HDX Quick Charts use JSON configuration files to define the different kinds of charts to offer to users for HXL-tagged data. There are three related formats:

A bite, representing a single chart definition.
A recipe, representing a collection of bites from which the user can choose.
A cookbook, containing a selection of recipes.

You can experiment with making your own bites interactively in the HDX Quick Charts Sandbox.

Bites

A simple JSON bite looks like this:

{
  "name": "orgs",
  "type":"key figure",
  "ingredient": {
    "valueColumn": "#org",
    "aggregateFunction": "distinct-count"
  },
  "uiProperties": {
    "title": "Organisations",
    "description": "Number of organisations deployed."    "unit": "orgs",
    "numberFormat": "us"
  } 
}

This will generate a key-figure chart showing the number of unique organisations mentioned in the first column with the HXL hashtag “#org”.

Here is a slightly more-complex example, creating a chart (bar or pie, chosen automatically) that shows the number of unique organisations for each admin1 subdivision (“#adm1”):

{
  "type":"chart",
  "ingredient": {
    "aggregateColumn": "#adm1"
    "valueColumn": "#org",
    "aggregateFunction": "distinct-count"
  },
  "uiProperties": {
    "title": "Organisations",
    "unit": "orgs",
    "numberFormat": "us"
  }
}

bite properties

name	The internal reference name for the bite (not displayed).
title	The display title for the Quick Chart.
description	The display description for the Quick Chart.
type	Type of chart to display. key figure: a single numeric indicator (e.g. total population, number of organisations) chart: a chart of numeric values (e.g. population by admin1, organisations by sector) timeseries: data on a timeline (e.g. number of refugees from 2013 to 2023) For chart, Quick Charts will choose the graph type (pie or bar) automatically, based on the number of distinct values in aggregateColumn (see below).
ingredient	Definition of the data to use in the chart (see below).
uiProperties	Definition of how the chart should be displayed (see below).

“ingredient” object fields

aggregateColumn	A HXL tag pattern identifying the reference column for aggregation (chart and timeseries only).
dateColumn	A HXL tag pattern identifying the column to use for dates (timeseries only).
valueColumn	A HXL tag pattern identifying the column containing values.
aggregateFunction	The aggregation function to apply to valueColumn. If the type is “chart” or “timeseries”, the aggregations will apply to each unique value of aggregateColumn. sum: add all of the values together (numbers only) average: calculate the mean of the values (numbers only) count: count all of the values, including duplicates (numbers, dates, or strings) distinct-count: count all of the unique values
filterWith	A filter for rows to include in the chart: it should be a list of JSON objects, where the keys are HXL tag patterns and the values are either literal values that must appear in rows to include, or the pseudo values “$MAX$” (for the largest value) or “$MIN” (for the smallest value). For example, this filter would include only rows for the latest year (assuming it appears in a column with the HXL hashtag spec “#date+year”). `"filterWith:" [ { "#date+year": "$MAX$" } ]`
filterWithout	Like filterWith, except that it’s a filter for rows to exclude from the chart.

uiProperties object fields

title	The display title for the Quick Chart (overrides top level)
description	The display description for the Quick Chart (overrides top level)
unit	The label to place under the number for a key figure
numberFormat	The format to use for numbers: us: English format (“,” as thousands separator) de: Continental European format (“.” as thousands separator) If not provided, the format will be standard computer number format, with no thousands separator and “.” as the decimal separator.
showGrid	Show a grid behind a bar chart or timeseries if true.
swapAxis	For a bar graph, place the labels along the Y-axis if true, or along the X-axis if false.
color	Hex RGB color code for a bar chart, e.g. “#FFFF00” for yellow.
sortingByValue1	Sort a bar chart by values. Use “ASC” for ascending, or “DESC” for descending.
sortingByCategory1	Sort a bar chart by categories (labels in the aggregateColumn). Use “ASC” for ascending, or “DESC” for descending. Note: this will work only if sortingByValue1 is present and explicitly set to null.

Recipes

Recipes generate a list of bites that the user can choose from, based on the data available in the source dataset. It is similar to a Bite, except that “ingredient” changes to “ingredients”, and inside ingredients most of the fields become plural: aggregateColumns, dateColumns, valueColumns, and aggregateFunctions (but not filtersWith or filtersWithout). Each of this contains a list HXL tag patterns, for generating bites that the user may choose (depending on which columns appear in the source data). This example will provide options for the number of orgs, activities, sectors, or subsectors grouped by region, country, or 5 admin levels — up to 28 different bites, depending on what’s present in the source data:

Cookbooks

Cookbooks contain one or more recipes and a list of HXL tag patterns; if there are columns in the source data matching all of the tag patterns, then these recipes will be available to the user.

name	The internal reference name for the cookbook (not displayed).
title	Cookbook title to display.
type	Always “cookbook”.
columns	A list of HXL tag patterns that should appear in the source data for these recipes to apply.
recipes	A list of recipes to make available.
numberFormat	The format to use for numbers: us: English format (“,” as thousands separator, “.” as decimal) de: Continental European format (“ ” as thousands separator, “,” as decimal) If not provided, the format will be standard computer number format, with no thousands separator and “.” as the decimal separator.

HDX

Quick Charts JSON formats