Bids API v2.0

The Bids API lets you submit real-time bids and get the bids that you have submitted, including any multipliers applied to those bids. You must use this API or the Hotel Ads Center to set bids on hotels in sub accounts.

Path

base_path/api_version/account_id/bids[/update]

Where:

Path Parameter Description
base_path https://www.googleapis.com/travelpartner
api_version v2.0
account_id A parent account or sub account ID. If you specify a parent account, then data for all sub accounts in addition to the parent account is included.You must specify the sub account ID to set a bid on a hotel in that sub account. You cannot set a bid on a hotel in a sub account if you specify the parent account in the URL.
update The optional action to submit new bids as part of a PUT request. If you do not specify update, then the Bids API returns a list of current bids.

Query String Parameters (all parameters are optional)

Parameter Required? Description
account_default Optional (GET requests only) A boolean that indicates whether or not to return changes to the Account Default Bid only. Set to true to return account default bid changes; otherwise, false. The default value is false.

If you do not specify a value for this property, group_ids, or hotel_ids, then the Bids API returns bids for all properties, up to the maximum number of results (maxresults).

group_ids Optional (GET requests only) A comma-separated list of Hotel Group IDs for which you want to get bid information. Restricts the retrieved bids to the specified groups.

If you do not specify a value for this property, account_default, or hotel_ids, then the Bids API returns bids for all properties, up to the maximum number of results (maxresults).

hotel_ids Optional (GET requests only) A comma-separated list of hotels for which you want to get bid information. Restricts the retrieved bids to the specified hotels.

If you do not specify a value for this property, account_default, or group_ids, then the Bids API returns bids for all properties, up to the maximum number of results (maxresults).

id Optional (update action only) Specifies a unique ID for the current bid update. This value is stored with the update and not with individual bids within the update.

You can later view this as the value of the partner_id property when you use the Feed Status API to get your feed status. For more information, see Getting Feed Status.

maxresults Optional (GET requests only) Specifies the maximum number of results per page. Valid values are positive integers up to 16,384 (2^14). The default value is 16,384.

nextrow Optional (GET requests only) Specifies a random string that represents an offset for your query. For more information, see Using Offsets.
return_effective_bids Optional (GET requests only) Determines whether to return effective or actual bids. An actual bid is the bid that you submitted. An effective bid is the bid that a hotel inherits from a Hotel Group or campaign default, or a Hotel Group inherits from the campaign default.

The default value is "true", meaning the Bids API returns effective bids by default.

timestamp Optional (update action only) Specifies a timestamp for the current bid update. This value is stored with the update and not with individual bids within the update.

You can later view this as the value of the partner_timestamp property when you use the Feed Status API to get your feed status. For more information, see Getting Feed Status.

Supported Methods

HTTP Method Description
GET Gets a list of bids; you can get all bid information, or narrow the results by Hotel Groups, hotel IDs, and/or the account default bid.
PUT Updates bids with values set in the HTTP message's body.

Examples

Lists bids for the specified account:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids

Lists "actual" bids for the specified account (not "effective" bids):

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids?return_effective_bids=false

Lists changes to the account default bid only:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids?account_default=true

Lists bids for the specified hotels only:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids?hotel_ids=1066,1492

Lists bids for the specified Hotel Groups only:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids?group_ids=dQw4w9WgXcQ,LbK9EjeloG8

Lists bids for the specified hotel, Hotel Group, and the account default only:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids?hotel_ids=1066&account_default=true&group_ids=dQw4w9WgXcQ

Updates bids:

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/bids/update

Updates bids and sets the ID and timestamp:

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/bids/update?id=420&timestamp=123456789

Listing bids

You can use the Bids API to get a list of bids for the specified account. You can get the account default bid and all hotels that use it, a list of bids for specific hotels, and a list of bids by Hotel Group.

To get a list of all bids in an account, submit a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.0/account_id/bids

The following example lists all bids for account ID "4200042":

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids

The account ID can be a parent or sub account. If you specify a parent account, then the Bids API includes the parent account's bids in addition to the bids of all sub accounts.

To list bids for specific hotels, submit a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.0/account_id/bids?hotel_ids=hotel_1[,...]

The following example gets the bids for the two specified hotels with IDs "1066" and "1492":

GET https://www.googleapis.com/travelpartner/v2.0/4200042/bids?hotel_ids=1066,1492

You can also restrict the list of results by Hotel Group or to just the account default bid information by using the groups_id or account_default query string parameters, respectively.

