Objects¶

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.

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

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).

The rate limits with API quota thresholds are shown in the table below.

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.

The following table describes the current behavior (unchanged) for Search when serving eligible channels.

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) and mr (maximum rows to retrieve) params in GET calls. If not provided, si will default to 0 and mr 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.

Related Topics¶

If you’re an Yahoo Native API developer, partner or advertiser using your own analytics in Yahoo Native ads, you may need to understand briefly how ad monitoring and URL crawling work.

Yahoo crawls URLs for both content and screen grabbing. While the content crawl is used to determine Yahoo Native Advertising Policy Compliance, the editorial team reviews the screen-grab or screenshot rather than the actual webpage. Both crawls are performed using a user agent, i.e., Yahoo Ad Monitoring. It’s important to note that you can disregard that user agent in the user agent string so you only capture clicks from Yahoo users.

For more detailed information, refer to What is Yahoo Ad Monitoring.