API Databank – Conventions and Limits
Conventions
The following list describes common conventions used by our API and should help to inform the construction of valid HTTP requests:
- The ending/character can be included or omitted as preferred from the request URL. For example:
- GET https://services.oxfordeconomics.com/api/databank is functionally the same as…
- GET https://services.oxfordeconomics.com/api/databank/.
- URL paths are not case sensitive.
- Field names (i.e. in request queries or bodies) are case sensitive. For example:
- GET /api/tree/Locations_{id} might be a valid URL provided an ID is inserted.
- However, GET /api/tree/locations_{id} (note the lower-case “L”) would be invalid.
- Field names use PascalCase. I.e. the first letter of each word is capitalized, including for the first word, and there are no spaces or underscores.
- Success or failure of an API call is indicated by the HTTP status. For example, an error response of 404 page not found might indicate that a selection could not be found with the ID provided. 200 OK is returned following successful requests.
- Query and body parameters that are included unnecessarily are ignored.
Rate limits
The Global Data Workstation imposes rate limits in order to prevent abuse and keep the service fast and accessible to everyone. Currently, it doesn’t impose a hard limit. I.e. there is no policy that will drop API requests after a certain limit is reached. However, this is subject to change, in which case requests made beyond this threshold will be rejected with a 503 Service Unavailable HTTP status.
We do employ a soft limit, which is currently around 60 requests per minute. If this limit has been reached, then a delay will be imposed on subsequent requests in order to bring down the number of requests into the rate limit window. Please note: this rate is not guaranteed and may fluctuate with server load.
The following HTTP headers are included in every API response:
- Rate-Limit-60: Unthrottled
- Rate-Limit-60-Status: Unthrottled
- Rate-Limit-60-Window: 60
- Rate-Limit-60-RequestCount: 0
- Rate-Limit-60-RequestLimit: 60
Page limits
The Global Data Workstation limits the maximum number of data rows returned in a single API call to 20,000. To retrieve more data than this, you will need to use paging. See below on ‘Downloading entire databanks’.
Authorisation and variables access
Each API key is authenticated by an organisation’s subscription and provides access only to databanks and variables authorised in the subscription. Any attempt to circumvent this authorisation and/or use another organisation’s API key will be in breach of the terms and conditions of your subscription contract. The API does not return data for unauthorised variable requests, and it is throttled to prevent abuse and protect the main service.