Objects¶
The Yahoo Native API provides you with a set of RESTful Objects that you can use to create, manage and retrieve advertiser data for your ads, ad groups and campaigns programmatically.
Using these RESTful Objects, you can access HTTP resources, which return a set of JSON representations along with their corresponding data types.
Data Model¶
The data model for the Yahoo Native v3 API is not based on services, but rather on calling the same RESTful object with a different HTTP method.
To better understand the relationships between the entities and data objects, you may wish to study this diagram.

Each object type with associated fields, endpoints and example representations is described in detail in the Objects list.
Note
The Yahoo Native v3 API includes a library of shared sets. For more information on these new objects, refer to Shared Sets Library.
Object Representation¶
Each object representation – Ad, Ad Group, Advertiser, Campaign – includes a field description that lists, in table format, its name and data type, as well as additional information for adding and updating. The Endpoint for the resource URI is then provided, followed by example representations with RESTful responses associated with standard GET, PUT and POST calls.
To retrieve data for an ad campaign, for example, you would make a GET call with an ID parameter that you’ve specified (31336), like this:
https://api.gemini.yahoo.com/v2/rest/campaign/31336
{
"errors": null,
"response": {
"id": 31336,
"status": "PAUSED",
"advertiserId": 87292,
"campaignName": "SampleCampaign",
"budget": 100,
"language": "en",
"budgetType": "LIFETIME",
"channel": "SEARCH_AND_NATIVE",
"objective": "PROMOTE_BRAND",
"isPartnerNetwork": "TRUE",
"defaultLandingUrl": null
}
}
The response is then the campaign associated with the given ID, as shown above.
If you want to clear the value of any optional string field, for example, you would pass in an empty string when you update the object. As shown below, to clear the landing url for the keyword id 1234, you would make a PUT call to the keyword endpoint, like this, passing in:
{
"id": 1234,
"landingUrl": ""
}
The response would be:
{
"errors": null,
"response": {
"exclude": "FALSE",
"bidSet": null,
"status": "ACTIVE",
"id": 1234,
"advertiserId": 99,
"landingUrl": null,
"parentType": "ADGROUP",
"parentId": 5678,
"matchType": "BROAD",
"adParamValues": null,
"value": "keyword value"
}
}
Important
The Yahoo Native API exposes lastUpdateDate
and createdDate
as read-only fields in API responses for all Yahoo Native API objects. These fields provide UNIX timestamps for when an object was created and last updated.
Partial Updates¶
In general, Yahoo Native APIs support partial updates for each RESTful object represented in the v3 API. Note that partial updates are ignored if you pass NULL in your JSON response. For string attributes, you need to pass an empty string “” to explicitly erase the value. Integers are handled differently, and may be erased with 0 or -1 on a case-by-case basis. See specific object attributes documentation for those details.
Limits¶
The following table provides details on the object limits supported in the Yahoo Native API:
Object |
Limit |
---|---|
Campaigns per advertiser account |
10,000 |
Ad groups per campaign |
10,000 |
Keywords per advertiser account |
5,000,000 |
Keywords per ad group |
10,000 |
Ads per ad group |
50 |
Negative keywords per advertiser account |
5,000,000 |
Location targeting objects per advertiser account |
100,000 |
Location WOEID targeting per campaign or adgroup |
10,000 |
Maximum number of objects passed in API call |
500 |
Shared Sets per account |
20 |
Negative Keywords per Shared Set |
5000 |
Shared Sitelinks per account |
5000 |
Important
The total number of campaigns per account for advertisers is 10,000. Once you reach that limit and go beyond it, an error message is returned. There are no restrictions on the number of campaigns you can create daily. Note that for location WOEID targeting per campaign or adgroup, there is also a 10,000 maximum limit.
Rate Limits for API Endpoints¶
For all object APIs (i.e., campaign, ad group, ad, targeting attribute, and so on), the API quota is 100,000 calls per hour. Read operations (such as GETs) have a lower cost factor than write operations (POST/PUT/DELETE).
Important
Any call beyond these rate limits will result in exceeding your hourly quota, which means you’ll start receiving ``HTTP 429 `` error responses, i.e., Too Many Rquests.
The rate limits with API quota thresholds are shown in the table below.
Operation |
1 object (minimum) |
500 objects (maximum) |
---|---|---|
GET (cost factor 1) |
100,000 calls per hour |
200 calls per hour |
PUT/DELETE (cost factor 2) |
50,000 calls per hour |
100 calls per hour |
POST (cost factor 3) |
33,000 calls per hour |
66 calls per hour |
Matrix View of Required fields When Serving Different Ad Types¶
For a comprehensive matrix view of required fields when serving different ad types, refer to Matrix View.
[New] Matrix View of Search Changes When Serving Eligible Channels¶
The following table describes the behavior (current and new) for Search when serving eligible channels. For terminology: SON means Search on Native, SRN means Search Retargeting on Native, KRT means Keyword Retargeting. Note that for SON, the sub_channel can be SRN_AND_SEARCH or SRN_ONLY.
Input Channel |
Input Sub-Channel |
Current |
New |
---|---|---|---|
SEARCH |
SRN_AND_SEARCH |
SEARCH, SON |
SON |
SEARCH |
NULL |
SEARCH, SON (based on the advertiser’s setup. Category 1 -> Search Only. Category [2|3|4] -> SEARCH, SON) |
No OP., or SON (based on the Advertiser’s setup. Category 1 -> No OP. Category [2|3|4] -> SON) |
NATIVE |
SRN_ONLY |
NATIVE KRT |
NATIVE KRT |
SEARCH AND NATIVE |
NULL |
SEARCH, NATIVE |
NATIVE |
The following table describes the current behavior (unchanged) for Search when serving eligible channels.
Input Channel |
Input Sub-Channel |
Current |
New |
---|---|---|---|
SEARCH |
SRN_ONLY |
SON |
SON |
NATIVE |
SRN_AND_SEARCH |
Throws an exception |
Throws an exception |
NATIVE |
NULL |
NATIVE |
NATIVE |
SEARCH AND NATIVE |
SRN_AND_SEARCH |
Throws an exception |
Throws an exception |
SEARCH and NATIVE |
SRN_ONLY |
Throws an exception |
Throws an exception |
Changes to Landing URLs or Text Attributes¶
Any changes to either the landing urls or the text attributes of the following entities – Ad, Keywords and Sitelinks – will result in an editorial status review, with the following values: NOT_REVIEWED, PENDING_REVIEW, APPROVED, OR REJECTED. Note that our SLA is 24 hours; however, in practice, most ads are re-activated in 1 to 2 hours. Please plan your edits and sync logic, accordingly.
Pagination¶
When fetching account data, we recommend the following:
Use the
/count
method to get the total number of objects in the data set you are downloading./count
can be used with all API endpoints.For example, make the following GET call in order to get the number of campaigns for a given advertiser: https://api.gemini.yahoo.com/v2/rest/campaign/count?advertiserId=11610
Use the
si
(start index) andmr
(maximum rows to retrieve) params in GET calls. If not provided,si
will default to 0 andmr
will default to 500.500 is the maximum number of objects that can be retrieved in a single GET call. For optimal results, we recommend fetching in batches no larger than 100.