Bids list results

For list actions, the Bids API responds with a bids object that uses the following syntax:

{
  "bids": [
    {
      "bid_targets": {
        ... // Account default, list of hotels, or list of Hotel Groups
      },
      "bid": {
        ... // Bid details plus applicable Bid Multipliers
      },
      "base_bid_source":   < "Account default bid" | "Group bid" | "Hotel bid" | "None" >,
      "multiplier_source": < "Account default bid" | "Group bid" | "Hotel bid" | "None" >,
      "last_update_time": "YYYY-MM-DD HH:MM:SS"
    }
  ]
}

Each bids object contains the following:

  • (GET and PUT) bid_targets: Identifies the properties to which the bid applies. For more information, see bid_targets object.
  • (GET and PUT) bid: Describes the bid and any applicable Bid Multipliers. For more information, see bid object.
  • (GET only) base_bid_source: Identifies the target(s) of the bid. Can be one of the following:
    • "Account default bid": The base bid was made as an account default bid.
    • "Group bid": The base bid was made on a Hotel Group.
    • "Hotel bid": The base bid was made directly on individual hotels.
    • "None": There is no base bid on the specified targets.
  • (GET only) multiplier_source: Identifies the target on which the Bid Multiplier was set. Can be one of the following values:
    • "Account default bid": The Bid Multiplier was set on the account default bid.
    • "Hotel bid": The Bid Multiplier was set on an individual hotel.
    • "Group bid": The Bid Multiplier was set on a Hotel Group.
    • "None": There is no Bid Multiplier for the specified bid.
  • (GET only) last_update_time: The date and time (in YYYY-MM-DD HH:MM:SS format) at which the bid was submitted to Google.

The following example shows a simple response from a Bids API GET request. This response shows the most recent account default bid, a bid on two hotels, and a bid on a Hotel Group:

{
  "bids": [
    // Account default bid
    {
      "bid_targets": {
        "account_default": true
      },
      "bid": {
        "percent_bid": 5,
        "multipliers": [
          {
             "multiplier": 0.6,
             "device_types": [
               "mobile",
               "tablet"
             ]
          },
          {
            "multiplier": 1.2,
            "sites": [
              "localuniversal"
            ]
          }
        ]
      },
      "base_bid_source": "Account default bid",
      "multiplier_source": "Account default bid",
      "last_update_time": "2016-05-09 12:41:53"
    },
    // Bid on two specific hotels
    {
      "bid_targets": {
        "hotel_ids": [
          "1066","1492"
        ]
      },
      "bid": {
        "percent_bid": 2.0,
        "multipliers": [
          {
            "multiplier": 0.8,
            "booking_window_min_days": 3
          }
        ]
      },
      "base_bid_source": "Account default bid",
      "multiplier_source": "Account default bid",
      "last_update_time": "2016-01-27 08:21:34"
    },
    // Bid on a Hotel Group
    {
      "bid_targets": {
        "group_ids": [
            "dQw4w9WgXcQ"
        ]
      },
      "bid": {
        "percent_bid": 5,
        "multipliers": [
          {
            "multiplier": 0.6,
            "device_types": [
              "mobile"
            ]
          },
          {
            "multiplier": 1.2,
            "sites": [
              "localuniversal"
            ]
          }
        ]
      },
      "base_bid_source": "Account default bid",
      "multiplier_source": "Account default bid",
      "last_update_time": "2016-05-09 12:41:53"
    }
  ]
}

Bids API objects

This section describes the bid and bid_targets objects. In a GET request, these objects display the bids and the targets of those bids. In a PUT request, you use these objects to set the bids and identify the targets of those bids.

bid_targets object

The bid_targets object defines the hotels or Hotel Groups to which the bid applies. Bid targets can include one or more of the following:

  • account_default: The bid is used as your account’s default bid.
  • hotel_ids: A comma-separated list of one or more individual hotel IDs to which the bid applies.
  • group_ids: A comma-separated list of one or more Hotel Groups to which the bid applies.

The bid_targets object uses the following syntax:

"bid_targets": {

  // One of the following:

  "account_default": < true|false >

  // AND/OR

  "hotel_ids": [
    "hotel_id_1",
    "hotel_id_2",
    ...
  ]

  // AND/OR

  "group_ids": [
    "group_id_1",
    "group_id_2",
    ...
  ]

}

The following example sets the account default bid to $5.00 USD:

