layout: default title: "Usage Guide | Timeseries SVG" description: "Data input formats and usage examples for timeseries-sparklines library."

Usage Guide

The timeseries-sparklines library automatically normalizes various input formats. Use the format that best matches your data source.

List of Dicts (Standard Format)

Recommended for most use cases. Uses d for date and v for value.

[
  {"d": "2024-01-01", "v": 100.0},
  {"d": "2024-01-02", "v": 102.5},
  {"d": "2024-01-03", "v": 101.2},
  {"d": "2024-01-04", "v": 105.0},
  {"d": "2024-01-05", "v": 103.8}
]

List of Lists

Each inner list is [date, value]:

[
  ["2024-01-01", 100.0],
  ["2024-01-02", 102.5],
  ["2024-01-03", 101.2],
  ["2024-01-04", 105.0]
]

Dict with Date Keys

Date strings as keys, values as the data:

{
  "2024-01-01": 100.0,
  "2024-01-02": 102.5,
  "2024-01-03": 101.2,
  "2024-01-04": 105.0
}

Simple Value List

Auto-generates dates as "day-0", "day-1", etc. Best for sparklines where dates don't matter:

[100.0, 102.5, 101.2, 105.0, 103.8, 107.0]

Custom Keys

If your data uses different key names, specify them:

[
  {"date": "2024-01-01", "price": 100.0},
  {"date": "2024-01-02", "price": 102.5},
  {"date": "2024-01-03", "price": 101.2}
]

Use with:

renderer.render(data, date_key="date", value_key="price")

Nested Format (JSONB from databases)

Common format for database JSONB storage - the library extracts the array automatically:

{
  "history": [
    {"d": "2024-01-01", "v": 100.0},
    {"d": "2024-01-02", "v": 102.5},
    {"d": "2024-01-03", "v": 101.2}
  ]
}

Chart Types

Line Charts

Use TimeSeriesChartRenderer for traditional line charts with axes and grid lines:

from timeseries_svg import TimeSeriesChartRenderer

renderer = TimeSeriesChartRenderer(width=760, height=320)
svg = renderer.render(data, period="5D", title="Price History")

With custom y-axis label and offset:

renderer = TimeSeriesChartRenderer(
    width=760,
    height=320,
    y_axis_label="$",
    y_axis_offset=0.1
)
svg = renderer.render(data, period="5D", title="Price History")

Bar Charts

Use BarChartRenderer for vertical bar charts:

from timeseries_svg import BarChartRenderer

renderer = BarChartRenderer(width=760, height=320)
svg = renderer.render(data, period="1M", title="Temperature by Month")

With custom y-axis label and offset:

renderer = BarChartRenderer(
    width=760,
    height=320,
    y_axis_label="°F",
    y_axis_offset=0.1
)
svg = renderer.render(data, period="1M", title="Temperature by Month")

API usage (specify chart_type: "bar"):

POST /chart-raw
{
  "data": [...],
  "chart_type": "bar",
  "period": "1M",
  "title": "Temperature by Month"
}

Chart Examples by Period

Chart data is filtered by time window from the most recent data point:

5D (5 Calendar Days)

[
  {"d": "2024-01-08", "v": 160},
  {"d": "2024-01-09", "v": 148.5},
  {"d": "2024-01-10", "v": 145.0},
  {"d": "2024-01-11", "v": 142.5},
  {"d": "2024-01-12", "v": 146.0}
]

1M (30 Calendar Days)

[
  {"d": "2024-01-02", "v": 160},
  {"d": "2024-01-03", "v": 148.5},
  {"d": "2024-01-04", "v": 145.0},
  {"d": "2024-01-05", "v": 142.5},
  {"d": "2024-01-08", "v": 146.0},
  {"d": "2024-01-09", "v": 144.5},
  {"d": "2024-01-10", "v": 148.0},
  {"d": "2024-01-11", "v": 151.5},
  {"d": "2024-01-12", "v": 149.0},
  {"d": "2024-01-16", "v": 152.0},
  {"d": "2024-01-17", "v": 155.5},
  {"d": "2024-01-18", "v": 153.0},
  {"d": "2024-01-19", "v": 149.5},
  {"d": "2024-01-22", "v": 147.0},
  {"d": "2024-01-23", "v": 150.5},
  {"d": "2024-01-24", "v": 154.0},
  {"d": "2024-01-25", "v": 157.5},
  {"d": "2024-01-26", "v": 155.0},
  {"d": "2024-01-29", "v": 158.5},
  {"d": "2024-01-30", "v": 162.0},
  {"d": "2024-01-31", "v": 160.0}
]

