API

(For coders)

Computer programs can use the HXL Proxy as if it were an Application programming interface (API).

There are two basic URL patterns available (substitute a different domain if you are using a local copy of the proxy):

https://proxy.hxlstandard.org/data.<ext>
https://proxy.hxlstandard.org/data/download/<basename>.<ext>

The ext portion may be either "csv" for CSV data, or "json" for JSON data. In the second form, you can chose any custom download filename by setting the basename appropriately, e.g. "2016-burundi-3w".

Parameters

HTTP parameter	Required	Description	Example
url	yes	URL of the original dataset (see Special URL handling).	http://example.org/data.csv
sheet	no	Zero-based index of the tab to use from an Excel workbook	1
recipe	no	A [[JSON data recipe	JSON recipes]] for transforming the data.
force	no	If "on", skip input and output [[caching	Caching]].
strip-headers	no	If "on", do not include text headers above the HXL hashtag row. This will ensure that there is only a single row of headers (the hashtags), for database import, etc.	on
max-rows	no	Maximum number of rows to display/download (0 or more). If not specified, HTML display will be limited to 5,000 rows, and CSV/JSON download will be unlimited.	1000

You may optionally also include the form parameters from the interactive Recipe page if you wish. The HXL Proxy will read the recipe parameter first, then append any form-based filters after it.

Examples

All examples in this section use the UNHCR Persons of Concern dataset, which is available with HXL hashtags.

The JSON recipes are included in the URLs without extra whitespace, but formatted for readability below.

Persons of concern resident in Jordan

In CSV format, downloading as "data.csv":

https://beta.proxy.hxlstandard.org/data.csv?url=http%3A%2F%2Fpopstats.unhcr.org%2Fen%2Fpersons_of_concern.hxl&recipe={%22filter%22:%22with_rows%22,%22queries%22:%22country%2Bresidence=jordan%22}

Embedded recipe:

{ 
  "filter": "with_rows", 
  "queries": "country+residence=jordan"
}

Persons of concern coming from Afghanistan during or after 2001

In CSV format, downloading as "data.csv":

https://beta.proxy.hxlstandard.org/data.csv?url=http%3A%2F%2Fpopstats.unhcr.org%2Fen%2Fpersons_of_concern.hxl&recipe=[{%22filter%22:%22with_rows%22,%22queries%22:%22country%2Borigin=afghanistan%22},{%22filter%22:%22with_rows%22,%22queries%22:%22date%3E=2001%22}]

Embedded recipe:

[
  { 
    "filter": "with_rows", 
    "queries": "country+residence=afghanistan"
  },
  {
    "filter": "with_rows",
    "queries": "date>=2001"
  }
]

Persons of concern resident in Canada, by year

In JSON format, downloading as "ca-refugees-by-year.json":

URL: https://beta.proxy.hxlstandard.org/data/download/ca-refugees-by-year.json?url=http%3A//popstats.unhcr.org/en/persons_of_concern.hxl&recipe=%5B%7B%22filter%22%3A%22with_rows%22%2C%22queries%22%3A%22country%2Bresidence%3Dcanada%22%7D%2C%7B%22filter%22%3A%22count%22%2C%22patterns%22%3A%22date%22%2C%22aggregate_pattern%22%3A%22affected%2Brefugees%22%7D,{%22filter%22:%22with_columns%22,%22whitelist%22:%22date%2Byear,meta%2Bsum%22},{%22filter%22:%22rename_columns%22,%22specs%22:[%22meta%2Bsum:Total%20refugees%23affected%2Brefugees%22]}%5D

Embedded recipe:

[
  {
    "filter": "with_rows",
    "queries": "country+residence=canada"
  },
  {
    "filter": "count",
    "patterns": "date",
    "aggregate_pattern": "affected+refugees"
  },
  {
    "filter": "with_columns",
    "whitelist": "date+year,meta+sum"
  },
  {
    "filter": "rename_columns",
    "specs": ["meta+sum:Total refugees#affected+refugees"]
  }
]