Time Series Charts

Image-Charts has no date axis. A time series is an ordinary line chart. You send the values in chronological order with chd, then write the x-axis labels yourself with chxl. Nothing in the API parses a date, so the labels are plain text and the points are always spaced evenly.

How Do You Plot a Time Series?

Four parameters cover it: the chart type, the values, the axes you want drawn and the labels that go under them.

  1. Set cht=lc for a line chart.
  2. Send the values with chd=a:, oldest first. The a: format takes floating point numbers with no upper bound and scales the axis for you.
  3. Turn on the axes with chxt, where x names the bottom axis and y the left one. Most time series use chxt=x,y.
  4. Write the labels with chxl=0:|Jan|Feb|…, where 0 is the position of that axis in your chxt list.

https://image-charts.com/chart?cht=lc&chd=a:31,42,38,55,61,58,72,80,76,91,88,103&chs=700x300&chxt=x,y&chxl=0:%7CJan%7CFeb%7CMar%7CApr%7CMay%7CJun%7CJul%7CAug%7CSep%7COct%7CNov%7CDec&chls=3&chco=1F3B99&chg=1,1&chtt=Signups+per+month

Line chart of twelve monthly values with every month named under the x-axis
Twelve values and twelve labels. The order of the labels follows the order of the values, and the API does no date arithmetic of its own.

Fewer Labels Than Data Points

Twelve labels under twelve points is often too many to read at chart size. Give the axis fewer labels and Image-Charts spreads them out, padding the gaps with blank labels so the first and the last stay at the ends of the axis.

Four quarter labels over the same twelve monthly points come out as Q1, three blanks, Q2, three blanks, Q3, two blanks, Q4. You write four labels and the axis stays aligned with the data.

https://image-charts.com/chart?cht=lc&chd=a:31,42,38,55,61,58,72,80,76,91,88,103&chs=700x300&chxt=x,y&chxl=0:%7CQ1%7CQ2%7CQ3%7CQ4&chls=3&chco=1F3B99&chg=1,1&chtt=Signups+per+month

The same twelve monthly values labelled with four quarter marks spread along the x-axis
The data is unchanged. Only the four labels replace the twelve, and the spacing is worked out from the length of the longest series.

Naming an Axis Instead of Its Ticks

An axis given exactly one label uses it as the name of the axis rather than as a tick label. chxl=1:|Signups writes Signups alongside the second axis in the list instead of printing it next to a single tick. Add a second entry for the same axis and both become tick labels again.

https://image-charts.com/chart?cht=lc&chd=a:31,42,38,55,61,58,72,80,76,91,88,103&chs=700x300&chxt=x,y&chxl=0:%7CQ1%7CQ2%7CQ3%7CQ4%7C1:%7CSignups&chls=3&chco=1F3B99&chg=1,1

Line chart with quarter labels on the x-axis and the word Signups naming the y-axis
One chxl value carries both axes, four labels for axis 0 and a single name for axis 1.

Gaps in a Series

An underscore in place of a value marks that point as missing, so chd=a:31,42,_,55 leaves a hole in the line rather than drawing it down through zero. This matters on a time series more than anywhere else, because a month with no measurement is not a month with a value of zero.

https://image-charts.com/chart?cht=lc&chd=a:31,42,_,55,61,58,72,80&chs=700x260&chxt=x,y&chls=3&chco=1F3B99&chg=1,1&chtt=A+month+with+no+data

Line chart where the third point is missing, leaving a visible break in the line
The break sits between the second and the fourth point. An empty value between two commas does the same thing as the underscore.

Fixing the Value Axis

By default the value axis fits itself around the data, so the same URL rendered a month apart can frame its numbers differently. chxr=<axis_index>,<start>,<end> pins it instead, and a fourth number sets the distance between ticks. chxr=1,0,120,20 runs the second axis from 0 to 120 in steps of 20.

Writing the range backwards, as in chxr=1,120,0, turns the axis upside down, which is what you want for a rank or a position where 1 belongs at the top.

https://image-charts.com/chart?cht=lc&chd=a:31,42,38,55,61,58,72,80,76,91,88,103&chs=700x300&chxt=x,y&chxr=1,0,120,20&chxl=0:%7CQ1%7CQ2%7CQ3%7CQ4&chls=3&chco=1F3B99&chg=0,1

Line chart whose y-axis runs from zero to one hundred and twenty in steps of twenty
The axis now starts at zero and ends at a round number, so the same URL rendered next month still frames the data the same way.

Grid Lines

chg draws the grid. Its first two numbers are the x and y step sizes, and its third and fourth are a dash length and a gap length, as in chg=1,1,4,3.

The two step sizes work as switches rather than as spacings. Any value above 0 and below 100 turns that grid on, and Image-Charts draws the lines at the ticks it has already worked out, so chg=1,1 and chg=20,20 produce the same grid. Setting one of them to 0 leaves that half of the grid off, which is how chg=0,1 gives horizontal lines only.

https://image-charts.com/chart?cht=lc&chd=a:31,42,38,55,61,58,72,80,76,91,88,103&chs=700x300&chxt=x,y&chg=1,1,4,3&chxl=0:%7CQ1%7CQ2%7CQ3%7CQ4&chls=3&chco=1F3B99

Line chart with a dashed grid on both axes
Both grids on, drawn as four pixel dashes with three pixel gaps. A dashed grid stays behind the data instead of competing with it.

chl Is Not an Axis Parameter

The parameter that labels an axis is chxl. chl does something else. On a bar chart it labels the bars, on a pie chart it labels the slices, and on a line chart it leaves the axis alone. Sending your months in chl is the usual reason a time series comes back with a bare numeric x-axis. The reference documentation describes both.

Chart a Time Series

Build a Chart