Tech Labs | 14 Jun 2022

API Databank – Endpoints

Technology Team

Oxford Economics

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.

curl --request GET --url \
   https://services.oxfordeconomics.com/api/databank \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

2. GET /api/databank/{selection_id} returns a JSON object with databank information.

curl --request GET \
   --url https://services.oxfordeconomics.com/api/databank/{{databank_id}} \<br>
   --header 'api-key: {{api_key}}' \<br>
   --header 'content-type: application/json'

/Download

Request a download based on an existing selection Id or a well-formed selection provided in the POST body.

1. GET /api/download/{id} returns a JSON object based on the saved selection ID provided.

curl --request GET \
   --url 'https://services.oxfordeconomics.com/api/download/{{selection_id}} \<br>
 	?includemetadata=true&page=0&pagesize=5' \<br>
   --header 'api-key: {{api_key}}' \<br>
   --header 'content-type: application/json'

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.

curl --request POST \
   --url 'https://services.oxfordeconomics.com/api/download?includemetadata=true&page=0&pagesize=5' \<br>
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json' \
   --data '{
   "MeasureCode": "L",
   "IsTemporarySelection": true,
   "DatabankCode": "WDMacro",
   "Sequence": "EarliestToLatest",
   "GroupingMode": false,
   "TransposeColumns": null,
   "Order": "IndicatorLocation",
   "IndicatorSortOrder": "AlphabeticalOrder",
   "LocationSortOrder": "AlphabeticalOrder",
   "SortedColumnName": null,
   "SortedColumnOrder": null,
   "Format": 0,
   "LegacyDatafeedFileStructure": false,
   "Variables": [
        {
              "VariableCode": "CPI",
              "ProductTypeCode": "WMC",
              "MeasureCodes": [
                    "L"
              ]
        },
        {
              "VariableCode": "GDP$",
              "ProductTypeCode": "WMC",
              "MeasureCodes": [
                    "L",
                    "PY",
                    "DY"
              ]
        }
   ],
   "Regions": [
        {
              "DatabankCode": "WDMacro",
              "RegionCode": "GBR"
        },
        {
              "DatabankCode": "WDMacro",
              "RegionCode": "USA"
        }
   ],
      "ShareCodeId": null,
      "ListingType": "Private",
      "IsDatafeed": false,
      "StartYear": 2015,
      "EndYear": 2021,
      "Frequency": "Annual",
      "StackedQuarters": false
  }'

/FileDownload

Run and download a saved 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 (see below).

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

curl --request GET \
   --url https://services.oxfordeconomics.com/api/filedownload/{{selection_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

2. POST /api/filedownload returns a JSON object based on the saved selection ID provided. Click here to see the controller configuration dictionary below.

curl –request POST \
   --url https://services.oxfordeconomics.com/api/filedownload \
   --header 'api-key: {{api_key}}' \
  --header 'content-type: application/json'
--data '{
   "format": “csv”,
   "name": "download name",
   "selections": [
        {
              {{selection id}}
        },
 }'

/QueueDownload

Run and download a saved selection as either an Excel or CSV file. The API returns two URLs: ReadyUrl, which you can poll to see whether the download is ready; and URL, which you can download the data from once ready.

1. GET /api/queuedownload/{id} returns a JSON object containing URL for download and ReadyUrl for polling download readiness..

curl --request GET \
   --url https://services.oxfordeconomics.com/api/queuedownload/{{selection_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

2. POST /api/queuedownload returns a JSON object containing URL for download and ReadyUrl for polling download readiness.

<code> curl --request GET \<br>
   --url https://services.oxfordeconomics.com/api/queuedownload \<br>
   --header 'api-key: {{api_key}}' \<br>
   --header 'content-type: application/json'
--data '{
   "format": “csv”,
   "name": "download name",
   "selections": [
        {
              {{selection id}}
        },
 }'

/Region

Shows which regions are available for a given databank. This includes the RegionCode value, which you can use to build custom selections.

1. GET /api/region/{id} returns a JSON list object with the regions available for a given databank.

curl --request GET \
   --url https://services.oxfordeconomics.com/api/region/{{databank_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

/SavedSelections

Create saved selections, or access and update existing ones.

1. GET /api/savedselections/{id} returns a JSON object describing the selection at the ID provided, including things like start and end date and variables requested.

curl --request GET \
--url https://services.oxfordeconomics.com/api/savedselections/{{selection_id}} \
--header 'api-key: {{api_key}}' \
--header 'content-type: application/json'

2. PUT /api/savedselections/{id} takes a selection dictionary in the post body and updates the selection with the provided ID.

Note: this does not return the updated selection object.