"bid_targets": {
  "account_default": true,
  "bid": {
    "fixed_bid": {
      "amount": 5.00,
      "currency": "USD"
    }
  }
}

When listing bids (GET request), each bid will only be paired with one type of target. When setting bids, you can specify only one type of target (account default, groups, or individual hotels) for each bid and set of Bid Multipliers.

bid object

The bid object defines the bids that are applied to the specified bid targets. For each target, you can apply one of the following types of bids:

  • fixed_bid: Sets the specified fixed bid amount on the targets, in the specified currency.
  • percent_bid: Sets the % CPC on the targets.
  • target_roas: Sets the target ROAS on the specified targets. This bid type can be applied only to Hotel Group targets.
  • automatic_multipliers: Enables Automatic Bid Multipliers. If omitted, it defaults to false. Cannot be used in conjunction with the multipliers key.

The bid object can optionally include an array of Bid Multipliers that apply to the bid with the multipliers object.

The bid object uses the following syntax:

"bid": {
  // One of the following:
  "fixed_bid": {
    "amount": <bid_amount>,
    "currency": "<3-letter_currency_code>"
  },

  // OR

  "percent_bid": <rate>,

  // OR

  "target_roas": <target_amount>,

  // OR

  "automatic_multipliers": <true|false>,

  // OR
  // Only settable on Hotel Groups, which must have at least 100 hotels,
  // and the account must have conversion tracking enabled
  "commission_net_of_cancellations": <rate>,

  // Optionally:
  "multipliers": [
    {
      multiplier: <decimal_multiplier_value>,

      // One of the following per multiplier:
      "checkin_days_of_week": [One or more of "Monday","Tuesday","Wednesday","Thursday",
                               "Friday","Saturday","Sunday" ]
      "user_countries":       [ One or more 2-letter country codes ]
      "sites":                [ One or more of "mapresults","placepage","localuniversal" ]
      "device_types":         [ One or more of "desktop","mobile","tablet" ]
      "length_of_stay_min_nights": <num_nights>
      "booking_window_min_days": <num_days>
      "date_types": [ "default" | "selected" ]
    }
  ],
  "cleared_bid": true  // Clears the bids for the specified targets; omit if false
}

The following example sets a percentage bid with several Bid Multipliers on two hotels:

{
  "bids": [
    {
      "bid_targets": {
        "hotel_ids": [
          "1066",
          "1492"
        ]
      },
      "bid": {
        "percent_bid": 5.0,
        "multipliers": [
          {
            "multiplier": 2.0,
            "sites": [
              "mapresults",
              "placepage"
            ]
          },
          {
            "multiplier": 2.5,
            "length_of_stay_min_nights": 2
          },
          {
            "multiplier": 3.0,
            "user_countries": [
              "US",
              "CA"
            ]
          }
        ] // end multipliers array
      } // end bid object
    }, // end bid container
    ...
  ] // end bids array
} // end message container

Setting bids

You can use the Bids API to update the account default bid, or set bids on Hotel Groups or individual hotels.

When setting bids, you should limit the size of your request to 4MB. If you experience issues with requests of this size, try limiting your requests to 2MB. You can issue up to 3 concurrent requests, as long as they do not affect the same bid targets.

To update bids, submit a PUT request to the update action of the Bids API using the following syntax:

PUT https://www.googleapis.com/travelpartner/v2.0/account_id/bids/update

You must set the request’s Content-Type header to “application/json”.

Define the bids in the body of the HTTP message with the root bids object. The bids object contains an array of objects that pair bid targets with bids, as the following example shows:

{
  "bids": [
    // Set an account default bid
    {
      "bid_targets": {
        "account_default": true
      },
      "bid": {
        "percent_bid": 4.20
      }
    },

    // Set a fixed bid on two individual hotels
    {
      "bid_targets": {
        "hotel_ids": [
          "1492", "1620"
        ]
      },
      "bid": {
        "fixed_bid": {
          "amount": 5.0,
          "currency": "USD"
        }
      }
    },

    // Set a percent bid on a Hotel Group
    {
      "bid_targets": {
        "group_ids": [
          "dQw4w9WgXcQ"
        ]
      },
      "bid": {
        "percent_bid": 5.0
      }
    }
  ]
}

To help reduce the size of your bid requests, use bid targets to match identical bids to multiple targets. You can combine group IDs, individual hotels, and the account default bid in the same bid_targets block.

Setting bids examples

This section shows some examples of how to set bids using the Bids API.

