Oxford Economics Cookies

This website uses cookies to give you a better experience. If you continue with your current settings, we'll assume that you agree to receive all cookies from Oxford Economics website. If you don't agree and would like to remove the cookies created by this website you can do it by following these steps.

A leader in global forecasting and quantitative analysis, with the world’s only fully integrated economic model and 200 full-time economists and analysts, Oxford Economics is a trusted advisor to corporate and government decision-makers. We help our clients track, analyse, and model country, industry and urban trends around the world.

Subscription Services

A deep portfolio of research tools to assess the impact of macro events across more than 200 countries, including regularly-updated economic briefings, forecasts, and scenarios. Find out more.

A complete industry forecasting and analysis service with continuous updates for 74 countries and 26 commodities. Find out more.

The most complete set of forecasts available for cities and sub-regions around the world. Find out more.

Techlabs

API guide for the Global Data Workstation

Select users now have API access to the Global Data Workstation. Create custom saved selections programmatically, run them against any of your subscribed databanks, or integrate Oxford Economics’ data into applications like Tableau and Microsoft Power BI.

Getting an API key

To request an API key, please contact us using the Helpdesk. Eligibility for API provisioning depends on your organisation’s subscription. The key provided will be tied to a new, separate technical user account, which will maintain the same subscription profile as your organisation’s master account.

Endpoints

Each of the endpoints below returns a JSON object containing the corresponding requested data. Most require a valid API token and each can take optional GET and POST data to specify existing selections or databanks.

/Databank

Fetch information about the available Global Workstation databanks. This includes things like the start and end year of availability, the relevant corresponding indicator and location trees, and whether your user account has access.

1. GET /api/databank returns a JSON list of databanks with the details listed above.

2. POST /api/download?includemetadata={true/false} returns a JSON object with the data described by the selection provided in the request body. Click here for a breakdown of the selection request dictionary below. Note: you can opt to append paging options to either of the above methods via &page={page number}&pagesize={size} where pagesize dictates the number of elements on each page.

/FileDownload, /QueueDownload

Run and download a sample selection as either an Excel or CSV file. Depending on the expected size of the requested dataset and demand on our servers, /FileDownload might not return immediately. For this reason, we have included the /QueueDownload functionality, which allows the user to submit a request and then later poll for readiness.

1. GET /api/filedownload/{id} returns a JSON object based on the saved selections provided in the controller dictionary in the request body.

/Users

Gets your user data or create a new session by logging in.

1. GET /api/users/{id} returns a JSON object of user information with the ContactId provided, including a list of available saved selections. If id is set to “me”, this endpoint will return information for the user with the API key in the request header.

Key request dictionaries

Note that for the purpose of describing these dictionaries, the ( and ) characters indicate a choice and should be omitted in practice. For example, format: ("csv", "excel") indicates a choice between the strings csv and excel, so in practice this might look like format: "csv" or format: "excel".

In contrast, the [ and ] characters indicate an array and must not be omitted.

User credentials

User credentials layout:

{
Username: string,
Password: string
}

Example credentials:

{
Username: "john@example.com",
Password: "example_password"
}

Key response dictionaries

Note that for the purpose of describing these dictionaries, the ( and ) characters indicate a choice and should be omitted in practice. For example, format: ("csv", "excel") indicates a choice between the strings csv and excel, so in practice this might look like format: "csv" or format: "excel".

In contrast, the [ and ] characters indicate an array and must not be omitted.

Selection

This is the same as the selection dictionary in the request body. However, the response version always includes fields that are otherwise optional in the request. These include: LastUpdate, ContactId, ShareCodeId, and IsDataFeed.

Measure codes

Several of these request and response objects have a MeasureCode field. This value describes how the annual data is represented. The available options are:

L - Level values

PY - Percentage difference year over year

DY - Difference year over year

P - Percentage difference quarter over quarter

D - Difference quarter over quarter

GR - Annualized growth rate

Conventions, limits, and access

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

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.

A note about redirects

The File Download and Queue Download endpoints employ a redirect response to indicate successful completion and to pass along the newly generated download URL. Any client-side API call must expose this redirect URL (i.e. the download URL). However, in many web browsers this is will not be possible because of CORS restrictions. Therefore, setting up an intermediary application is necessary to make these calls and forward along the redirect URL. In our example code, we have included a simple Webtask script (js/file-download.js) to indicate one way this can be done.

Webtasks are one method for launching simple, lightweight web applications like this, so your code can run remotely without the need to configure server hardware or software. This particular framework uses Javascript and a wide range of NPM modules. More on Webtasks at https://webtask.io/.

Downloading entire databanks

In most circumstances, narrowly-defined selections are the best and quickest method to download data with the API. However, in some cases it may be necessary to fetch everything all at once. The way to do this is nearly identical to any other download but for the following two conditions:

The Regions and Variables fields in the selection dictionary are assigned empty lists (see example below).

There is a hard upper limit on the number of rows of data that can be downloaded in a given page. In fact, if employing the method described in this section, we recommend using a page size of 5000 elements.