curl --request PUT \
  --url https://services.oxfordeconomics.com/api/savedselections/{{selection_id}} \
  --header 'api-key: {{api_key}}' \
  --header 'content-type: application/json' \
  --data '{
  "Id": "{{selection_id}}",
  "SelectionType": "QuerySelection",
  "MeasureCode": "L",
  "IsTemporarySelection": false,
  "DatabankCode": "WDMacro",
  "Sequence": "EarliestToLatest",
  "GroupingMode": false,
  "TransposeColumns": null,
  "Order": "IndicatorLocation",
  "IndicatorSortOrder": "AlphabeticalOrder",
  "LocationSortOrder": "AlphabeticalOrder",
  "SortedColumnName": null,
  "SortedColumnOrder": null,
  "Format": 0,
  "LegacyDatafeedFileStructure": false,
  "Variables": [
    {
      "VariableCode": "CPI",
      "ProductTypeCode": "WMC",
      "MeasureCodes": [
        "L"
      ]
    },
    {
      "VariableCode": "GDP$",
      "ProductTypeCode": "WMC",
      "MeasureCodes": [
        "L",
        "PY",
        "DY"
      ]
    }
  ],
  "Regions": [
    {
      "DatabankCode": "WDMacro",
      "RegionCode": "GBR"
    },
    {
      "DatabankCode": "WDMacro",
      "RegionCode": "USA"
    }
  ],
  "ShareCodeId": null,
  "ListingType": "Private",
  "IsDatafeed": false,
  "Name": "Selection - (Updated yyyy/mm/dd)",
  "StartYear": 2015,
  "EndYear": 2021,
  "Frequency": "Annual",
  "StackedQuarters": false
}'

3. DELETE /api/savedselections/{id} deletes a user’s selection with the provided ID.

curl --request DELETE \
   --url https://services.oxfordeconomics.com/api/savedselections/{{selection_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

4. POST /api/savedselections takes a selection dictionary in the post body and creates and returns a new selection object.

Note: Click here for a breakdown of the selection request dictionary below.

curl --request POST \
  --url https://services.oxfordeconomics.com/api/savedselections \
  --header 'api-key: {{api_key}}' \
  --header 'content-type: application/json' \
  --data '{
  "SelectionType": "QuerySelection",
  "MeasureCode": "L",
  "IsTemporarySelection": false,
  "DatabankCode": "WDMacro",
  "Sequence": "EarliestToLatest",
  "GroupingMode": false,
  "TransposeColumns": null,
  "Order": "IndicatorLocation",
  "IndicatorSortOrder": "AlphabeticalOrder",
  "LocationSortOrder": "AlphabeticalOrder",
  "SortedColumnName": null,
  "SortedColumnOrder": null,
  "Format": 0,
  "LegacyDatafeedFileStructure": false,
  "Variables": [
    {
      "VariableCode": "CPI",
      "ProductTypeCode": "WMC",
      "MeasureCodes": [
        "L"
      ]
    },
    {
      "VariableCode": "GDP$",
      "ProductTypeCode": "WMC",
      "MeasureCodes": [
        "L",
        "PY",
        "DY"
      ]
    }
  ],
  "Regions": [
    {
      "DatabankCode": "WDMacro",
      "RegionCode": "GBR"
    },
    {
      "DatabankCode": "WDMacro",
      "RegionCode": "USA"
    }
  ],
  "ShareCodeId": null,
  "ListingType": "Private",
  "IsDatafeed": false,
  "Name": "New selection",
  "StartYear": 2015,
  "EndYear": 2021,
  "Frequency": "Annual",
  "StackedQuarters": false
}'

/ShapedDownload

Download saved selections configured into shaped tables.

1. POST /api/shapeddownload/{id} returns a JSON dictionary of download data based on the selection ID provided and the shape configuration sent in the request body.

curl --request POST \
  --url https://services.oxfordeconomics.com/api/shapeddownload/{{selection_id}} \
  --header 'api-key: {{api_key}}' \
  --header 'content-type: application/json' \
  --data '{
	"Pivot": "false",
	"StackedQuarters": "false",
	"Frequency": "Both"
 }'

/Tree

Provides useful information on a databank’s related trees.

1. GET /api/tree/Locations_{id} returns a JSON list of a databank’s related locations.

 curl --request GET \
   --url https://services.oxfordeconomics.com/api/tree/Locations_{{databank_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

2. GET /api/tree/Indicators_{id} returns a JSON list of a databank’s related indicators.

 curl --request GET \
   --url https://services.oxfordeconomics.com/api/tree/Indicators_{{databank_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

/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.

 curl --request GET \
   --url https://services.oxfordeconomics.com/api/users/{{contact_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

2. POST /api/users returns a JSON object with user information, including a list of available saved selections, as well as the user’s API key. See the request dictionary entry for user credentials below.

 curl --request POST \
   --url https://services.oxfordeconomics.com/api/users \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json' \
   --data '{
        "Username": {{user_name}},
        "Password": {{password}}
 }'

/Variable

Shows which variables are available for a given databank. This includes the VariableCode value, which you will use in building custom selections.

1. Get /api/variable/{id} returns a JSON list object with the indicators available for a given databank.

 curl --request GET \
   --url https://services.oxfordeconomics.com/api/variable/{{databank_id}} \
   --header 'api-key: {{api_key}}' \
   --header 'content-type: application/json'

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:

Related Services

Post

From opportunity to impact – Assessing the economic, societal, and cultural benefits of YouTube in Finland

This study assesses YouTube's contribution to GDP and employment in Finland, and its broader impact on society and culture.

Find Out More

Post

Mahdollisuuksista vaikuttavuuteen – Arviointi YouTuben taloudellisista, yhteiskunnallisista ja kulttuurisista hyödyistä Suomessa

Tässä tutkimuksessa arvioidaan YouTuben vaikutusta Suomen bruttokansantuotteeseen ja työllisyyteen sekä sen laajempaa vaikutusta yhteiskuntaan ja kulttuuriin.

Find Out More

Post

Economic Impacts of The Umbrella Academy Season Two in Ontario

In 2019, production of Season Two of “The Umbrella Academy” resulted in total spending in Ontario of over C$77.3 million.

Find Out More