Advertisers

Overview

The AdvertiserService provides methods for retrieving advertiser data. An advertiser is an entity that manages campaigns in Gemini. It has settings such as contact information and billing details, and is able to manage campaigns and view reports for those campaigns. The Yahoo ID you use to log in to Ad Manager can be associated with one or more advertisers.

Fields

The Advertiser object contains the following fields:

Name Description Type
id The ID of the advertiser to retrieve. long
advertiserName The name of the advertiser. string
timezone The timezone of the advertiser. string
currency The currency of the advertiser. string

Endpoint

Resource URI

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

Example Representations

Advertiser

{
  "id": 1,
  "currency": "USD",
  "timezone": "America/New_York",
  "advertiserName": "advertiser1"
}

Advertiser Array

[
   {
    "id": 1,
    "currency": "USD",
    "timezone": "America/New_York",
    "advertiserName": “advertiser1”
   },
   {
    "id": 2,
    "currency": "USD",
    "timezone": "America/New_York",
    "advertiserName": “advertiser2”
   }
]

Advertiser Response

{
   "errors": null,
   "response": {
      "id": 1,
      "currency": "USD",
      "timezone": "America/New_York",
      "advertiserName": "advertiser1"
   }
}

Operations

Read specific advertiser data

Method: To retrieve data for a specific advertiser, make a GET call with the id parameter.

Example: GET call to retrieve an advertiser:

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

The response will be the advertiser associated with the given id:

{
  "errors": null,
  "response": {
      "id": 87292,
      "currency": "USD",
      "timezone": "America/New_York",
      "advertiserName": "company name"
  }
}

Response: The advertiser associated with the given ID.

Example: GET call to retrieve a list of advertisers:

https://api.gemini.yahoo.com/v3/rest/advertiser/?id=134&id=19426

Response: The advertisers associated with the given ids:

{
  "errors": null,
  "response": [
      {
          "id": 134,
          "currency": "USD",
          "advertiserName": "NativeAdvertiser_1",
          "timezone": "America/New_York"
      },
      {
          "id": 19426,
          "currency": "USD",
          "advertiserName": "SearchAdvertiser_1",
          "timezone": "America/New_York"
      }
  ]
}

Read data for filtered list of advertisers

Method: To retrieve data for a filtered list of advertisers, make a GET call with the parameters in the table below:

Name Description Type
id The ID of the advertiser to retrieve. long
mr The maximum number of rows to retrieve. This value should not be greater than 300. int
si The start index or the first element to retrieve. int
status The status of the advertiser to filter the list of advertisers. enum
managedBy This field indicates that the advertiser account has a managing entity that is authorized to perform actions on their behalf. The value should be the id of the reseller that is creating the account, and is immutable once set. long
type This field defaults to ADVERTISER and is read-only. enum
nameContains This field enables you to search by name and can be any part of a name. long

Example: GET call for a filtered list of advertisers:

https://api.gemini.yahoo.com/v3/rest/advertiser/?mr=5

Response: The list of advertisers matching the given filter.

Important

The Advertiser must be a managed account in order to take advantage of the following APIs.

Read specific advertiser budget data

Method: To retrieve data for a specific advertiser budget, make a GET call with the parameters in the table below:

Name Description Type
id The ID of the advertiser to retrieve. long
budget Budget amounts are interpreted in advertiser currency. long
budgetType The allowed budget types are NONE, TOTAL and MONTHLY. string
previousBudget The budget that is currently running and will expire in one day. This is a READ-ONLY parameter. long
previousBudgetType The budget that is currently running and will expire in one day. This is a READ-ONLY parameter. string

Example: GET call to retrieve an advertiser budget:

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


The response will be the advertiser budget associated with the given id:

{
  "errors": null,
      "response": {
            "id": 1365112,
        "budget": 11,
        "budgetType": "TOTAL",
        "previousBudget": null,
        "previousBudgetType": "NONE"
   }
}

Response: The advertiser budget associated with the given ID.

Update existing advertiser budget

Method: To update one or more existing advertiser budgets, make a PUT call to the Advertiser endpoint with one or more budget parameters. Specify the fields to update; please note that id and budgetType are the only required parameters, all other fields are optional. The result will be the list of updated advertiser budgets. The allowed budget types are NONE, TOTAL, MONTHLY.

For example, in order to update the budget for an advertiser:

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

Data passed

      {
              "id":1365112,
              "budgetType":"TOTAL",
              "budget":11
      }

Example response

      {
          "errors": null,
              "response": {
                    "id": 1365112,
                "budget": 11,
                "budgetType": "TOTAL"
           }
      }

Note

Budget amounts are interpreted in advertiser currency.