Campaigns API v2.1

The Campaigns API lets you get a list of campaigns, view the details of a campaign, create a new campaign, or update an existing campaign. In addition, you can set bids on a campaign or define its budget. You cannot delete a campaign with the Campaigns API (but you can pause it).

For the Beta, you can create up to 50 campaigns per account, with up to 2,000 Hotel Groups per campaign.

When you create or edit a campaign using the Campaigns API, you can set bids on that campaign. These bids must adhere to the campaign bidding rules.

All campaigns must be in a sub account. For information on creating or editing sub accounts, see Sub Accounts API.

Paths

GET base_path/api_version/account_id/campaigns
GET base_path/api_version/account_id/campaigns/campaign_id
POST base_path/api_version/account_id/campaigns/create
PUT base_path/api_version/account_id/campaigns/campaign_id/update

Where:

Path Parameter Description
base_path https://www.googleapis.com/travelpartner
api_version v2.1
account_id The ID of the account or sub account for which you want campaign information.
campaign_id A campaign's unique ID. This value is assigned by the Campaigns API when a campaign is created.
create The optional action to create a new campaign as part of a POST request.
update The optional action to edit a campaign's settings as part of a PUT request.

Note that you cannot delete a campaign with the Campaigns API. At any time, however, you can stop a campaign's hotels from participating in auctions by pausing the campaign.

Supported Methods

HTTP Method Description
GET Gets details about all campaigns in an account, or gets details about a single, specified campaign in an account.
POST Creates a new campaign in the specified account with the values set in the HTTP message's body.
PUT Updates an existing campaign with the values set in the HTTP message's body.

Examples

Gets details about all campaigns in account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns

Gets details about campaign 4102 in account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns/4102

Creates a new campaign in account 4200042:

POST https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns/create

You define details about the new campaign in the body of the HTTP request.

Updates campaign 4102 in account 4200042:

PUT https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns/4102/update

You define new details about the campaign in the body of the HTTP request.

Campaign Info object

Details about campaigns are structured as Campaign Info objects in Campaigns API responses. When you create or update a campaign, you use the Campaign Info object in the request.

The following example shows the structure of a Campaign Info object in a response:

{
  "kind": "travelpartner#campaignList",
  "campaigns": [
    {
      "kind": "travelpartner#campaign",
      "account_id": "4200042",
      "campaign_id": "4102",
      "campaign_name": "Sample Campaign",
      "tracking_param": "hct_camp_us_ca",
      "campaign_targets": {
        "user_countries": ["US","CA"],
        "countries_are_targeted": true
      },
      // Set a fixed bid for all hotels and Hotel Groups in the campaign:
      "campaign_bid": {
        "fixed_bid": {
          "amount": 5.00,
          "currency": "USD"
        }
      },
      // Set the daily spending cap for the campaign:
      "daily_spending_cap": {
        "amount": 250.00,
        "currency": "USD"
      }
    }
  ],
  "campaign_last_update_timestamp_micro": "1234567"
}

The following table describes the properties of the Campaign Info object:

Property Type Description
kind String The object type (in a response). This is "travelpartner#campaignList" for campaigns[]. It is "travelpartner#campaign" for each campaign in the array.

The kind property is only included in responses from the Campaigns API. You do not need to specify it in the body of your requests.

account_id String The ID of the account or sub account to which the campaign belongs.
campaign_id String The campaign's unique ID. This value is assigned by the Campaigns API when it creates a new campaign.
campaign_name String The name of the campaign.
tracking_param String Passed via a landing page (point of sale) parameter when the click is from this campaign so that you can track its source.

The string must be less than or equal to 80 characters in length, and consist of ASCII letters, digits, hyphens, periods, underscores, or tildes only.

For more information, see:

campaign_targets Array of Strings Location-specific targets of the campaign. This object contains the following properties:

  • user_countries: An array of 2-letter country codes that represent countries that are either included in or excluded from this campaign. For example, "['US','CA']".
  • countries_are_targeted: A boolean that indicates whether or not the list of user_countries is included or excluded in the campaign.

    If true, then the list of countries is included in the campaign. If false, then the list of countries is excluded from the campaign. If user_countries is not specified, then all countries are targeted.

If you do not specify a value for campaign_targets when creating a new campaign, the default is to include all countries in the campaign.

campaign_bid bid object The campaign-level bid for this campaign. This object uses the same syntax as the bid object in a Bids API v2.1 update request, but the bidding model is different.

For more information, see Campaign bidding rules.

daily_spending_cap budget object The budget for this campaign. The budget object defines the campaign's daily spending cap.

For more information, see Set a campaign's budget.

campaign_last_update_timestamp_micro String Shows the last time in micro seconds when this campaign was updated, excluding bid rate updates.

Get campaign details

You can use the Campaigns API to get details about a single campaign, or all campaigns in an account.

Request

One campaign

To get details about a single campaign, submit a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_id/campaigns/campaign_id

The following example gets details about campaign 4102:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns/4102

All campaigns

To get details about all campaigns in an account, submit a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_id/campaigns

The following example gets details about all campaigns in account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns

Response

The Campaigns API responds with an array of Campaign Info objects. The following example shows a response with two Campaign Info objects:

