API Databank – Key Request Dictionaries and Request Header

Modified on: Thu, 1 Sep 2022 9:18 AM

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.

Request Header

HTTP requests to the API require two headers be set: api-key, which should be set to the user’s API key, and content-type, which is typically “application/json”.

Example request, indicating proper HTTP headers:

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

Controller

Controller layout:

 {
   format: ("csv", "excel"),
   name: string,
   selections: [selection id] 
 }

Example controller:

 {
   format: "csv",
   name: "GDP$ USA, GBR 2016-21",
   selections: ["cc0547f1-4600-4ace-88a0-d86876508a15"] 
 }

Selection

Selection layout:

{ 
   Id: string,
   Name: string,
   DatabankCode: string,
  MeasureCode: see measure codes,
  StartYear: int,
  EndYear: int,
  StackedQuarters: ("true", "false"),
  Frequency: ("Annual", "Quarterly", "Both"),
  GroupingMode: ("true", "false"),
  IndicatorSortOrder: ("AlphabeticalOrder", "TreeOrder"),
  IsDatafeed: ("true", "false"),
  IsTemporarySelection: ("true", "false"),
  LegacyDatafeedFileStructure: ("true", "false"), 
  ListingType: ("Hidden", "Private", "Company", "Public", "Shared"),
  LocationSortOrder: ("AlphabeticalOrder", "TreeOrder"),
  Order: ("IndicatorLocation", "LocationIndicator"),
  Regions:
  [ {
   DatabankCode: string,
   RegionCode: string
  } ]
  Variables:
  [ {
   ProductTypeCode: string,
   VariableCode: string,
   MeasureCodes: [see measure codes]
  } ]
 }

Example selection:

{
     DownloadUrl: "/api/download/46bbd06a-5bf2-4278-b96f-037f15e2f256",
     Id: "46bbd06a-5bf2-4278-b96f-037f15e2f256",
     SelectionType: "QuerySelection",
     MeasureCode: "L",
     IsTemporarySelection: false,
     LastUpdate: "2017-05-08T18:51:54.363",
     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,<br>
     Name: "Selection - (Updated 2017/05/09)",
     StartYear: 2015,
     EndYear: 2021,
     Frequency: "Annual",
     StackedQuarters: false
  }

     DownloadUrl: "/api/download/46bbd06a-5bf2-4278-b96f-037f15e2f256",
     Id: "46bbd06a-5bf2-4278-b96f-037f15e2f256",
     SelectionType: "QuerySelection",
     MeasureCode: "L",
     IsTemporarySelection: false,
     LastUpdate: "2017-05-08T18:51:54.363",
     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 2017/05/09)",
     StartYear: 2015,
     EndYear: 2021,
     Frequency: "Annual",
     StackedQuarters: false

Shape configuration

Shape configuration layout:

{ 
Pivot: ("true", "false"),
StackedQuarters: ("true", "false"),
 Frequency: ("annual", "quarterly", "both")
}

Example shape configuration:

{ 
Pivot: ("true", "false"),
StackedQuarters: ("true", "false"),
 Frequency: "both"
}

User credentials

User credentials layout:

 {
  Username: string,
  Password: string
}

Example credentials:

 {
  Username: name@example.com,
  Password: example_password
}

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