Skip to main content

Analysis output formats

The execute endpoints return results in one of two formats: JSON (the default) or CSV (by appending .csv to the path). The request body is identical in both cases; only the response differs.

JSON response (default)​

Each series in the result carries its calculated data as a three-dimensional cube. The dimensions are always, in this order: metric, date, perspective.

"data": {
  "dimensions": ["metric", "date", "perspective"],
  "coordinates": {
    "metric": ["buzz"],
    "date": ["2024-01-01", "2024-01-02", "…"],
    "perspective": [
      "volume", "score", "positives", "negatives",
      "neutrals", "positives_neutrals", "negatives_neutrals"
    ]
  },
  "values": [
    [
      [503.0, 12.4, 11.2, 7.7, 72.4, 83.6, 80.1],
      [511.0, 12.9, 11.8, 6.9, 67.8, 79.6, 74.6],
      "…"
    ]
  ]
}
  • dimensions — the axis order.
  • coordinates — the labels along each axis (metric sorted alphabetically by metric name, not in the order of metrics_score_types; date as YYYY-MM-DD; perspective always the same seven, in the order shown).
  • values — nested arrays indexed values[metric][date][perspective]. So values[0][3][1] is the score (perspective index 1) of the first metric on the fourth date.

The seven perspectives give the headline figure plus the components behind it:

PerspectiveMeaning
volumeBase size (respondents behind the figure)
scoreThe headline score, given the chosen score type and scoring
positivesShare of positive responses
negativesShare of negative responses
neutralsShare of neutral responses
positives_neutralsPositives and neutrals combined
negatives_neutralsNegatives and neutrals combined

Dates with no data return null in the corresponding positions of values.

CSV output​

Append .csv to any execute path (e.g. POST /v1/analyses/execute.csv) to receive the same data as a flat CSV file (Content-Type: text/csv) — convenient for spreadsheets and data-warehouse loads.

The file has a header row, then one row per date, per metric, per series. Columns, in order:

date, analysis_id, region, sector_id, brand_id, custom_sector_uuid,
query_id, query_index, metric,
volume, score, positives, negatives, neutrals,
positives_neutrals, negatives_neutrals
  • The identity columns (region, sector_id, brand_id, custom_sector_uuid) are populated only where they apply to that series' entity type, and left blank otherwise.
  • query_id and query_index correspond to id and query_index in the JSON response, so each row traces back to the query that produced it.
  • The seven value columns match the seven perspectives above.

Which to use​

  • JSON for programmatic use where you will chart or transform the data.
  • CSV (.csv suffix) for quick pulls into spreadsheets/warehouses.
  • For a formatted file download (Excel or CSV with filename), use the export endpoint instead.