Skip to main content

Which routes offer it

On these routes format=json is the default. Every other route answers JSON only: leave format out there, because any value, json included, is a 400 whose message lists the routes above.

What you get

  • Content-Type: text/csv; charset=utf-8, one header row, then one line per item on the page, in the standard CSV format (lines end in a carriage return and a line feed; a cell containing a comma, a quote or a line break is quoted).
  • A figure becomes four columns: its value, then _band, _n and _low_sample. visibility becomes visibility, visibility_band, visibility_n and visibility_low_sample. The value never travels without its band and sample size, so a chart drawn from the file can still show them.
  • Other objects become prefixed columns: a row’s brand becomes brand_id, brand_name and brand_own.
  • A list becomes one cell, its values joined with |.
  • An empty value is an empty cell. A figure with no answers behind it has an empty value cell and 0 in its _n column.
  • Columns are the union of the page’s rows, in the order first seen, so a row with a field the first row lacks keeps its column.
  • An empty page is an empty file, with no header row: there is no row to take the columns from.
The CSV carries less than the JSON: a figure’s delta, within_noise, unit and state are not in it, and neither is the response’s scope. Keep the query you sent beside the file so you know what it counted.

Text that looks like a formula

Brand names, prompts, URLs and search queries are other people’s text. A spreadsheet would run a cell that starts with =, +, - or @ as a formula, so any text cell that starts with one of those (or with a tab or a carriage return) is written with a ' in front. Numbers are written as numbers, so a negative number stays a number.

Paging a CSV

The next page is not in the body; it is in two response headers:
  • Citino-Next-Cursor: the cursor for the next page. Absent on the last page.
  • Link: the next page as a relative reference with rel="next", for clients that follow links.
Request the next page with the same parameters plus cursor, and append its rows without its header line.
Each page’s columns come from that page’s own rows. The samples above drop every later page’s header line; a careful job checks that it matches the first page’s before appending, and stops if it does not.

Reports

Dimensions, filters and budgets.

Pagination

Cursors and why they belong to their query.

Metric objects

What the four figure columns mean.

Pulling data nightly

A daily job that writes rows to a warehouse.