Data Dictionary

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

Note

The maximum number of objects that can be retrieved in a single GET call is 500. For optimal results, we recommend fetching in batches no larger than 100. For more information about pagination, refer to Pagination.

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/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.gemini.yahoo.com/v3/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.gemini.yahoo.com/v3/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 Languages For Call to Action Text

If a campaign is set to Spanish, for example, callToActionText won’t accept the values in English. You’ll need to use enum values, shown in the table below, which are supported for multiple languages in the data dictionary.

Make a GET call to these specific endpoints, depending on your choice of language:

English (which is the default):

https://api.gemini.yahoo.com/v3/rest/dictionary/call_to_action_text/

Spanish:

https://api.gemini.yahoo.com/v3/rest/dictionary/call_to_action_text/?language=es

French:

https://api.gemini.yahoo.com/v3/rest/dictionary/call_to_action_text/?language=fr

Japanese:

https://api.gemini.yahoo.com/v3/rest/dictionary/call_to_action_text/?language=ja

List of supported languages

Language

Value

Type

Required?

English

en

enum

Yes

French

fr

enum

Yes

German

de

enum

Yes

Spanish

es

enum

Yes

Italian

it

enum

Yes

Greek

el

enum

Yes

Swedish

sv

enum

Yes

Vietnamese

vi

enum

Yes

Japanese

ja

enum

Yes

Simplified Chinese

zh_CN

enum

Yes

Traditional Chinese

zh_TW

enum

Yes

Malay

ms

enum

Yes

Indonesian

id

enum

Yes

Portuguese

pt

enum

Yes

Arabic

ar

enum

Yes

Dutch

nl

enum

Yes

Romanian

ro

enum

Yes

Russian

ru

enum

Yes

Turkish

tr

enum

Yes

Note

If you don’t specify a language value, the default will be English.

Example: Get a List of Supported Devices

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

GET https://api.gemini.yahoo.com/v3/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.gemini.yahoo.com/v3/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.gemini.yahoo.com/v3/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,
    "minBidCpmVideo": 4,
    "minBidCpv": 0.01,
    "minBidCpc": 0.05
  }
}

Example: Get a List of Supported WOEIDs

WOEIDs represent location ids that are used for geo targeting on Native (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.gemini.yahoo.com/v3/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": "Town",
      "name": "Zhangjiakou, China, null"
  },
  {
      "woeid": 1180689,
      "parentWoeid": 23424934,
      "type": "Town",
      "name": "Makati City, Philippines, null"
  },
  {
      "woeid": 1915203,
      "parentWoeid": 23424759,
      "type": "Town",
      "name": "Rajshahi, Bangladesh, null"
  },

  ...
  ]
 }

Important

Native Ad Platform API provides you with an additional parameter: fuzzy. You can use this parameter to expand your search results. For instance, if your returned result doesn’t contain the WOEID you’re looking for, you can set this parameter to ‘true’ to perform a fuzzy search that will expand your search results. Note that this fuzzy parameter only works for this dictionary API call using location search: ../dictionary/woeid?location=…&fuzzy=true.

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.gemini.yahoo.com/v3/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": "Town",
          "name": "Zhangjiakou, China, null"
      }
  ]
 }

Looking up WOEIDs by location name

The WOEIDs returned by the dictionary service cover the locations the Verizon Media Native API 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.

Zip code level targeting is also available.

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.gemini.yahoo.com/v3/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 the Verizon Media Native API 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.

Zip code level targeting is also available.

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.gemini.yahoo.com/v3/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
        }
      ]
}

Example: Get a List of Valid Site Names for Site X Device Targets

To accomplish this, make the following GET call:

GET https://api.gemini.yahoo.com/v3/rest/dictionary/bbsxd_supported_sites

This can be filtered by category. If no category is passed, then it will return all valid sites.

Note

This is case-insensitive.

The list of supported categories:

  • MAIL

  • HOMEPAGE

  • NEWS

  • FINANCE

  • TUMBLR

  • AFFILIATE

  • SPORTS

  • FANTASY_SPORTS

  • STYLE

  • CELEBRITY

  • WEATHER

  • ANSWERS

  • AUCTION

  • DICTIONARY

  • TELEVISION

  • MSN

If you wish to get a list of valid site names filtered by MAIL, make the following GET call:

GET https://api.gemini.yahoo.com/v3/rest/dictionary/bbsxd_supported_sites?category=MAIL

The response will be an array of all the valid supported sites under MAIL category. The value will be the site name for site x device target, and it also includes a name describing them.

{
      "errors": null,
      "response": [{
              "category": "Mail",
              "name": "AOL Mail",
              "value": "AOL_MAIL"
      }, {
              "category": "Mail",
              "name": "AT&T Mail US",
              "value": "AT&T_MAIL_US"
      }, {
              "category": "Mail",
              "name": "AT&T Mail US 2",
              "value": "AT&T_MAIL_US_2"
      }, {
              "category": "Mail",
              "name": "BT Mail UK",
              "value": "BT_MAIL_UK"
      },
      ...
      ]
}

Example: Get a List of Valid Site Group Names

To accomplish this, make the following GET call:

