Get Started - API Endpoints

The Yahoo Native v3 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.

If you are new to the API, you may wish to review the sections below that discuss key terms, example endpoint usage and the matrix of the API endpoints. The matrix outlines the supported HTTP methods for RESTful Objects.

Get Started

To get started with the API, you’ll need to apply for access and an API Key. The process is simple and straightforward, once you complete the form at Apply for Access.

Important

Once we review your application, we’ll provide you with access, so that you can create an application and take advantage of the Yahoo Native API. You’ll receive a Consumer Key and Secret, which you’ll need when using the API.

Key Terminology

A resource is an essential data abstraction in the RESTful software architecture. A resource can be any named object, service or collection of other resources. The Yahoo Native RESTful API relies on a resource identifier to identify a resource used when defining the interaction between objects.

An endpoint is a URI (Uniform Resource Identifier) that provides access to a resource. Endpoints define how you access the resource. Supported HTTP methods specify which interactions, like GET, POST, PUT or DELETE, are permitted with the resource.

A service is comprised of an endpoint, an HTTP method and a set of parameters.

HTTP Methods

Definition

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/get_2cf25ef4b.png

Used to read (or retrieve) a representation of a resource.

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/post_ef494b04f.png

Used to create new resources. In particular, used to create subordinate resources.

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/put_a59833233.png

Used to update capabilities.

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/delete_f2bb8ca21.png

Used to delete a resource identified by a URI.

Matrix View of API Endpoints

The Yahoo Native v3 API provides you with the following RESTful objects and services, as shown in the table below.

Data Objects, Definitions & Examples

Supported HTTP Methods

Endpoint

Authentication

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/get_2cf25ef4b.png

https://api.login.yahoo.com/oauth2/get_token

Advertisers

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/get_2cf25ef4b.png

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

Campaign

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Ad Group

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Ad

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Keyword

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Targeting Attribute

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Ad Extension

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Shared Sitelink

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Shared Sitelink Setting

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Ad Site Setting

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Frequency Cap

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Dot Tag

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Conversion Rule

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Bulk Jobs

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/post-get-put_b247706f8.png

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

Shared Sets

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

https://api.gemini.yahoo.com/v3/rest/sharednegativekeyword/ https://api.gemini.yahoo.com/v3/rest/campaignsharedset/

Account Change History

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/post-get_231f18165.png

https://api.gemini.yahoo.com/v3/rest/accounthistory/reports/

Reseller Management

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

Reporting

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/post-get_231f18165.png

https://api.gemini.yahoo.com/v3/rest/reports/custom/

https://api.gemini.yahoo.com/v3/rest/reports/cob

Dynamic Product Ads

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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

https://api.gemini.yahoo.com/v3/rest/feed/ https://api.gemini.yahoo.com/v3/rest/dparule/

Data Dictionary

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/get_2cf25ef4b.png

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

Audience Management

https://s.yimg.com/oo/cms/products/nativeandsearch-vmdn/api-endpoints/images/all-verbs_b282d1cf1.png

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


Important

For developer convenience and ease of use, all of the above calls are available as a Postman collection. You can download them from the Postman API Toolkit. Postman can be useful in your development efforts for optimizing, testing and error-checking your API calls when working with the programmatic API.

Example Endpoint Usage

Using the Yahoo Native v3 API resource URI, for example:

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

You can set frequency capping for a campaign by making a PUT call to the following endpoint with these parameters:

PUT https://api.gemini.yahoo.com/v3/rest/frequency

Data passed
{
  "value": 10,
  "type": "DAILY",
  "advertiserId": 11610,
  "parentType": "CAMPAIGN",
  "parentId": 332817035,
  "id": 299239189394
}


Example response
{
  "errors": null,
  "timestamp": "2015-08-22 1:58:45",
  "response": {
      "type": "DAILY",
      "id": 295617989759,
      "status": "ACTIVE",
      "parentId": 332817035,
      "parentType": "CAMPAIGN",
      "advertiserId": 11610,
      "value": "10"
  }
}

Learn More

To better understand the API and navigate the steps to get started, see Navigating the Yahoo Native API.

The data model for the Yahoo Native API is described in the section Objects.