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.

Object Types & Capabilities

The v1 Gemini API object types include:

Type Description
Ad Provides methods for adding, updating, and retrieving ads.
Ad Extensions Enables your ads to take up more real estate and to offer more details and value to your customers.
Ad Group Provides methods for creating, updating, and retrieving ad groups.
Advertisers Provides methods for retrieving advertiser data.
Campaigns Provides methods for creating, updating, deleting and retrieving campaigns.
Keyword Specifies the search keyword phrase that you would like to target.
Targeting Attribute Specifies objects that can be used for targeting.

How It Works

Each object representation – Ad, Ad Group, Advertiser, Campaign, Keyword – 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.admanager.yahoo.com/v1/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"
   }
}

The data model for the Gemini API is not based on services, but rather on calling the same RESTful object with a different HTTP method.

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.