Groups API v2.0

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.

Path

base_path/api_version/account_id/groups[/group_id][/add_hotels][/create][/delete][/remove_hotels][/rename][/lookup]

Where:

Path Parameter Description
base_path https://www.googleapis.com/travelpartner
api_version v2.0
account_id A master or sub account ID. Actions with this API apply to this 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.
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.
lookup Gets the name of the groups for the specified hotel or hotels during a GET action.

Query String Parameters

Parameter Description
min_update_version (Optional, all requests) An incremented value that represents the version of the Hotel Groups in the account. 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.

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).

Supported Methods

HTTP Method Description
GET Lists all Hotel Groups for an account or sub account, or 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 the specified account:

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

Lists all hotels in group 12345678911:

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

Gets a list of all ungrouped hotels for the specified account:

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

Creates a new group named "Brand B":

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

Adds ungrouped hotels to group 12345678911:

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/groups/12345678911/add_hotels

Removes hotels from group 12345678911:

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/groups/12345678911/remove_hotels

Renames group with the ID 12345678912 to "New Name":

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

Deletes group 12345678911:

DELETE https://www.googleapis.com/travelpartner/v2.0/4200042/groups/12345678911/delete

Gets the group affiliation for "Hotel 1" in the specified account:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/groups/lookup/Hotel%201

Gets the group affiliations for Hotel 1, Hotel 2, and Hotel 3 in the specified account:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/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 or sub account.

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

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

The following example gets a list of all Hotel Groups in the 4200042 account:

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

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

GET https://www.googleapis.com/travelpartner/v2.0/4200042/groups?min_update_version=42

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_id": "12345678912",
      "group_name": "Brand B"
    },
    {
      "group_id": "12345678913",
      "group_name": "Brand C"
    }
  ],
  "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.

Listing hotels in a Hotel Group

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

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

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

The following example lists all hotels in the "12345678911" Hotel Group for account 4200042:

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

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

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

Note that if your Hotel Group's name contains a space or other special character, you must URL encode it.

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"
}

Listing ungrouped hotels

To list all ungrouped hotels in an 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.0/account_id/groups/ungrouped

The following example lists all ungrouped hotels in account 4200042:

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

Adding hotels to a Hotel Group

You can use the Groups API to add one or more ungrouped hotels to the specified Hotel 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.0/account_id/groups/group_id/add_hotels

The following example adds ungrouped hotels to the group "12345678911" in account 4200042:

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/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"
  }
}

You can explicitly add a hotel to the special "ungrouped" Hotel Group, which is the same as removing a hotel from a Hotel Group and not adding it to another group.

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.

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

PUT https://www.googleapis.com/travelpartner/v2.0/account_id/groups/group_id/remove_hotels

The following example removes the specified hotels from the "12345678911" group in the 4200042 account:

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/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 adds hotels with the IDs h1066 and h1977:

{
  "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. 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.0/account_id/groups/create/group_name

The following example adds ungrouped hotels to the group "Brand B" in account 4200042:

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

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

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

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"
}

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.)

Renaming a Hotel Group

You can use the Groups API to change the name of a Hotel Group.

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

PUT https://www.googleapis.com/travelpartner/v2.0/account_id/groups/group_id/rename/new_group_name

The following example renames group 12345678912 to "New Name":

PUT https://www.googleapis.com/travelpartner/v2.0/4200042/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.0/4200042/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.

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

DELETE https://www.googleapis.com/travelpartner/v2.0/account_id/groups/group_id/delete

The following example deletes the Hotel Group with the ID "12345678914:

DELETE https://www.googleapis.com/travelpartner/v2.0/4200042/groups/12345678914/delete

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

DELETE https://www.googleapis.com/travelpartner/v2.0/4200042/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 "ungrouped" group.

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 it's ID, as well as a list of 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.0/account_id/groups/lookup/hotel_id

The following example looks up the group for a hotel with the ID h101:

GET https://www.googleapis.com/travelpartner/v2.0/account_id/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"
}

You can use the Groups API to look up any number of hotels by using 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.0/account_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"
}

Groups API Changes

The Groups API is new for version 2.0.