Data Dictionary

The data dictionary service allows you to get a list of the supported values for different Gemini object attributes.

Endpoint

Resource URI

https://api.admanager.yahoo.com/v1/rest/dictionary/

Supported data dictionary types

To retrieve a list of the supported dictionary types, make a GET call to the dictionary endpoint.

Example: GET call to retrieve supported dictionary types

https://api.admanager.yahoo.com/v1/rest/dictionary

The response will be an array of all the supported dictionary types and a description for them:

{
  "errors": null,
  "response": [
      {
          "name": "All acceptable campaign language values",
          "value": "language"
      },
      {
          "name": "All acceptable campaign booking/billing country values",
          "value": "country"
      },
      {
          "name": "All acceptable advertiser timezone values",
          "value": "timezone"
      },
      {
          "name": "All acceptable interest currency values",
          "value": "currency"
      },
      {
          "name": "All acceptable interest segment values",
          "value": "interest_segments"
      },
      {
          "name": "All acceptable woeid values",
          "value": "woeid"
      }
  ]
}

The dictionary type values can be used in the URI in order to get a list of the supported values for those dictionary types (see examples below). Note that supported dictionary types may be added over time, in which case the array in the response will grow. The GET call required in order to retrieve this list will not change.

Example: get a list of supported languages

To retrieve a list of the supported languages for advertisers and campaigns, make a GET call to the dictionary endpoint and specify “language” in the URI:

GET https://api.admanager.yahoo.com/v1/rest/dictionary/language

The response will be an array of all the supported values for the “language”” dictionary type, along with a name describing each value:

{
   "errors": null,
   "timestamp": "2016-01-20 22:32:44",
   "response": [
{
   "name": null, "value": "DKK"
},
{
   "name": null, "value": "NZD"
},
{
   "name": null, "value": "CNY"
},
{
   "name": null, "value": "ILS"
},
{
   "name": null, "value": "USD"
},
....
]
}

Example: get a list of supported devices

To get a list of supported devices, make the following GET call:

GET https://api.admanager.yahoo.com/v1/rest/dictionary/device

The response will be an array of all the supported values for the “device” dictionary type, along with a name describing each value:

{
      "errors": null,
      "response":
      [
              {       "value": "DESKTOP",
                      "name": "Desktop"
              },
              {       "value": "SMARTPHONE",
                      "name": "SmartPhone"
              },
              {       "value": "TABLET",
                      "name": "Tablet"
              },
              {       "value": "MOBILE_SMART_PHONES_APPLE",
                      "name": "Mobile/Smart Phones/Apple"
              },
              {       "value": "MOBILE_SMART_PHONES_APPLE_IPHONE",
                      "name": "Mobile/Smart Phones/Apple/iPhone"
              },
              {       "value": "MOBILE_SMART_PHONES_SAMSUNG",
                      "name": "Mobile/Smart Phones/Samsung"
              },
              ...
      ]
}

Example: get a list of supported currencies

To get a list of supported currencies, make the following GET call:

GET https://api.admanager.yahoo.com/v1/rest/dictionary/currency

The response will be an array of all the supported values for the “currency” dictionary type, along with a name describing each value:

{
  "errors": null,
  "timestamp": "2016-01-20 22:32:44",
  "response":
 [
   {
           "name": null, "value": "DKK"
       },
       {
          "name": null, "value": "NZD"
       },
   {
          "name": null, "value": "CNY"
       },
   {
          "name": null, "value": "ILS"
       },
   {
          "name": null, "value": "USD"
       },
   ....
 ]
}

Looking up currency details by type

To get a list of specific currency information such as minimum budget or bid values, make the following GET call:

GET https://api.admanager.yahoo.com/v1/rest/dictionary/currency?code=USD

The response will include the relevant currency information:

{

“errors”: null, “timestamp”: “2016-01-20 22:33:39”, “response”: {

“minCampaignBudget”: 5, “minBidCpm”: 0.25, “minBidCpv”: 0.01, “minBidCpc”: 0.05

}

}

Example: get a list of supported WOEIDs

WOEIDs represent location ids that are used for geo targeting on Gemini (refer to the targeting attribute service documentation for more details on working with WOEIDs). WOEIDs are different than other data dictionary types in that you need to specify which type of WOEID you are requesting the values for. Supported types are “country”, “region”, “state”, “DMA” and “city”.

For example, to get a list of supported city WOEIDs, make the following GET call:

GET https://api.admanager.yahoo.com/v1/rest/dictionary/woeid/?type=city

The response will be an array of all the supported city WOEIDs and a name describing them. The response will also include the parent WOEID for each value in that level:

{
  "errors": null,
  "response": [
  {
      "woeid": 2171688,
      "parentWoeid": 23424781,
      "type": "CITY",
      "name": "Zhangjiakou, China, null"
  },
  {
      "woeid": 1180689,
      "parentWoeid": 23424934,
      "type": "CITY",
      "name": "Makati City, Philippines, null"
  },
  {
      "woeid": 1915203,
      "parentWoeid": 23424759,
      "type": "CITY",
      "name": "Rajshahi, Bangladesh, null"
  },

  ...
  ]
 }

Look up location by WOEID

You can use the data dictionary service to look up the locations specific WOEIDs represent. Here is an example of looking up the location for two specific WOEIDs:

https://api.admanager.yahoo.com/v1/rest/dictionary/woeid?woeid=23424804&woeid=2171688

The response will be an array of all the locations of the WOEIDs that were passed in the request:

{
  "errors": null,
  "response": [
      {
          "woeid": 23424804,
          "parentWoeid": 23424804,
          "type": "COUNTRY",
          "name": "Equatorial Guinea"
      },
      {
          "woeid": 2171688,
          "parentWoeid": 23424781,
          "type": "CITY",
          "name": "Zhangjiakou, China, null"
      }
  ]
 }

Looking up WOEIDs by location name

The WOEIDs returned by the dictionary service cover the locations Yahoo Gemini officially supports. You can still target WOEIDs that are not in the dictionary as long as they are in the country, state, DMA, or city level. On search campaigns zip code level targeting is supported as well. Note that while targeting locations that are not in the dictionary is possible, it will likely result in more limited audience reach.

You can look up the WOEID for a location that may not be in the dictionary by passing in the location name as a parameter, as well as an optional ‘type’ parameter:

https://api.admanager.yahoo.com/v1/rest/dictionary/woeid?location=california&type=state

The response will include the relevant WOEID:

{
  "errors": null,
  "timestamp": "2015-11-07 2:35:08",
  "response": [
      {
          "woeid": 2347563,
          "name": "California, US",
          "type": "State",
          "parentWoeid": 23424977
      }
  ]
}

Looking up WOEIDs by Zip code

The WOEIDs returned by the dictionary service cover the locations Yahoo Gemini officially supports. You can still target WOEIDs that are not in the dictionary as long as they are in the country, state, DMA, or city level. On search campaigns zip code level targeting is supported as well. Note that while targeting locations that are not in the dictionary is possible, it will likely result in more limited audience reach.

You can look up the WOEID for a location that may not be in the dictionary by passing in the location name as a parameter, as well as an optional ‘type’ parameter:

https://api.admanager.yahoo.com/v1/rest/dictionary/woeid?location=01067&type=zip

The response will include the relevant WOEID:

{
      "errors": null,
      "timestamp": "2016-02-29 22:39:11",
      "response": [
        {
          "woeid": 12831235,
          "name": "01067, Dresden, Saxony, Germany",
          "type": "Zip",
          "parentWoeid": 2345493
        }
      ]
}