Objects

The Gemini 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 Gemini v2 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 Gemini entities and data objects, you may wish to study this diagram.

v2 api gemini data model

Each object type with associated fields, endpoints and example representations is described in detail in the Objects list.

Note

The Gemini v2 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 Gemini API exposes lastUpdateDate and createdDate as read-only fields in API responses for all Gemini objects. These fields provide UNIX timestamps for when an object was created and last updated.

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 10,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
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.

Video Tutorials

In this second video tutorial, you’ll learn how to work with RESTful Objects in Programmatic Gemini API - Episode 2.

In the third video tutorial, you’ll learn How To Set up Your Sandbox Environment in the Programmatic Gemini API - Episode 3.

Matrix View of Required fields When Serving Different Ad Types

The Gemini Ad service provides you with methods for adding, updating, and retrieving ads. The following table is a matrix view of required fields when serving different ad types:

Ad Type Campaign-Channel Campaign-Objective Campaign-defaultLandingUrl Bid types Ad-imageUrl Ad-imageUrlHQ Ad-videoPrimaryUrl Assets Ad-mailAssetUrl Ad-imageUrlThumbnail
Search Ad Search, Search_and_Native VISIT_WEB   CPC            
Yahoo Mail Ad Native, Search_and_Native VISIT_WEB, PROMOTE_BRAND   CPC, CPM         required  
Native Stream Ad Native, Search_and_Native VISIT_WEB, PROMOTE_BRAND   CPC, CPM required for CPM required for CPM        
Native Magazine Ad Native, Search_and_Native VISIT_WEB, PROMOTE_BRAND   CPC, CPM required required        
Video Ad (Native) Native PROMOTE_BRAND, VISIT_WEB   CPV, CPM, CPC required required required      
Video Ad (App Install) Native INSTALL_APP app store url CPC required required required      
Install App Ad Native INSTALL_APP app store url CPC required required        
Reengage App Native REENGAGE_APP app store url CPC required required        
Native Carousel Ad Native VISIT_WEB, PROMOTE_BRAND   CPC, CPM required required   required    

Important

The programmatic Gemini API does not rely explicitly on ad types, but rather on a combination of assets and objectives when targeting users and serving ads. This combination is based on campaign settings and objectives, targeting attributes and bid types, as well as landing page URLs, and other required fields used to serve Gemini ads.

For more information on the Gemini Ad object, refer to Ad.

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.