Conventions

All text should be encoded UTF-8 except where otherwise specified.

Field Types

The following types exist for fields in the API.

Name Description
integer 0 or greater integer sent without quotes
string UTF-8 character string surrounded in quotes
boolean true or false
object A map of string key & value pairs
array A list of strings, e.g. [“a”, “b”, “c”]

Parameters

Parameters for GET requests should be passed in the query string. Parameters for POST and PATCH requests should be passed in a JSON-encoded body, with header Content-Type: application/json set. JSON bodies should be a top-level object with parameters under the key data, e.g.:

  {
    "data": {
      "param1": "foo",
      "param2": "bar"
    }
  }

Dates

Parameter type: date

Since JSON does not have a built-in date type, dates should be passed as strings in ISO 8601 (YYYY-mm-dd) format.

Locations

Countries

Parameter type: country

Country locations should be passed as JSON strings using ISO 3166-1 alpha-2 format (standard 2-letter codes).

U.S. States and Subdivisions

Parameter type: subdiv

U.S. domestic subdivisions (e.g. U.S. States) should be passed as JSON strings using the 2 character abbreviations defined by the Geographic Names Information System’s National Geographic Names Data Compilation Program. These abbreviations are also codified under ISO 3166-2:US.

Foreign Subdivisions

Parameter type: subdiv

Foreign subdivisions, where available, should be passed as JSON strings using the abbreviations specified by ISO 3166-2.

Responses

Except where otherwise specified, response bodies will be a top-level JSON object with the returned resource(s) under the data key.