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
	Used to read (or retrieve) a representation of a resource.
	Used to create new resources. In particular, used to create subordinate resources.
	Used to update capabilities.
	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://api.login.yahoo.com/oauth2/get_token
Advertisers		https://api.gemini.yahoo.com/v3/rest/advertiser/
Campaign		https://api.gemini.yahoo.com/v3/rest/campaign/
Ad Group		https://api.gemini.yahoo.com/v3/rest/adgroup/
Ad		https://api.gemini.yahoo.com/v3/rest/ad/
Keyword		https://api.gemini.yahoo.com/v3/rest/keyword/
Targeting Attribute		https://api.gemini.yahoo.com/v3/rest/targetingattribute/
Ad Extension		https://api.gemini.yahoo.com/v3/rest/adextension/
Shared Sitelink		https://api.gemini.yahoo.com/v3/rest/sharedsitelink/
Shared Sitelink Setting		https://api.gemini.yahoo.com/v3/rest/sharedsitelinksetting/
Ad Site Setting		https://api.gemini.yahoo.com/v3/rest/adsitesetting/
Frequency Cap		https://api.gemini.yahoo.com/v3/rest/frequency/
Dot Tag		https://api.gemini.yahoo.com/v3/rest/tag/
Conversion Rule		https://api.gemini.yahoo.com/v3/rest/conversionrule/
Bulk Jobs		https://api.gemini.yahoo.com/v3/rest/bulk/
Shared Sets		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://api.gemini.yahoo.com/v3/rest/accounthistory/reports/
Reseller Management		https://api.gemini.yahoo.com/v3/rest/advertiser/
Reporting		https://api.gemini.yahoo.com/v3/rest/reports/custom/ https://api.gemini.yahoo.com/v3/rest/reports/cob
Dynamic Product Ads		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://api.gemini.yahoo.com/v3/rest/dictionary/
Audience Management		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.