Groups API v2.1

The Groups API lets you programmatically manipulate Hotel Groups. With the API, you can create, delete, or rename groups. You can also add and remove hotels to and from Hotel Groups.

Note that with version 2.1 of the API, biddable groups must belong to a campaign. If a group is not in a campaign, you cannot place bids on that group.

Paths

GET base_path/api_version/account_or_campaign_id/groups
GET base_path/api_version/account_or_campaign_id/groups/group_id
GET base_path/api_version/account_id/groups/group_id/ungrouped *
POST base_path/api_version/account_or_campaign_id/groups/create/group_name
POST base_path/api_version/account_or_campaign_id
/groups/create
PUT base_path/api_version/account_or_campaign_id/groups/group_id/add_hotels
PUT base_path/api_version/account_or_campaign_id/groups/group_id/remove_hotels
PUT base_path/api_version/account_or_campaign_id/groups/group_id/rename/group_name
DELETE base_path/api_version/account_or_campaign_id/groups/group_id/delete
GET base_path/api_version/account_or_campaign_id/groups/lookup/hotel_name

(* Note that to get the ungrouped hotels in a campaign, you specify the ungrouped group's ID as a path parameter, as you would with any other custom group. You cannot use the ungrouped path parameter. For more information, see Listing ungrouped hotels.)

Where:

Path Parameter Description
base_path https://www.googleapis.com/travelpartner
api_version v2.1
account_or_campaign_id A campaign ID (for biddable groups) or a master or sub account ID for non-bidable groups. Actions with this API apply to this campaign or account's groups only.
group_id The unique 11-character ID that identifies the group. This is a required path parameter for all calls to the Groups API except listing group names and creating a new group.
add_hotels Moves hotels not currently in a group to a Hotel Group during a PUT action.
create Creates a new Hotel Group during a POST action.
delete Deletes a Hotel Group during a DELETE action.
lookup Gets the name of the groups for the specified hotel or hotels during a GET action.
remove_hotels Removes hotels from a Hotel Group and puts them in the special "ungrouped" Hotel Group during a PUT action.
rename Renames a Hotel Group during a PUT action.
ungrouped A special path parameter that references the ungrouped group for accounts and sub accounts.

Use this path parameter to get the ungrouped hotels in an account or sub account. To get the ungrouped hotels in a campaign, you must specify the ungrouped group's ID in the path, as you would any other custom group ID.

For more information, see Listing ungrouped hotels.

Query String Parameters

Parameter Description
hotel_ids (Optional, lookup requests only) A comma-separated list of hotel names that you can use when looking up a hotel's group affiliation (one of the GET actions).

For more information, see Looking up groups by hotel ID.

min_update_version (Optional, all requests) An incremented value that represents the version of the Hotel Groups in the account or campaign. You can use this so that an operation does not take effect until a particular version is available.

For example, to ensure that a read call is accessing the current version from the cache, your call can include the previous write call's min_update_version.

Supported Methods

HTTP Method Description
GET Lists all Hotel Groups for an account, sub account, or campaign. Also lists all hotels in the specified Hotel Group.
POST Creates a new Hotel Group.
DELETE Deletes the specified Hotel Group.
PUT Adds or removes hotels from a group; renames the specified Hotel Group.

Examples

Lists all Hotel Groups for campaign 4102:

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

Lists all hotels in account 4200042 and group 12345678911:

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

Gets a list of all ungrouped hotels for sub account 4200042:

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

Gets a list of all ungrouped hotels for campaign 4102, where the ungrouped group's ID is 0042:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/0042

Creates a new group named "Brand B" in campaign 4102:

POST https://www.googleapis.com/travelpartner/v2.1/4102/groups/create/Brand%20B

Adds previously ungrouped hotels in campaign 4102 to group 12345678911:

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911/add_hotels

Removes hotels in campaign 4102 from group 12345678911 (and adds them to the ungrouped group):

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911/remove_hotels

Renames the group in campaign 4102 with the ID 12345678912 to "New Name":

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678912/rename/New%20Name

Deletes group 12345678911 from campaign 4102:

DELETE https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911/delete

Gets the group affiliation for Hotel 1 in the specified campaign 4102:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/lookup/Hotel%201

Gets the group affiliations for Hotel 1, Hotel 2, and Hotel 3 in campaign 4102:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/lookup?hotel_ids=Hotel%201,Hotel%202,Hotel%203

Listing Hotel Groups

You can use the Groups API to get a list of all Hotel Groups in your account, sub account, or campaign. For campaigns, this listing also includes the special ungrouped group.

To get a list of Hotel Groups, execute a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups

The following example gets a list of all Hotel Groups in campaign 4102:

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

The Groups API responds with an array of group names and their corresponding IDs in a hotel_groups object, as the following example shows:

{
  "hotel_groups": [
    {
      "group_id": "12345678911",
      "group_name": "Brand A",
      "group_last_update_timestamp_micro": "1234567"
    },
    {
      "group_id": "12345678912",
      "group_name": "Brand B",
      "group_last_update_timestamp_micro": "1234567"
    },
    {
      "group_id": "12345678913",
      "group_name": "Brand C",
      "group_last_update_timestamp_micro": "1234567"
    },
    {
      "group_id": "0042",
      "group_name": "",  // An empty string for the name indicates the "ungrouped" group
      "group_last_update_timestamp_micro": "1234567"
    }
  ],
  "update_version": "42"

}

In addition to a list of Hotel Group names and IDs, the response also contains the update_version, which is an incremented value that represents the version of the most recent change.

The response also includes the group_last_update_timestamp_micro field, which shows the last time in micro seconds when each group was updated, excluding bid rate updates.

You can optionally specify the minimum update version in a request, as the following example shows:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups?min_update_version=42

Listing hotels in a Hotel Group

You can use the Groups API to get a list of all hotels in a Hotel Group in an account or campaign.

To list all hotels in a Hotel Group, execute a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/group_id

The following example lists all hotels in Hotel Group 12345678911 for campaign 4102:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911

The Groups API response includes a hotel_ids array that contains the names of all hotels in the specified group, as the following example shows:

{
  "group_id": "12345678911",
  "group_name": "Brand A",
  "hotel_ids": [
    "h1066",
    "h1492",
    "h1620",
    "h1971"
  ],
  "update_version": "42",
  "group_last_update_timestamp_micro": "1234567890"
}

You can optionally specify the minimum update version, as the following example shows:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911?min_update_version=42

Listing ungrouped hotels

Ungrouped hotels are hotels that do not belong to any group, and therefor belong to the special "ungrouped" group. Note that you cannot rename or delete the ungrouped group. You also cannot explicitly add or remove hotels from the ungrouped group. (You implicitly add hotels to the ungrouped group by removing them from their current group, as described in Removing hotels from a Hotel Group.)

You can set bids on a campaign's ungrouped group using the Bids API.

Accounts and sub accounts

To list all ungrouped hotels in an account or sub account, use the special group name "ungrouped". To do this, execute a GET request with the following syntax:

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

The following example gets a list of all ungrouped hotels in account 4200042:

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

Campaigns

To list all ungrouped hotels in a campaign, use the ungrouped group's ID in the URL, as you would any other custom group ID. For example, if the campaign ID is 4102 and the ungrouped group's ID is 0042, use the following URL:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/0042

If you do not know the ungrouped group's ID, get a list of Hotel Groups as described in Listing Hotel Groups.

Adding hotels to a Hotel Group

You can use the Groups API to add one or more ungrouped hotels to the specified Hotel Group. You cannot explicitly add hotels to the special ungrouped group.

A hotel can be in only one Hotel Group at a time. Only an ungrouped hotel can be added to a Hotel Group. If a hotel is already in a group, it must first be removed from its current group before it can be added to a different group.

To add ungrouped hotels to a Hotel Group, execute a PUT request with the following syntax:

PUT https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/group_id/add_hotels

The following example adds ungrouped hotels to the group "12345678911" in campaign 4102:

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911/add_hotels

To define which hotels to add to a group, list the hotel IDs in the hotel_ids array in the HTTP message body. The following example message body lists two new hotels to add to a Hotel Group:

{
  "hotel_ids": [
    "h1066",
    "h1977"
  ]
}

If the target Hotel Group does not exist, the Groups API creates a new group with the name that you provided.

The maximum number of hotels that you can add to a group at one time is 30,000. This is the number of hotels that are specified in the API request, not the total number of hotels affected by the request. For example, you can have more than 30,000 hotels in a group that are affected by the request.

If a hotel is already in a Hotel Group when you attempt to add it to another group, the API returns the following error:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "alreadyExists",
        "message": "Conflict"
      }
    ],
    "code": 409,
    "message": "Conflict"
  }
}