{
  "kind": "travelpartner#campaignList",
  // Array of Campaign Info objects
  "campaigns": [
    // First Campaign Info object
    {
      "kind": "travelpartner#campaign",
      "account_id": "4200042",
      "campaign_id": "4102",
      "campaign_name": "Sample Campaign 1",
      "tracking_param": "hct_camp_us_ca",
      "campaign_targets": {
        "user_countries": ["US","CA"],
        "countries_are_targeted": true
      },
      "campaign_bid": {
        "fixed_bid": {
          "amount": 5.00,
          "currency": "USD"
        }
      },
      "daily_spending_cap": {
        "amount": 250.00,
        "currency": "USD"
      }
    },
    // Second Campaign Info object
    {
      "kind": "travelpartner#campaign",
      "account_id": "4200042",
      "campaign_id": "7891011",
      "campaign_name": "Sample Campaign 2",
      "tracking_param": "hct_camp_fr",
      "campaign_targets": {
        "user_countries": ["FR"],
        "countries_are_targeted": true
      },
      "campaign_bid": {
        "percent_bid": 8.0  // Set a percent bid of 8.0%
      },
      "daily_spending_cap": {
        "cleared": true  // Sets the budget to unlimited
      }
    }
  ],
  "campaign_last_update_timestamp_micro": "1234567890"
}

Create a new campaign

You can use the Campaigns API to create a new campaign. You define the details about the new campaign as a Campaign Info object in the body of the HTTP request.

For the Beta, you can create up to 50 campaigns per account, with up to 2,000 Hotel Groups per campaign.

Request

To create a new campaign, submit a POST request with the following syntax:

POST https://www.googleapis.com/travelpartner/v2.1/account_id/campaigns/create

The body of the request defines the campaign details. The following fields are required when creating a new campaign:

  • campaign_name
  • campaign_bid

All other fields are optional.

When creating a new campaign, the campaign_id field must be empty. The Campaigns API assigns an ID when the campaign is created. You can use this ID on subsequent requests.

The following example shows the body of a request that creates a new campaign:

// Do not specify a campaign_id in a create request; the Campaigns API
// will assign one to the new campaign
{
  "campaign": {
    "account_id": "4102",
    "campaign_name": "Sample Campaign",  // Required
    "tracking_param": "hct_camp_us_ca",
    "campaign_targets": {
      "user_countries": ["US","CA"],
      "countries_are_targeted": true
    },
    // Required
    // Sets a fixed bid for the campaign
    "campaign_bid": {
      "fixed_bid": {
        "amount": 5.00,
        "currency": "USD"
      }
    },
    // Set the daily spending cap for the campaign
    "daily_spending_cap": {
      "amount": 250.00,
      "currency": "USD"
    }
  }
}

If you do not define campaign_targets, the default is to include all countries in the campaign. If you do define campaign_targets, the countries_are_targeted field is required (true or false); the user_countries field is optional; it defaults to all countries if unspecified.

When creating a new campaign, be sure that you understand the campaign bidding rules.

If you create a new campaign, but do not specify the daily_spending_cap, the campaign stops serving when the account's budget is reached.

Response

For a successful campaign creation request, the Campaigns API responds with a Campaign Info object that describes the new campaign. This object includes the new campaign's ID.

Update a campaign

You can use the Campaigns API to update the details about an existing campaign. You define the details about the campaign as a Campaign Info object in the body of the HTTP request.

When updating a campaign, all fields in the request are optional except campaign_id. You cannot change this value. All other fields maintain their existing values unless you explicitly override them in the update.

If you change the campaign's bid type, all of the existing group- and hotel-level bids will be deleted.

Request

To update a campaign, submit a PUT request with the following syntax:

PUT https://www.googleapis.com/travelpartner/v2.1/account_id/campaigns/campaign_id/update

The following example updates campaign 4102 in account 4200042:

PUT https://www.googleapis.com/travelpartner/v2.1/4200042/campaigns/4102/update

The following example shows the body of a request that updates the bid rate to 6.5% (all other values remain unchanged) for campaign 4102:

{
  "campaign": {
    "campaign_id": "4102",  // Required
    "campaign_bid": {
      "percent_bid": 6.5  // Changes campaign bid to 6.5%
    }
  }
}

When updating a new campaign, be sure that you understand the campaign bidding rules.

Response

For a successful campaign update request, the Campaigns API responds with a Campaign Info object that describes the updated campaign.

Set a campaign's budget

You can use the Campaign API to define the campaign's daily spending cap. You do this with the daily_spending_cap field.

The following example shows the syntax for setting a campaign's budget:

...
"daily_spending_cap": {
  "amount": decimal_value,  // Must be at least $100 USD
  "currency": "currency_code"
}
...

The minimum value for the daily spending cap is $100 USD. Any value between $.01 and $99.99 is interpreted as a cap of $100 USD.

For small campaigns, Google might exceed the cap. This could happen if your campaign's cap is less than your account's cap. Note that Google will never exceed your account's cap; if it does, Google will refund the overage.

If you create a new campaign, but do not specify a budget, the campaign stops serving when the account's budget is reached.

To set a budget to be unlimited, set daily_spending_cap.cleared to true, as the following example shows:

...
"daily_spending_cap": {
  "cleared": true  // Sets the budget to unlimited
}
...

Pause a campaign

You can "pause" a campaign at any time. When a campaign is paused, the campaign's hotels will not participate in auctions.

To pause a campaign, you use the Bids API, as described in Pausing bidding.

Campaigns API Changes

Changes to version 2.1 of the Campaigns API include the following:

  • You cannot set the maximum bid at the campaign level.
  • campaign_budget.account_daily has been renamed to daily_spending_cap.
  • To explicitly clear the campaign's spending cap, set daily_spending_cap.cleared to true.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
  • Responses now include a campaign_last_update_timestamp_micro field.