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": Arabic, "value": "ar"
},
{
   "name": Danish, "value": "da"
},
{
   "name": German, "value": "de"
},
{
   "name": Greek, "value": "el"
},
{
   "name": English, "value": "en"
},
....
]
}

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

A response example looks like this:

{
      "errors": null,
      "timestamp": "2020-07-16 0:19:35",
      "response": [
          "Follow Now",
              "Join Now",
              "Start Now",
              "Search Now",
              "Read Now",
              "Explore",
        ...
        ]
}

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 Yahoo 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

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
     }
   ]
}

Yahoo Native Interest Segments¶

Read data for a list of Yahoo Native interest segments

Method: To retrieve data for a list of Yahoo Native 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 Yahoo Native 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
     }
   ]
}