Removing hotels from a Hotel Group

You can use the Groups API to remove hotels from a Hotel Group. After you remove a hotel from a Hotel Group, it becomes ungrouped (a member of the special ungrouped Hotel Group) until it is added to another group. You cannot use the Groups API to explicitly remove a group from the special ungrouped group.

To remove hotels from a Hotel Group, execute a PUT request with the following syntax:

PUT https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/group_id/remove_hotels

The following example removes the specified hotels from the "12345678911" group in campaign 4102:

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678911/remove_hotels

To specify which hotels to remove from a Hotel Group, add a list of hotel IDs to the hotel_ids array in the HTTP message body.

The following example specifies that hotels with the IDs h1066 and h1977 should be removed from their group:

{
  "hotel_ids": [
    "h1066",
    "h1977"
  ]
}

The maximum number of hotels that you can remove from a group at one time is 30,000. This is the number of hotels that are specified in the API request, not the total number of hotels affected by the request. For example, you can have more than 30,000 hotels in a group that are affected by the request.

Creating a Hotel Group

You can use the Groups API to create a Hotel Group in an account or campaign. Hotel Group names can be anything you want, except "ungrouped". That name is reserved.

To create a Hotel Group, execute a POST request with the following syntax:

POST https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/create/group_name

The following example adds ungrouped hotels to the group "Brand B" in campaign 4102:

POST https://www.googleapis.com/travelpartner/v2.1/4102/groups/create/Brand%20B

If you create a new Hotel Group whose name contains spaces or special characters, you must URL encode the name in the URL (such as replacing a space with "%20").

The Groups API responds with a message that contains the new group's unique ID and the updated_version, as the following example shows:

{
  "group_id": "12345678914",
  "update_version": "42",
  "group_last_update_timestamp_micro": "1234567890"
}

New groups do not have any hotels assigned to them. You can create a new group and add hotels to it at the same time by using the add_hotels action. (If the group name does not already exist, the Groups API creates a new group for you.)

You can optionally specify the minimum update version when creating a new Hotel Group, as the following example shows:

POST https://www.googleapis.com/travelpartner/v2.1/4102/groups/create/Brand%20B?min_update_version=42

Creating multiple Hotel Groups

To create multiple Hotel Groups, you'll need to send a POST request to:
POST https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/create/
The body of the request should specify the new group names:

{
  "group_names": [
    "group 1",
    "group 2",
    ...
  ]
}
This command returns a list of group IDs, which will be in the same order as you specified in the request. For example if you specified group IDs in order as "AAAAAAG" and "AAAAAAH" you would see the following response:

{
  "group_ids": {
    "AAAAAAG",
    "AAAAAAH",
    ...
  }
  "update_version": "1234567890"
}

Renaming a Hotel Group

You can use the Groups API to change the name of a custom Hotel Group. You cannot change the name of the special ungrouped group.

To rename a Hotel Group, execute a PUT request with the following syntax:

PUT https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/group_id/rename/new_group_name

The following example renames group 12345678912 in campaign 4102 to "New Name":

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678912/rename/New%20Name

You can optionally specify the minimum update version, as the following example shows:

PUT https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678912/rename/New%20Name?min_update_version=42

Deleting a Hotel Group

You can use the Groups API to delete a Hotel Group from an account or campaign. You cannot delete the special ungrouped group.

To delete a Hotel Group, execute a DELETE request with the following syntax:

DELETE https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/group_id/delete

The following example deletes Hotel Group 12345678914 from campaign 4102:

DELETE https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678914/delete

You can optionally specify the minimum update version, as the following example shows:

DELETE https://www.googleapis.com/travelpartner/v2.1/4102/groups/12345678914/delete?min_update_version=42

If you delete a Hotel Group that contains hotels, then all hotels in the group are reverted to the special ungrouped group within that campaign or account.

Looking up groups by hotel ID

You can use the Groups API to look up a hotel's group affiliation by the hotel's ID. The response includes the name of the group and its ID, as well as a list of only the requested hotels that in the group.

To look up a hotel's group affiliation, execute a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/lookup/hotel_id

The following example looks up the group for hotel h101 in campaign 4102:

GET https://www.googleapis.com/travelpartner/v2.1/4102/groups/lookup/h101

The Groups API responds with a hotel_groups object that contains details about the hotel's group, including the group ID, group name, and a list of the requested hotels in the group. It does not list all hotels in the group.

The following example response shows the group affiliation for Hotel 1:

{
  "hotel_groups": [
    {
      "group_id": "12345678911",
      "group_name": "Brand A",
      "hotel_ids": [
         "h101"
       ]
    }
  ],
  "update_version": "42",
  "group_last_update_timestamp_micro": "1234567890"
}

You can use the Groups API to look up the group affiliation of any number of hotels by specifying a comma-delimited list for the hotel_ids query string parameter. The following example looks up hotels with the IDs h101, h102, and h103:

GET https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id/groups/lookup?hotel_ids=h101,h102,h103

This request returns an array of objects in hotel_groups, as the following example shows:

{
  "hotel_groups": [
    {
      "group_id": "12345678911",
      "group_name": "Brand A",
      "hotel_ids": [
         "h101"
       ]
    },
    {
      "group_id": "12345678912",
      "group_name": "Brand B",
      "hotel_ids": [
        "h102",
        "h103"
      ]
    }
  ],
  "update_version": "42",
  "group_last_update_timestamp_micro": "1234567890"
}

Groups API Changes

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

  • All Groups API endpoints now take either a campaign or account ID. Previously, they accepted only account IDs.
  • Each campaign has one ungrouped group that cannot be deleted or renamed. You can access this group by its ID; you cannot access it with the ungrouped path parameter. For accounts and sub accounts, you can use the ungrouped path parameter to access this special group.
  • The ungrouped group show in the group list with an empty name.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
  • Responses now include a group_last_update_timestamp_micro field.

Enviar comentarios sobre…

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