API v1

The API provides access to downloading the free datasets and the datasets you are subscribed to.

Contact us if you need help using the API to get the data you need.

Getting data with GET requests

Download as much or as little data as you like through customized URLs made through GET requests. Simply follow these steps:

Authorization

In order to access either the free datasets or the datasets you are subscribed to, you must provide your API key in an Authorization header or as an argument to the apikey parameter.

Get an API key by signing up for Public Data Market for free.

If authorization fails, you will receive an HTTP status error code (401).

Data format

To get data as a JSON array (the default), make a GET request to the following URL, passing your API key to the apikey parameter:

https://publicdatamarket.com/api/v1/{username}/{dataset}?apikey=YOURAPIKEYHERE

{username} and {dataset} are found in the URL that hosts the dataset. For example, the free dataset of contact information of all Hong Kong Access to Information Officersat https://publicdatamarket.com/hkdata/accessgovhk/ can be accessed through the API via the following URL (try it now!):

https://publicdatamarket.com/api/v1/hkdata/accessgovhk?apikey=YOURAPIKEYHERE

To get data in a JSON lines or CSV format, pass jsonlines or csv as the argument to the dataformat parameter, e.g.:

https://publicdatamarket.com/api/v1/{username}/{dataset}?apikey=YOURAPIKEYHERE&dataformat=csv

Limits and pagination

Only up to 10,000 data points are returned at a time. If you want to download less, append &limit= and the desired number to the end of the URL. For example, to download only 5 contact details from the dataset above, use:

https://publicdatamarket.com/api/v1/hkdata/accessgovhk?apikey=YOURAPIKEYHERE&limit=5

To download more than 10,000 rows of data, or simply to facilitate downloading smaller chunks of data, you can make multiple requests, each time starting the downloading further down the dataset, using the offset parameter, e.g. to download the next 5 contacts:

https://publicdatamarket.com/api/v1/hkdata/accessgovhk?apikey=YOURAPIKEYHERE&limit=5&offset=5

Filtering

You can filter the data by adding conditions on columns. For example, to get the details for the Hong Kong Access to Information officers with the email address `enquiry@epd.gov.hk` (there are currently 3, including obsolete details), use the URL parameter email (as that is the name of the column) and the argument eq.enquiry@epd.gov.hk (where eq stands for "equals", followed by a dot, followed by the email address to filter on):

https://publicdatamarket.com/api/v1/hkdata/accessgovhk?apikey=YOURAPIKEYHERE&email=eq.enquiry@epd.gov.hk

The full set of operators available is as follows:

Abbreviation

PostgreSQL equivalent

Meaning

eq

=

equals

gt

>

greater than

gte

>=

greater than or equal

lt

<

less than

lte

<=

less than or equal

neq

<> or !=

not equal

like

LIKE

LIKE operator (to avoid URL encoding you can use * as an alias of the percent sign % for the pattern)

ilike

ILIKE

ILIKE operator (to avoid URL encoding you can use * as an alias of the percent sign % for the pattern)

in

IN

one of a list of values, e.g. ?a=in.(1,2,3) – also supports commas in quoted strings like ?a=in.("hi,there","yes,you")

is

IS

checking for exact equality (null,true,false,unknown)

isdistinct

IS DISTINCT FROM

not equal, treating NULL as a comparable value

not

NOT

negates another operator

or

OR

logical OR

and

AND

logical AND

all

ALL

comparison matches all the values in the list

any

ANY

comparison matches any value in the list

Ordering

You can reorder the data using the argument order. It uses a comma-separated list of columns and directions, e.g.

https://publicdatamarket.com/api/v1/hkdata/accessgovhk?apikey=YOURAPIKEYHERE&order=latestdate.desc,department.asc

If no direction is specified then order is ascending by default.