Getting Started

The Gemini API provides you with the tools and resources you need to create, manage and retrieve advertiser data for your ads, ad groups and campaigns programmatically.

Developers are encouraged to take advantage of Gemini API as mobile traffic continues to increase rapidly, with the majority of ads on Yahoo mobile search inventory being served by Yahoo Gemini. Native advertising across Yahoo mobile inventory is only available through Yahoo Gemini.

The sooner you participate in Yahoo Gemini, the sooner the system can begin to build a performance history for your ad, so that your ad can earn better ranking and start getting you the clicks it deserves. As traffic ramps, your ad is then in the best position for cost-effective delivery and performance.

Who Should Read This Document

This documentation is intended for programmers who are developing apps to access Yahoo! content and search infrastructure. A prerequisite for working with Yahoo Gemini API is an understanding of HTTP, XML, JSON, and a cursory knowledge of query languages.

Integrating Yahoo’s OAuth Authorization Model

Gemini supports the OAuth 2.0 protocol. Yahoo Gemini API uses OAuth 2.0 as a simple and secure way method for validation and access. The authorization model is open and based on existing standards, which ensure that secure credentials can be provisioned and verified by different software platforms.

OAuth 2.0 allows you, and visitors to your web page, to securely access the Yahoo! Web, Image, and News content. As a publisher, OAuth 2.0 provides secure access to this content, using your Gemini API application ID and the Yahoo API key to verify your authorized access privileges and allow for correct billing from Yahoo.

Before You Begin

Follow these steps:

  1. To begin, you need a Yahoo user ID that is dedicated to Gemini. If you don’t have one (login.yahoo.com or admanager.yahoo.com), you should create one.

  2. Create the app and subsequent developer keys:

  • https://developer.yahoo.com/apps/create/?api=admg

  • If you are creating a web application for other companies to use your software to access Gemini, select Web Application as the app type. You will need a valid callback domain.

  • If you are creating a server-only connection to perform API functions restricted to your own company, use Installed Application. This does not require a callback domain to be entered; leave this blank. For subsequent API calls that require a callback url, simply enter oob.

  1. Next, you need to follow the explicit grant flow.

  2. Implicit grant flow only allows a single API session for each authorization.

Using OAuth 2.0 with Gemini API

Once your users connect with Gemini OAuth, your application will be able to make API calls on their behalf without requiring additional authorization from them.

The workflow is as follows:

  1. When users connect to Yahoo Gemini to create and manage ad campaigns, or query and fetch reports, you must send them to Yahoo! with the client_id you received when registering your app.

  2. Users are then prompted to connect to their Gemini account. After connecting, they will be redirected to your redirect_uri with an authorization code. If authorization is denied, an error code is returned.

  3. You can then exchange that authorization code for an access token, which enables usage of your API calls.

Setting up your OAuth 2.0 client

For information on how to set up your OAuth 2.0 client, refer to the OAuth 2.0 Guide. OAuth 2.0 is an updated version of the OAuth protocol that supersedes OAuth 1.0 and 1.0a.

Some key changes and distinctions from OAuth 1.0:

  • SSL for secure communication

  • signatures are no longer necessary

  • support for a variety of grant types and flows


For detailed information on Yahoo!’s implementation of the OAuth standard, see the documentation OAuth Authorization Model on the Yahoo! Developer Network.

OAuth refresh tokens

Key points to consider when working with refresh tokens:

  • Refresh tokens will not expire. They can only be invalidated explicitly by the user.

  • Access tokens will expire after 60 minutes.

  • As a best practice, you should always capture the refresh token after using it to get a new access token. It may change, and when it does you should use the new one.

  • If you change your password, the existing refresh token should continue to work. A new refresh token will not be issued and you won’t need to request user consent and restart the OAuth flow.

  • If, as a Yahoo Partner, you explicitly revoke the OAuth access for your app on account info, you should request user consent again.


For more information, see Authorization Code Flow for Server-side Apps on the Yahoo! Developer Network.

Using the Gemini Sandbox Environment

Yahoo Gemini provides you with a sandbox environment that you can use in your development workflow to test the creation and management of your advertising campaigns. You use the same consumer key and consumer secret you obtained when you set up your OAuth to access the sandbox.

Resource URI

https://sandbox-api.admanager.yahoo.com/v1/rest/{resource}

The Gemini sandbox serves as a modified version of the production environment.

While all operations are designed to function the same in the sandbox as in the production environment, the campaigns and ads you create in this environment do not actually serve. The sandbox environment is completely separate from your production environment.

All campaigns, ads, and keywords you create in the sandbox are available in the sandbox environment only. There is no possibility that the ads you create in the sandbox will be accidentally served. Nor will your production accounts be charged for any mock transactions in the sandbox environment.

You will need to create a sandbox account in order to test in this environment. You can do this by making a POST call to the sandbox signup endpoint and passing in the name you wish to call your test advertiser. The response will be a test advertiser object that will only be available in the sandbox environment:

POST http://sandbox-api.admanager.yahoo.com/v1/rest/advertisersignup

Data passed
{
   "advertiserName":
   "sandbox test"
}

Example response
{
  "errors": null,
  "timestamp": "2015-02-27 23:37:32",
       "response": [
         {
           "advertiser": {
           "currency": "USD",
           "timezone": "America/New_York",
           "id": 123456,
           "advertiserName": "sandbox test"
         }
       }
 ]
}

Data Model

To better understand the relationships between the Gemini entities and data objects, you may wish to study this diagram. Please refer to Objects_ for more details on the different data objects and their attributes.

ad manager plus data model

Limits

The following table provides details on the object limits supported in Gemini:

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

20,000

Ads per ad group

50

Negative keywords per advertiser account

5,000,000

Location targeting objects per advertiser account

100,000

Maximum number of objects passed in API call

500

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.

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.admanager.yahoo.com/v1/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.