GET https://api.gemini.yahoo.com/v3/rest/dictionary/bbsxd_supported_site_groups

The response will be an array of all the valid supported site groups. The value will be the site group name for the site group x device target.

{
      "response": [{
              "category": "Mail",
              "name": "Yahoo Mail",
              "value": "YAHOO_MAIL"
      }, {
              "category": "Mail",
              "name": "MSN Mail",
              "value": "MSN_US"
      }
      ]
}

Important

For purposes of clarity, note that /bbsxd_supported_site_groups fetches only site groups that can be targeted as a SITE_GROUP_X_DEVICE.

Note

If a SITE_X_DEVICE targeting is created or updated for a site that belongs to an active site group, an INVALID_INPUT error will be thrown with the appropriate error message.

Example: Get a List of Supported Flash Sale Countdown Prefix Text in a Certain Language

If a campaign is set to Spanish, for example, FlashSaleConfig.countdownPrefixText won’t accept the values in English. You’ll need to use enum values, shown in the table below, which are supported for multiple languages in the data dictionary.

Make a GET call to these specific endpoints, depending on your choice of language:

For English (which is the default):

https://api.gemini.yahoo.com/v3/rest/flash_sale_countdown_prefix_text/

Spanish:

https://api.gemini.yahoo.com/v3/rest/dictionary/flash_sale_countdown_prefix_text/?language=es

French:

https://api.gemini.yahoo.com/v3/rest/dictionary/flash_sale_countdown_prefix_text/?language=fr

Japanese:

https://api.gemini.yahoo.com/v3/rest/dictionary/flash_sale_countdown_prefix_text/?language=ja

(The supported language is the same; the default is English.)

The Result:

{
  "errors": null,
  "response":[
      "Starts in",
      "Sale starts in",
      "Launches in",
      "Ends in",
      "Sale ends in",
      "Offer ends in",
      "Deadline in",
      "Deal ends in",
      "Expires in",
      "Time left",
      "Premieres in"
  ]
}

3rd Party Interest Segments

Read data for list of 3rd-party interest segments

Method: To retrieve data for a list of 3rd-party interest segments, make a GET call using the following parameters:

Name

Description

Type

Value

Required?

advertiserId

The ID of the advertiser needed to filter the segments.

int

The ID of the advertiser.

Yes

dataProvider

The 3P data provider name, such as DMP (optional).

String

The data provider name.

Optional

searchString

A string used for substring search.

int

If nothing is specified, the full list by pagination is returned.

Optional

si

The start index or the first element to retrieve. Only active segments are returned.

int

The start index.

Optional

mr

The maximum number of rows to retrieve.

int

The default maximum rows is 500.

Optional

id

When id passed in, the search string is no longer honored.

int

The segment ID.

Optional

parentId

When parentID is passed in, it returns all the next level child segments.

int

The segment parent ID

Optional

Example: GET call for a list of 3rd-party interest segments:

https://api.gemini.yahoo.com/v3/rest/dictionary/interest_segments_3p?advertiserId=12345


{
   "errors":null,
   "timestamp":"2018-01-19 1:13:02",
   "response":[
      {
         "name":"BlueKai",
         "value":20097120
      },
      {
         "name":"Adobe",
         "value":50000040
      }
   ]
}

Method: To retrieve data for interest segments for 3rd-party data providers, make a GET call using the following parameters:

Example: GET call for interest segments for 3rd-party data providers:

https://api.gemini.yahoo.com/v3/rest/dictionary/interest_segments_data_providers?advertiserId=12345

{
   "errors":null,
   "timestamp":"2018-01-19 1:13:02",
   "response":[
              {
         "name": "Blue Collar Worker",
         "description": null,
         "parentId": 20086282,
         "dataProvider": "DMP",
         "value": 20075667
     },
     {
         "name": "BlueKai",
         "description": null,
         "parentId": 20077359,
         "dataProvider": "DMP",
         "value": 20075819
     }
   ]
}

Verizon Media Interest Segments

Read data for a list of Verizon Media interest segments

Method: To retrieve data for a list of Verizon Media interest segments, make a GET call using the following parameters:

Name

Description

Type

Value

Required?

advertiserId

The ID of the advertiser needed to filter the segments.

int

The ID of the advertiser.

Yes

searchString

A string used for substring search.

int

If nothing is specified, the full list by pagination is returned.

Optional

si

The start index or the first element to retrieve. Only active segments are returned.

int

The start index.

Optional

mr

The maximum number of rows to retrieve.

int

The default maximum rows is 500.

Optional

id

When id passed in, the search string is no longer honored.

int

The segment ID.

Optional

parentId

When parentID is passed in, it returns all the next level child segments.

int

The segment parent ID

Optional

Example: GET call for a list of Verizon Media interest segments:

https://api.gemini.yahoo.com/v3/rest/dictionary/interest_segments_oath?advertiserId=12345

{
   "errors":null,
   "timestamp":"2018-01-19 1:13:02",
   "response":[
              {
         "name": "Blue Collar Worker",
         "description": null,
         "parentId": 20086282,
         "value": 20075667
     },
     {
         "name": "BlueKai",
         "description": null,
         "parentId": 20077359,
         "value": 20075819
     }
   ]
}