7M (AAPL from market_snapshot_stocks.price_history)

[
  {"d": "2025-10-06", "v": 256.69},
  {"d": "2025-10-07", "v": 256.48},
  {"d": "2025-10-08", "v": 258.06},
  {"d": "2025-10-09", "v": 254.04},
  {"d": "2025-10-10", "v": 245.27},
  {"d": "2025-10-13", "v": 247.66},
  {"d": "2025-10-14", "v": 247.77},
  {"d": "2025-10-15", "v": 249.34},
  {"d": "2025-10-16", "v": 247.45},
  {"d": "2025-10-17", "v": 252.29},
  {"d": "2025-10-20", "v": 262.24},
  {"d": "2025-10-21", "v": 262.77},
  {"d": "2025-10-22", "v": 258.45},
  {"d": "2025-10-23", "v": 259.58},
  {"d": "2025-10-24", "v": 262.82},
  {"d": "2025-10-27", "v": 268.81},
  {"d": "2025-10-28", "v": 269.0},
  {"d": "2025-10-29", "v": 269.7},
  {"d": "2025-10-30", "v": 271.4},
  {"d": "2025-10-31", "v": 270.37},
  {"d": "2025-11-03", "v": 269.05},
  {"d": "2025-11-04", "v": 270.04},
  {"d": "2025-11-05", "v": 270.14},
  {"d": "2025-11-06", "v": 269.77},
  {"d": "2025-11-07", "v": 268.47},
  {"d": "2025-11-10", "v": 269.43},
  {"d": "2025-11-11", "v": 275.25},
  {"d": "2025-11-12", "v": 273.47},
  {"d": "2025-11-13", "v": 272.95},
  {"d": "2025-11-14", "v": 272.41},
  {"d": "2025-11-17", "v": 267.46},
  {"d": "2025-11-18", "v": 267.44},
  {"d": "2025-11-19", "v": 268.56},
  {"d": "2025-11-20", "v": 266.25},
  {"d": "2025-11-21", "v": 271.49},
  {"d": "2025-11-24", "v": 275.92},
  {"d": "2025-11-25", "v": 276.97},
  {"d": "2025-11-26", "v": 277.55},
  {"d": "2025-11-28", "v": 278.85},
  {"d": "2025-12-01", "v": 283.1},
  {"d": "2025-12-02", "v": 286.19},
  {"d": "2025-12-03", "v": 284.15},
  {"d": "2025-12-04", "v": 280.7},
  {"d": "2025-12-05", "v": 278.78},
  {"d": "2025-12-08", "v": 277.89},
  {"d": "2025-12-09", "v": 277.18},
  {"d": "2025-12-10", "v": 278.78},
  {"d": "2025-12-11", "v": 278.03},
  {"d": "2025-12-12", "v": 278.28},
  {"d": "2025-12-15", "v": 274.11},
  {"d": "2025-12-16", "v": 274.61},
  {"d": "2025-12-17", "v": 271.84},
  {"d": "2025-12-18", "v": 272.19},
  {"d": "2025-12-19", "v": 273.67},
  {"d": "2025-12-22", "v": 270.97},
  {"d": "2025-12-23", "v": 272.36},
  {"d": "2025-12-24", "v": 273.81},
  {"d": "2025-12-26", "v": 273.4},
  {"d": "2025-12-29", "v": 273.76},
  {"d": "2025-12-30", "v": 273.08},
  {"d": "2025-12-31", "v": 271.86},
  {"d": "2026-01-02", "v": 271.01},
  {"d": "2026-01-05", "v": 267.26},
  {"d": "2026-01-06", "v": 262.36},
  {"d": "2026-01-07", "v": 260.33},
  {"d": "2026-01-08", "v": 259.04},
  {"d": "2026-01-09", "v": 259.37},
  {"d": "2026-01-12", "v": 260.25},
  {"d": "2026-01-13", "v": 261.05},
  {"d": "2026-01-14", "v": 259.96},
  {"d": "2026-01-15", "v": 258.21},
  {"d": "2026-01-16", "v": 255.53},
  {"d": "2026-01-20", "v": 246.7},
  {"d": "2026-01-21", "v": 247.65},
  {"d": "2026-01-22", "v": 248.35},
  {"d": "2026-01-23", "v": 248.04},
  {"d": "2026-01-26", "v": 255.41},
  {"d": "2026-01-27", "v": 258.27},
  {"d": "2026-01-28", "v": 256.44},
  {"d": "2026-01-29", "v": 258.28},
  {"d": "2026-01-30", "v": 259.48},
  {"d": "2026-02-02", "v": 270.01},
  {"d": "2026-02-03", "v": 269.48},
  {"d": "2026-02-04", "v": 276.49},
  {"d": "2026-02-05", "v": 275.91},
  {"d": "2026-02-06", "v": 278.12},
  {"d": "2026-02-09", "v": 274.62},
  {"d": "2026-02-10", "v": 273.68},
  {"d": "2026-02-11", "v": 275.5},
  {"d": "2026-02-12", "v": 261.73},
  {"d": "2026-02-13", "v": 255.78},
  {"d": "2026-02-17", "v": 263.88},
  {"d": "2026-02-18", "v": 264.35},
  {"d": "2026-02-19", "v": 260.58},
  {"d": "2026-02-20", "v": 264.58},
  {"d": "2026-02-23", "v": 266.18},
  {"d": "2026-02-24", "v": 272.14},
  {"d": "2026-02-25", "v": 274.23},
  {"d": "2026-02-26", "v": 272.95},
  {"d": "2026-02-27", "v": 264.18},
  {"d": "2026-03-02", "v": 264.72},
  {"d": "2026-03-03", "v": 263.75},
  {"d": "2026-03-04", "v": 262.52},
  {"d": "2026-03-05", "v": 260.29},
  {"d": "2026-03-06", "v": 257.46},
  {"d": "2026-03-09", "v": 259.88},
  {"d": "2026-03-10", "v": 260.83},
  {"d": "2026-03-11", "v": 260.81},
  {"d": "2026-03-12", "v": 255.76},
  {"d": "2026-03-13", "v": 250.12},
  {"d": "2026-03-16", "v": 252.82},
  {"d": "2026-03-17", "v": 254.23},
  {"d": "2026-03-18", "v": 249.94},
  {"d": "2026-03-19", "v": 248.96},
  {"d": "2026-03-20", "v": 247.99},
  {"d": "2026-03-23", "v": 251.49},
  {"d": "2026-03-24", "v": 251.64},
  {"d": "2026-03-25", "v": 252.62},
  {"d": "2026-03-26", "v": 252.89},
  {"d": "2026-03-27", "v": 248.8},
  {"d": "2026-03-30", "v": 246.63},
  {"d": "2026-03-31", "v": 253.79},
  {"d": "2026-04-01", "v": 255.63},
  {"d": "2026-04-02", "v": 255.92},
  {"d": "2026-04-06", "v": 258.86},
  {"d": "2026-04-07", "v": 253.5},
  {"d": "2026-04-08", "v": 258.9},
  {"d": "2026-04-09", "v": 260.49},
  {"d": "2026-04-10", "v": 260.48},
  {"d": "2026-04-13", "v": 259.2},
  {"d": "2026-04-14", "v": 258.83},
  {"d": "2026-04-15", "v": 266.43},
  {"d": "2026-04-16", "v": 263.4},
  {"d": "2026-04-17", "v": 270.23},
  {"d": "2026-04-20", "v": 273.05},
  {"d": "2026-04-21", "v": 266.17},
  {"d": "2026-04-22", "v": 273.17},
  {"d": "2026-04-23", "v": 273.43},
  {"d": "2026-04-24", "v": 271.06},
  {"d": "2026-04-27", "v": 267.61},
  {"d": "2026-04-28", "v": 270.71},
  {"d": "2026-04-29", "v": 270.17},
  {"d": "2026-04-30", "v": 271.35},
  {"d": "2026-05-01", "v": 280.14},
  {"d": "2026-05-04", "v": 276.83},
  {"d": "2026-05-05", "v": 284.18},
  {"d": "2026-05-06", "v": 287.51}
]