Check-in Days of Week multiplier example

The following example applies a Bid Multiplier to Hotel Groups based on the days of the week that the end-user wants to check in:

{
  "bids": [
    {
      "bid_targets": {
        "hotel_ids": [
          "1066",
          "1492"
        ]
      },
      "bid": {
        "percent_bid": 5.0,
        "multipliers":  [
          {
            "multiplier": 1.125,
            "checkin_days_of_week": [
              "Monday",
              "Tuesday",
              "Wednesday",
              "Sunday"
            ]
          }
        ]
      }
    }
  ]
}

Booking window multiplier example

The following example applies a Bid Multiplier to two Hotel Groups, based on the days of the week that the end-user wants to check in:

{
  "bids": [
    {
      "bid_targets": {
        "group_ids": [
          "dQw4w9WgXcQ",
          "LbK9EjeloG8"
        ]
      },
      "bid": {
        "percent_bid": 5.0,
        "multipliers": [
          {
            "multiplier": 7.0,
            "booking_window_min_days": 10
          }
        ]
      }
    }
  ]
}

Multiple multiplier example

The following example applies more than one Bid Multiplier to a Hotel Group bid:

{
  "bids": [
    {
      "bid_targets": {
        "group_ids": [
          "dQw4w9WgXcQ",
          "LbK9EjeloG8"
        ]
      },
      "bid": {
        "percent_bid": 5,
        "multipliers": [
          {
            "multiplier": 0.9,
            "device_types": [
              "mobile",
              "tablet"
            ]
          },
          {
            "multiplier": 1.2,
            "sites": [
              "localuniversal"
            ]
          }
        ]
      }
    }
  ]
}

Automatic Bid Multiplier Example

In the following example, the bid object enables the Automatic Bid Multiplier (ABM). Do not include the multipliers key when automatic_multipliers is enabled.

{
  "bids": [
    {
      "bid_targets": {
        "group_ids": [
          "dQw4w9WgXcQ",
          "LbK9EjeloG8"
        ]
      },
      "bid": {
        "percent_bid": 5,
        "automatic_multipliers": true
      }
    }
  ]
}

Date types multiplier example

The following example applies a Bid Multiplier to Hotel Groups based on the date type:

{
  "bids": [
    {
      "bid_targets": {
        "hotel_ids": [
          "1066",
          "1492"
        ]
      },
      "bid": {
        "percent_bid": 5.0,
        "multipliers":  [
          {
            "multiplier": 2.0,
            "date_types": [
              "selected"
            ]
          }
        ]
      }
    }
  ]
}

Valid values for the date_types Bid Multiplier are 0.5 to 2.0, inclusive.

Clearing bids

You can use the cleared_bid field to reset the bid for the specified bid targets. Set to true to clear the bid; otherwise, you may omit this field (you do not need to set it to false).

This option cannot be used in combination with any other field in the bid object.

The following example clears the bids for the specified targets:

{
  "bids": [
    // Clear individual hotel bids
    {
      "bid_targets": {
        "hotel_ids": [ "h1", "h3"]
      },
      "bid": {
        "cleared_bid": true
      }
    },
    // Clear a campaign default bid:
    {
      "bid_targets": {
        "campaign_default": true
      },
      "bid": {
        "cleared_bid": true
      }
    }
  ]
}

Clearing Bid Multipliers

You can clear Bid Multipliers by submitting a bid update request with an empty multipliers array, as the following example shows:

{
  "bids": [
    {
      "bid_targets": {
        "hotel_ids": [
          "1066",
          "1492"
        ]
      },
      "bid": {
        "percent_bid": 5.0,
        "multipliers":  []  // Clears Bid Multipliers for the specified targets
      }
    }
  ]
}

Bid update responses

For bid updates, the Bids API returns a “0” if the bid update request was successful:

{
  "response": "0"
}

If an update request fails, the Bids API returns an error object that contains specific information about the reason for failure. If the error is related to the size of the request, try reducing your request size to 2MB.

The Bids API stores bids on invalid hotels (hotels whose IDs have not yet been assigned to the current account). If one of those hotels is later assigned to the account, the previous bid will be applied.

Bids API changes

Changes to v2.0 of the Bids API include the following:

  • The cleared_bid field has been added to the bid object.
  • Device type bid multipliers now support "tablet", "desktop", and "mobile".
  • You can now set bids via the Bids API.
  • The Bids API uses the new RESTful syntax.
  • All results are returned as JSON.

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.