David Megginson edited this page Oct 29, 2016 · 13 revisions

(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"]
  }
]
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.