NAV
http

Revision

Older versions here

Changelog

June 23rd, 2016

May 4th, 2016

February 7th, 2016

January 21st, 2016

January 20th, 2016

(Breaking API change) December 9th, 2015

(Breaking API change) November 18th, 2015

Introduction

ZUMATA is a new approach in B2B travel API’s. In a few simple steps, you can be getting real-time travel pricing, availability and booking worldwide via simple API calls.

The purpose of this site is to provide documentation and technical guidance to users of ZUMATA’s API products. From this site you can request a developer key, and get access to documentation for the API calls available, as well as contact us in the event you have questions.

Usage of the ZUMATA API requires consent to be bound by the terms of the ZUMATA API Agreement.

Authentication

GET /search?destination_id=RsBU&check_in_date=2015-12-20&check_out_date=2004-12-31&room_count=2&adult_count=2&currency=USD HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

In order to access the API, you will need an API key.

You can request an API Key by emailing apikeyrequest@zumata.com. Please state your name, company name, use case and contact information and we will get back to you.

The API key should be included in the X-Api-Key header of each request. Note that the API key is case sensitive.

Environments and HTTP(S)

We offer both test and production environments via different host endpoints.

Environment Host
Production api-v3.zumata.com (HTTPS)
Test test-api-v3.zumata.com (HTTPS)

Workflow

The general workflow for the API v3.0:

API v3.0 workflow

Search is architected as a polling endpoint; that means that you can continue to call the endpoint, and at any point in time the results from it are viable for display and booking. And, over time, polls should contain more data than previous ones. This allows you to poll from your front end browser application through to your server and from there on to the endpoint, with each call returning progressively more data. This will allow users to see hotel packages as soon as they are available rather than waiting for an arbitrary cut-off time or full search completion.

It is also possible to use the alternative method of simply waiting until either a) an arbitrary time has passed (max_time) or b) search is complete. In your code, you start the search with an initial call at the 0-seconds elapsed mark, then call once every 2-3 seconds until your max_time has been exceeded or we have returned a search completed response. Once this has happened you could return the results to your webpage or application.

There are two primary types of searches, hotel id list-based and destination based.

Hotel List Search:

Destination Search:

Why would you use one over the other?

The main distinction between these two searches is that one search requests specific hotel id’s and the other, a destination. Theoretically, these should ultimately return the same coverage of hotels, but there are two reasons why this generally doesn’t happen 1) the list of destinations is imprecise or incomplete and 2) there is matching discrepancy to the underlying supplier’s own list of locations. If you send us a request for a hotel id, we can pass that on directly to the supplier and we will definitely get the hotel, if you send us a destination, every supplier has their own list of hotel destinations which may be more or less specific than the one we have, and if the mapping between the two is not entirely correct (say, Singapore -> Central Singapore, or Hong Kong -> Hong Kong Island, or Sentosa -> no matching supplier location) you will miss out on a large number of hotels.

To fix this we have offered the hotel list search so that if you choose, you can download our full hotel list and group hotels against whatever existing location list you wish based on geolocation and city/country of the hotel.

Alternatively, and highly recommended, we suggest using the following 3 calls in conjunction:

Autosuggest (with city_en_US option) - Uses an enhanced destination list for better coverage, returns a region_id.

Region to Hotel ID Endpoint - Can convert the region_id from the autosuggest directly into a list of hotel_ids

hotel_list Search - Use the hotel_list search endpoint with the retrieved list of hotels

We have verified the coverage of the region system at 97% of our full hotel list, and certainly the list has more locations than our older destination list.

The Search Response

When performing a search, the response status can have different values.

complete: The search is completed. The search result is included in the response results body. in-progress: The search is being performed. You can poll the same search at any interval until the status is complete. Certain fields should always be expected from the search/[HOTEL_ID] result: booking_key, hotel_id, room_details/description, room_details/food, room_details/type, room_rate, room_rate_currency, chargeable_rate, chargeable_rate_currency.

IMPORTANT NOTE ON SEARCH USAGE: Our supplier agreements do not permit non-user-generated searches, this means pre-caching or warming up your cache in advance of searches or anticipation of a user search is prohibited. The primary reason for this is that there are certain ratios of searches to bookings that need to be maintained between your usage of ZUMATA API and also our own usage of supplier feeds. Non user-generated searches (scripts,cron jobs, etc.) quickly drive the “search” side of the ratio up to unacceptable levels and may result in your access being throttled or even blocked in extreme cases.

When performing a search, the response status can have different values.

Certain fields should always be expected from the search/[HOTEL_ID] result: booking_key, hotel_id, room_details/description, room_details/food, room_details/type, room_rate, room_rate_currency, chargeable_rate, chargeable_rate_currency.

IMPORTANT NOTE ON SEARCH USAGE: Our supplier agreements do not permit non-user-generated searches, this means pre-caching or warming up your cache in advance of searches or anticipation of a user search is prohibited. The primary reason for this is that there are certain ratios of searches to bookings that need to be maintained between your usage of ZUMATA API and also our own usage of supplier feeds. Non user-generated searches (scripts,cron jobs, etc.) quickly drive the “search” side of the ratio up to unacceptable levels and may result in your access being throttled or even blocked in extreme cases.

2. Booking Policy

Before a booking call is made against a package (returned via search), a booking policy call must be made.

Retrieving a booking policy returns additional information regarding the booking to be made and includes details like cancellation policy and hotel policies. In the case of some suppliers this call is equivalent to an availability check, because of this it is important not to let long periods (>20 minutes) lapse between retrieval of this policy and the booking itself as this will often reduce the likelihood of a package being successfully booked.

When making the pre-book request several packages from various suppliers may be able to fulfill this request. Accordingly, in the event of booking failure seen in our internal system, we will proceed to book from the next supplier available, until the booking request is fulfilled or no further options are available.

Tolerance parameters are provided while submitting a booking policy, affecting which packages are considered acceptable matches.

After submitting the booking policy, the details can be retrieved or can be used to carry out a pre-booking.

See here for more information.

3. Book

Books a package after a booking policy request has been made. This is where the guest information is passed and payment is performed. The booking is done in 3 calls.

Booking needs some time to process. The status of the booking can be retrieved in 2 ways (or a combination of both).

See here for more information.

4. Cancel

Cancels a booking.

See here for more information.

Webhooks

Sample request body

{
  "type": "confirmed",
  "booking": {
    "booking_id": "7c738d11-fbf5-44fc-74ee-0ffc5aaa8984",
    "client_reference": "7682197",
    "status": "bkg-cf",
    "status_payment": "acc-cp",
    "destination_id": "RsBU",
    "requested_at": "2015-07-15T12:34:03.872408+08:00",
    "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
    "package": {
      "hotel_id": "NBUd",
      "room_details": {
        "description": "Presidential Suite",
        "food": 2,
        "room_type": "Presidential",
        "room_view": "City",
        "beds": {
          "single": 1
        }
      },
      "check_in_date": "2015-08-04",
      "check_out_date": "2015-08-05",
      "adult_count": 2,
      "room_count": 1
    },
    "guest": {
      "salutation": "Mr.",
      "first_name": "Charlie",
      "last_name": "Smith",
      "email": "charlie.smith@zumata.com",
      "city": "Montreal",
      "state": "QC",
      "street": "123 Outtamy way",
      "postal_code": "H3H0H0",
      "country": "CA",
      "nationality": "CA",
      "contact_no": "+1 514 676-9827",
      "remarks": ""
    },
    "pricing": {
      "zumata": {
        "currency": "USD",
        "value": 21
      },
      "client": {
        "currency": "USD",
        "value": 100
      }
    },
    "cancellation_policy": {
      "remarks": "",
      "cancellation_policies": [      
        {
          "penalty_percentage": 100,
          "date_from": "2015-08-01T00:00:00Z",
          "date_to": "2015-08-04T00:00:00Z"
        }
      ]
    },
    "booking_details": {
      "customer_reference": "zbr-1234",
      "customer_booking_id": ""
    }
  }
}

A webhook endpoint can be configured for your account (contact us to setup your webhook). Your webhook endpoint will be called for different events.

Request

The request to your webhook endpoint will be a POST request with a JSON body.

Parameter Value Description
type Type: String The type of events. See here for the list of types.
booking Type: JSON The full status of the booking, which comprises of the fields retrieved in book status.

Events

Type Description
confirmed The booking has been successfully confirmed.
failed The booking has failed.
pending The booking has transitioned to a pending state and will be updated soon, typically within a few minutes to an hour.
pending_confirmed The pending booking has been successfully confirmed.
pending_failed The pending booking has failed.
cancelled The confirmed booking has been successfully cancelled.

Endpoints

Core Availability & Booking Endpoints

Status/Reporting Endpoints

GET /search

Searches available hotels (and picked price) for specified parameters.

Request URL

GET https://api-v3.zumata.com/search?[PARAMETERS]

Request Parameters

GET /search?destination_id=RsBU&check_in_date=2015-12-20&check_out_date=2004-12-31&room_count=2&adult_count=2&currency=USD HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>
Parameter Required Value Description
destination_id Yes Type: String Destination code from the list of destinations. The full list is available here.
Example destination ID.
SingaporeRsBU
check_in_date Yes Type: Date
Format: YYYY-MM-DD
The check-in date for the property stay. The value of this can range from today’s date to 1 year in the future. The check-in-date is considered to be as at the destination.
check_out_date Yes Type: Date
Format: YYYY-MM-DD
The check-out date for the property stay. The value of this can range from tomorrow’s date to about 1 year in the future. The check-in-date is considered to be as at the destination. It is expected that this date occurs after the check-in date.
room_count Yes Type: Integer The total number of rooms required for the stay.
adult_count Yes Type: Integer The total number of adult guests who will be staying in the property.
child_count No Type: Integer The total number of children guests who will be staying in the property. The age of all children used for searching and booking the property is 11 years.
currency Yes Type: String Result prices will be returned in this currency. A list of supported currencies must be specified when requesting for an API key. Please contact us if you wish to make changes to your currency list.
source_market No Type: JSON For sourcing availability within certain markets, a source market option may be usable for more accurate pricing and reduction in booking errors. Supported source markets: AE, TH

Response Fields

Response body

{
  "status": "complete",
  "search": {
    "destination_id": "RsBU",
    "check_in_date": "2015-11-04",
    "check_out_date": "2015-11-06",
    "room_count": 1,
    "adult_count": 2,
    "currency": "USD"
  },
  "hotels": [
    {
      "id": "0Tki",
      "rates": {
        "packages": [
          {
            "chargeable_rate": 9.45,
            "chargeable_rate_currency": "USD",
            "hotel_id": "0Tki",
            "room_rate_currency": "USD",
            "room_rate": 9.23,
            "indicative_market_rates": [
              {
                "market_rate": 10.09,
                "market_rate_currency": "USD",
                "market_rate_supplier": "exp"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "eqUd",
      "rates": {
        "packages": [
          {
            "chargeable_rate": 32.55,
            "chargeable_rate_currency": "USD",
            "hotel_id": "eqUd",
            "room_rate_currency": "USD",
            "room_rate": 31.79,
            "indicative_market_rates": [
              {
                "market_rate": 40.09,
                "market_rate_currency": "USD",
                "market_rate_supplier": "exp"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "i4Ud",
      "rates": {
        "packages": [
          {
            "chargeable_rate": 34.66,
            "chargeable_rate_currency": "USD",
            "hotel_id": "i4Ud",
            "room_rate_currency": "USD",
            "room_rate": 33.84,
            "indicative_market_rates": [
              {
                "market_rate": 36.77,
                "market_rate_currency": "USD",
                "market_rate_supplier": "exp"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "dnhy",
      "rates": {
        "packages": [
          {
            "chargeable_rate": 5.25,
            "chargeable_rate_currency": "USD",
            "hotel_id": "dnhy",
            "room_rate_currency": "USD",
            "room_rate": 5.14,
            "indicative_market_rates": [
              {
                "market_rate": 8.86,
                "market_rate_currency": "USD",
                "market_rate_supplier": "exp"
              }
            ]
          }
        ]
      }
    }
  ]
}

The result body contains the search request and list of hotels available with the pricing of a selected package (lowest price).

Fields Value Description
search Type: JSON Search parameter passed to the request.
hotels Type: JSON Array List of hotels available for the search request.
status Type: String Search result status. If the status is in-progress poll the search until complete is returned.

Use the search fields for the search/detail request.

Response Fields: hotels

The hotels section is a list of available hotels. It also includes the price of a selected packages (lowest price).

Fields Value Description
id Type: String Unique ID of the property returned. Every property has a unique ID.
rates/packages Type: JSON Array The rates of a selected package (lowest price).

Response Fields: packages

The packages section contains 1 element with the rate of a selected package (lowest price).

Fields Always present Value Description
hotel_id Yes Type: String Unique ID of the property returned. Every property has a unique ID.
room_rate Yes Type: Float The rate of a selected room package.
room_rate_currency Yes Type: String The currency of the room_rate. See the list of currencies here.
chargeable_rate Yes Type: Float The chargeable rate of a selected room package.
chargeable_rate_currency Yes Type: String The currency of the chargeable_rate. See the list of currencies here.
indicative_market_rates No Type: JSON Array The indicative market rates of a selected package.

Response Fields: indicative_market_rates

The indicative_market_rates section contains multiple elements with the indicative market rate of a selected package.

Fields Value Description
market_rate Type: Float The market rate of a selected room package.
market_rate_currency Type: String The currency of the market_rate. See the list of currencies here.
market_rate_supplier Type: String The source of the indicative market rate of a selected room package.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

GET /search/[HOTEL_ID]

Searches available packages for a specific hotel.

Request URL

GET https://api-v3.zumata.com/search/[HOTEL_ID]?[PARAMETERS]

Request Parameters

GET /search/NBUd?destination_id=RsBU&check_in_date=2015-12-20&check_out_date=2004-12-31&room_count=2&adult_count=2 HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

The same parameters as for the search request.

Response Fields

Response body

{
  "status": "complete",
  "search": {
    "destination_id": "RsBU",
    "check_in_date": "2015-08-04",
    "check_out_date": "2015-08-05",
    "room_count": 1,
    "adult_count": 2,
    "currency": "USD"    
  },
  "hotels": [
    {
      "id": "NBUd",
      "rates": {
        "packages": [
          {
            "hotel_id": "NBUd",
            "room_details": {
              "description": "Double Standard",
              "food": 2,
              "room_type": "Double",
              "room_view": "Beach view",
              "beds": {
                "double": 1
              }
            },
            "booking_key": "9e8d73ce",
            "room_rate": 21,
            "room_rate_currency": "USD",
            "chargeable_rate": 36,
            "chargeable_rate_currency": "USD",
            "indicative_market_rates": [
              {
                "market_rate": 38.55,
                "market_rate_currency": "USD",
                "market_rate_supplier": "exp"
              }
            ],
            "taxes_and_fees": {
              "total": {
                "currency": "USD",
                "value": 3.02
              }
            }

          },
          {
            "hotel_id": "NBUd",
            "room_details": {
              "description": "Single Standard",
              "food": 2,
              "room_type": "Single",
              "room_view": "Beach view",
              "beds":{
                "single": 1
              }
            },
            "booking_key": "7b0f97cy",
            "room_rate": 23,
            "room_rate_currency": "USD",
            "chargeable_rate": 33,
            "chargeable_rate_currency": "USD",
            "indicative_market_rates": [
              {
                "market_rate": 33.12,
                "market_rate_currency": "USD",
                "market_rate_supplier": "exp"
              }
            ],
            "taxes_and_fees": {
              "total": {
                "currency": "USD",
                 "value": 2.01
              }
            }
          }
        ]
      }
    }
  ]
}

The result body contains the search request and list of packages for the requested hotel.

Fields Value Description
search Type: JSON Search parameter passed to the request.
hotels Type: JSON Array The list should only contain one item (the selected hotel) with all the packages available for that hotel.
status Type: String Search result status. If the status is in-progress poll the search until complete is returned.

Use the search and package fields for the booking-policy request.

Response Fields: hotels

The hotels section is a list containing one item (the selected hotel) with all the packages for that hotel.

Fields Value Description
id Type: String Unique ID of the property returned. Every property has a unique ID.
rates/packages Type: JSON Array List of available packages.

Response Fields: packages

The hotels section is a list of packages available for the hotels.

Fields Always present Value Description
booking_key Yes Type: String The key to use when submitting the booking policy for this package. NOTE: This key is only used to verify contents of the package and is NOT unique in any scope, do not attempt to use this as a unique ID as there is a high chance of collision.
hotel_id Yes Type: String Unique ID of the property returned. Every property has a unique ID.
room_details Yes Type: JSON The details of the room.
room_rate Yes Type: Float This is the total price API consumer will be charged for the room(s), you should plan to mark this up yourself, or use the ‘chargeable_rate’ field below. In short, this is the price ZUMATA charges you for the room(s).
room_rate_currency Yes Type: String The currency of the room_rate. See the list of currencies here.
chargeable_rate Yes Type: Float This field will be populated by our system’s business logic (if you are using our assistance with calculating a final price to consumers). Most often it is at or near the market_rate, which means you would charge your users this amount and the difference between room_rate and chargeable_rate would be your gross margin. By default, we typically send the marketRate in this field unless some other logic has been chosen to override it. So ordinarily, this would be the price you display to users.
chargeable_rate_currency Yes Type: String The currency of the chargeable_rate. See the list of currencies here.
indicative_market_rates No Type: JSON Array The indicative market rates of a selected package.
taxes_and_fees Yes Type: JSON Taxes and fees break down. These amounts are included in the prices returned by the API.

Response Fields: room_details

Fields Always present Value Description
description Yes Type: String Short text summary of the room (e.g. queen size bed - no breakfast).
food Yes Type: Integer The code describing the food. The full list can be found here.
room_type Yes Type: String Short description about the room type.
room_view No Type: String Short description about the room view.
beds No Type: Lists the number of beds (per bed type) in the room. e.g. "beds":{ "single":2 }

Response Fields: Room code

Code Description
1 Room only
2 Breakfast
3 Lunch
4 Dinner
5 Half board: Breakfast and dinner*
6 Full board: Breakfast, lunch and dinner
7 All inclusive:

* In some cases half board could be any 2 meals (e.g. breakfast and lunch, lunch and dinner).

Please note that the exact definition of the room code depends on the accommodation.

Response Fields: indicative_market_rates

The indicative_market_rates section contains multiple elements with the indicative market rate of a selected package.

Fields Value Description
market_rate Type: Float The market rate of a selected room package.
market_rate_currency Type: String The currency of the market_rate. See the list of currencies here.
market_rate_supplier Type: String The source of the indicative market rate of a selected room package.

Response Fields: taxes_and_fees

The taxes_and_fees section contains multiple elements with taxes and fees breakdown.

Fields Value Description
total Type: JSON Total amount of taxes and fees. The sum of tax_and_service_fee and extra_person_fee.
estimated_total Type: JSON Total estimated amount of taxes and fees. This is the estimated amount and may differ from the actual.
extra_person_fee Type: JSON The amount of fee that will be incurred for extra guests.
hotel_occupancy_tax Type: JSON The amount of hotel occupancy tax.
sales_tax Type: JSON The amount of sales tax.
tax_and_service_fee Type: JSON Total amount of taxes and fees excluding extra person fee. Includes sales_tax, hotel_occupancy_tax and other taxes. A breakdown for other taxes will not be provided.

Response Fields: Amount

Fields Value Description
currency Type: String The currency of the value. e.g. USD.
value Type: Float The pricing value (in the currency specified).

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

GET /hotel_list

Searches a list of given hotels for specified parameters.

Request URL

GET https://api-v3.zumata.com/hotel_list?[PARAMETERS]

Request Parameters

GET /hotel_list?hotel_id_list=UjoO,bZtr&check_in_date=2016-05-07&check_out_date=2016-05-08&room_count=1&adult_count=2&currency=USD HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>
Parameter Required Value Description
hotel_id_list Yes Type: String Hotel ids to be searched for with the other given parameters. Only 200 hotel ids may be sent in a given request. The full list is available here.
Example hotel ID.
LeBlanc SaigonbZtr
check_in_date Yes Type: Date
Format: YYYY-MM-DD
The check-in date for the property stay. The value of this can range from today’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels.
check_out_date Yes Type: Date
Format: YYYY-MM-DD
The check-out date for the property stay. The value of this can range from tomorrow’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels. It is expected that this date occurs after the check-in date.
room_count Yes Type: Integer The total number of rooms required for the stay.
adult_count Yes Type: Integer The total number of adult guests who will be staying in the property.
child_count No Type: Integer The total number of children guests who will be staying in the property. The age of all children used for searching and booking the property is 11 years.
currency Yes Type: String Result prices will be returned in this currency. A list of supported currencies must be specified when requesting for an API key. Please contact us if you wish to make changes to your currency list.
source_market No Type: JSON For sourcing availability within certain markets, a source market option may be usable for more accurate pricing and reduction in booking errors. Supported source markets: AE, TH

Response Fields

Response body

{
  "status": "complete",
  "search": {
    "check_in_date": "2016-05-07",
    "check_out_date": "2016-05-08",
    "room_count": 1,
    "adult_count": 2,
    "currency": "USD"
  },
  "hotels": [
    {
      "id": "bZtr",
      "rates": {
        "packages": [
          {
            "hotel_id": "bZtr",
            "room_details": {
              "description": "Superior Executive Room Queen Bed",
              "food": 6,
              "room_type": "Superior Executive",
              "room_view": "",
              "beds": {
                "queen": 1
              }
            },
            "booking_key": "7a9ab8ad",
            "room_rate": 25.92,
            "room_rate_currency": "USD",
            "chargeable_rate": 26.58,
            "chargeable_rate_currency": "USD",
            "taxes_and_fees": {
              "estimated_total": {
                "currency": "USD",
                "value": 3.44
              }
            },
            "bundled_rate": false
          }
        ]
      }
    },
    {
      "id": "UjoO",
      "rates": {
        "packages": [
          {
            "hotel_id": "UjoO",
            "room_details": {
              "description": "Designer Room King Bed With Fjord View",
              "food": 5,
              "room_type": "Designer",
              "room_view": "Fjord",
              "beds": {
                "king": 1
              }
            },
            "booking_key": "7786b1d4",
            "room_rate": 71.53,
            "room_rate_currency": "USD",
            "chargeable_rate": 73.36,
            "chargeable_rate_currency": "USD",
            "taxes_and_fees": {
              "estimated_total": {
                "currency": "USD",
                "value": 9.83
              }
            },
            "bundled_rate": false
          }
        ]
      }
    }
  ]
}

The result body contains the search request and list of hotels available with the pricing of a selected package (lowest price).

Fields Value Description
search Type: JSON Search parameter passed to the request.
hotels Type: JSON Array List of hotels available for the search request.
status Type: String Search result status. If the status is in-progress poll the search until complete is returned.

Use the search fields for the search/detail request.

Response Fields: hotels

The hotels section is a list of the requested hotels. It also includes the price of a selected packages (lowest price).

Fields Value Description
id Type: String Unique ID of the property returned. Every property has a unique ID.
rates/packages Type: JSON Array The rates of a selected package (lowest price).

A response may contain X-Invalid-Hotel-ID-List. This header will appear if invalid hotel IDs were passed in a request.

Example:

X-Invalid-Hotel-ID-List: 12345,54321

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

GET /hotel_rooms

Searches a list of available packages for a given hotel ID and specified parameters.

Request URL

GET https://api-v3.zumata.com/hotel_rooms?[PARAMETERS]

Request Parameters

GET /hotel_rooms?hotel_id=UjoO&check_in_date=2016-05-07&check_out_date=2016-05-08&room_count=1&adult_count=2&currency=USD HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>
Parameter Required Value Description
hotel_id Yes Type: String Hotel id to be searched for with the other given parameters. The full list is available here.
Example hotel ID.
LeBlanc SaigonbZtr
check_in_date Yes Type: Date
Format: YYYY-MM-DD
The check-in date for the property stay. The value of this can range from today’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels.
check_out_date Yes Type: Date
Format: YYYY-MM-DD
The check-out date for the property stay. The value of this can range from tomorrow’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels. It is expected that this date occurs after the check-in date.
room_count Yes Type: Integer The total number of rooms required for the stay.
adult_count Yes Type: Integer The total number of adult guests who will be staying in the property.
child_count No Type: Integer The total number of children guests who will be staying in the property. The age of all children used for searching and booking the property is 11 years.
currency Yes Type: String Result prices will be returned in this currency. A list of supported currencies must be specified when requesting for an API key. Please contact us if you wish to make changes to your currency list.
source_market No Type: JSON For sourcing availability within certain markets, a source market option may be usable for more accurate pricing and reduction in booking errors. Supported source markets: AE, TH

Response Fields

Response body

{
  "status": "complete",
  "search": {
    "check_in_date": "2016-05-31",
    "check_out_date": "2016-10-05",
    "room_count": 1,
    "adult_count": 2,
    "currency": "USD"
  },
  "hotels": [
    {
      "id": "BtGa",
      "rates": {
        "packages": [
          {
            "hotel_id": "BtGa",
            "room_details": {
              "description": "Cottage Single Beds With Gulf View",
              "food": 1,
              "room_type": "Cottage",
              "room_view": "Gulf",
              "beds": {
                "single": 2
              }
            },
            "booking_key": "08c130d7",
            "room_rate": 18.18,
            "room_rate_currency": "USD",
            "chargeable_rate": 18.18,
            "chargeable_rate_currency": "USD",
            "taxes_and_fees": {
              "estimated_total": {
                "currency": "USD",
                "value": 2.71
              }
            },
            "bundled_rate": false
          },
          {
            "hotel_id": "BtGa",
            "room_details": {
              "description": "Courtyard Room Double Bed",
              "food": 6,
              "room_type": "Courtyard",
              "room_view": "",
              "beds": {
                "double": 1
              }
            },
            "booking_key": "c8e4adf7",
            "room_rate": 43.43,
            "room_rate_currency": "USD",
            "chargeable_rate": 43.43,
            "chargeable_rate_currency": "USD",
            "taxes_and_fees": {
              "estimated_total": {
                "currency": "USD",
                "value": 6.47
              }
            },
            "bundled_rate": false
          }
        ]
      }
    }
  ]
}

The result body contains the search request and the list of available packages for the given hotel ID.

Fields Value Description
search Type: JSON Search parameter passed to the request.
hotels Type: JSON Array List of hotels available for the search request. Will contain only one hotel
status Type: String Search result status. If the status is in-progress poll the search until complete is returned.

Use the search fields for the search/detail request.

Response Fields: hotels

The hotels section contains requested hotels. It also includes the list of available packages and prices.

Fields Value Description
id Type: String Unique ID of the property returned. Every property has a unique ID.
rates/packages Type: JSON Array The rates of packages for a selected hotel.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

POST /booking_policy

Submits a booking policy using a package returned from the search request.

This endpoint can be both blocking and non-blocking depending on the non_blocking flag in the config section. Set it to true to trigger the non-blocking behavior.

In blocking behavior, the endpoint will only return when search is completed. Search is considered completed only when all suppliers return with their results. At this point, we would have all the possible identical packages from all suppliers.

In non-blocking behavior, the endpoint returns even while search is still in progress. Only packages that are available at that time of request will be included. Packages that come back after this request will not be considered during booking time. Normal usage of endpoint in this mode is to call once every second or so until a package(s) is available and then stop, however if you wish you can continue until the search progress is complete - this may be several seconds so it depends on your application whether waiting the additional time is worthwhile. Waiting would allow us to assemble additional fall-back bookings within your tolerance, should the initial booking attempt fail.

It is strongly recommended you use the non-blocking behaviour as the blocking behaviour is likely to be deprecated.

Request URL

POST /booking_policy HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

POST https://api-v3.zumata.com/booking_policy

Request Parameters

Request body

{
  "search": {
    "destination_id": "RsBU",
    "check_in_date": "2015-08-04",
    "check_out_date": "2015-08-05",
    "room_count": 1,
    "adult_count": 2,
    "currency": "USD"    
  },
  "package": {
    "hotel_id":"NBUd",
    "room_details": {
      "description": "Double Standard",
      "food": 2,
      "room_type": "Double",
      "room_view": "Beach view",
      "beds": {
        "single": 1
      }
    },
    "booking_key": "9e8d73ce",
    "room_rate": 21,
    "room_rate_currency": "USD",
    "chargeable_rate": 36,
    "chargeable_rate_currency": "USD",
    "indicative_market_rates": [
      {
        "market_rate": 38.55,
        "market_rate_currency": "USD",
        "market_rate_supplier": "exp"
      }
    ]
  },
  "config": {
    "pricing": {
      "fixed_tolerance": 1
    },
    "matching": {
      "flexible_room_view": true,
      "flexible_beds": true
    },
    "non_blocking": false
  }
}
Parameter Required Value Description
search Yes Type: JSON The same parameters as for the search request.
package Yes Type: JSON A package returned by the search request.
config Yes Type: JSON Extra configuration for booking.

Config Parameters

When making a booking - several packages from various suppliers may be able to fulfill this request. Accordingly, in the event of booking failure seen in our internal system, we will proceed to book from the next supplier available, until the booking request is fulfilled or no further options are available. By providing the following tolerance parameters, more or less options will be considered in the booking process.

Parameter Required Value Description
pricing/fixed_tolerance No Type: Float The price tolerance for a package. This field is deprecated. Tolerance must be used instead.
pricing/tolerance No Type: JSON The tolerance for a package.
matching/flexible_room_view No Type: Boolean The tolerance for room view.
matching/flexible_beds No Type: Boolean The tolerance for beds.
non_blocking No Type: Boolean It will be false when not provided. Please set it to true if you wish to make a non-blocking booking policy call.
Non-blocking booking policy call has a different response format, please check here for information. Note that the false setting will likely be deprecated in future.

Tolerance

Parameter Required Value Description
amount No Type Float The price tolerance for a package.
percentage No Type Float The percentage tolerance for a package.

Either amount or percentage is allowed to be set, but not both at the same time.

Response Fields

Response body

{
  "booking_policy_id": "67639378-a64e-4e08-619f-fe8b2bd9843f",
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [{      
      "penalty_percentage": 50,
      "date_from": "2015-08-03T00:00:00Z",
      "date_to": "2015-08-04T00:00:00Z"
    }]
  }
}

The booking policy response contains information useful for booking and the cancellation policy.

Fields Value Description
booking_policy_id Type: GUID The unique booking policy ID. This ID is needed for the booking request.
cancellation_policy/remarks Type: String Remarks about the cancellation.
cancellation_policy/cancellation_policies Type: JSON Array The list of cancellation policies.

Response Fields: cancellation_policies

The 'cancellation_policies’ contains a list of policies rule.

Fields Value Description
cancellation_policies/penalty_percentage Type: Number The penalty percentage to pay when cancelling.
cancellation_policies/date_from Type: String The start date of the cancellation policy.
cancellation_policies/date_to Type: String The end date of the cancellation policy.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

HTTP Status Code ID Description
404 not_found This can occur if no bookable package was found.

It is possible that a package is not available when requesting for the booking policy. A common scenario is that the package was booked by someone else between the search and the booking policy request. This means the package is sold out.

Response Fields

Response body

{
  "search_status": "complete",
  "booking_policy": {  
    "booking_policy_id": "67639378-a64e-4e08-619f-fe8b2bd9843f",
    "cancellation_policy": {
      "remarks": "",
      "cancellation_policies": [{      
        "penalty_percentage": 50,
        "date_from": "2015-08-03T00:00:00Z",
        "date_to": "2015-08-04T00:00:00Z"
      }]
    }
  }
}

You may proceed to use the returned booking policy even though the search_status is still in-progress. If you continue to call every few seconds, waiting until the search is complete allows for slower partners to return which could improve the booking success rate.

Fields Value Description
search_status Type: String The search status for the requested package.
booking_policy Type: JSON The booking policy response.

GET /booking_policy/[BOOKING_POLICY_ID]

Retrieves the information from a booking-policy request.

Request URL

GET /booking_policy/67639378-a64e-4e08-619f-fe8b2bd9843f HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

GET https://api-v3.zumata.com/booking_policy/[BOOKING_POLICY_ID]

Request Parameters

Parameter Required Value Description
[BOOKING_POLICY_ID] Yes Type: GUID The booking_policy_id returned from booking-policy response result.

Response Fields

Response body

{
  "booking_policy_id": "67639378-a64e-4e08-619f-fe8b2bd9843f",
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [{      
      "penalty_percentage": 50,
      "date_from": "2015-08-03T00:00:00Z",
      "date_to": "2015-08-04T00:00:00Z"
    }]
  },
  "request": {
    "search": {
      "destination_id": "RsBU",
      "check_in_date": "2015-08-04",
      "check_out_date": "2015-08-05",
      "room_count": 1,
      "adult_count": 2,
      "currency": "USD"      
    },
    "package": {
      "hotel_id": "NBUd",
      "room_details": {
        "description": "Presidential Suite",
        "food": 2,
        "room_type": "Presidential",
        "room_view": "City",
        "beds": {
          "single": 1
        }
      },
      "booking_key": "9e8d73ce",
      "room_rate": 21,
      "room_rate_currency": "USD",
      "chargeable_rate": 36,
      "chargeable_rate_currency": "USD",
      "indicative_market_rates": [
        {
          "market_rate": 38.55,
          "market_rate_currency": "USD",
          "market_rate_supplier": "exp"
        }
      ]
    },
    "config": {
      "pricing": {
        "fixed_tolerance": 1,
        "tolerance" : {
          "amount" : 1
        }
      },
      "matching": {
        "flexible_room_view": true,
        "flexible_beds": true
      }
    }
  }
}

The response contains the information from the booking-policy request.

Fields Value Description
booking_policy_id Type: GUID The booking_policy_id requested.
cancellation_policy Type: JSON The cancellation policy of the booking.
request Type: JSON The request information of the booking policy.

Response Fields: request

Fields Value Description
search Type: JSON The search for the booking policy.
package Type: JSON The package for the booking policy.
config Type: JSON The config passed during the booking-policy.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

POST /pre_book

Pre-books a package after a booking-policy request has been made.

Request URL

POST /pre_book HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

POST https://api-v3.zumata.com/pre_book

Request Parameters

Request body

{
  "guest": {
    "salutation": "Mr.",
    "first_name": "Charlie",
    "last_name": "Smith",
    "email": "charlie.smith@zumata.com",
    "city": "Montreal",
    "state": "QC",
    "street": "123 Outtamy way",
    "postal_code": "H3H0H0",
    "country": "CA",
    "remarks": "2 extra bottles of water requested",
    "nationality": "CA",
    "contact_no": "+1 514 555-1234"
  },
  "booking_policy_id": "4959393f-1257-442c-51fc-2a3e425e2be5",
  "client_reference": "7682197"
}
Parameter Required Value Description
guest Yes Type: JSON The guest information.
booking_policy_id Yes Type: String The id returned from the booking-policy response.
client_reference No Type: String Custom id set by the client which can be retrieved during regular booking status calls.

Request Parameters: Guest parameters

Parameter Required Value Description
salutation No Type: String Salutation fields. e.g. 'Mr.’, 'Ms.’, or 'Mrs.’.
first_name Yes Type: String The first name of the guest.
last_name Yes Type: String The last name of the guest.
email No Type: String The email of the guest.
city No Type: String The address of the guest (city).
state No Type: 2 char The state code. The full list of states are available here.
street No Type: String The address of the guest (street).
postal_code No Type: String The address of the guest (postal code).
country No Type: 2 char The ISO 3166 country code. The full list of countries are available here.
nationality No Type: 2 char The nationality of the guest. The ISO 3166 alpha 2 country code. The full list of countries are available here.
contact_no Yes Type: String The contact number of the guest.
remarks No Type: String Any remarks the user would like to pass along to the booking provider

Response Fields

Response body

{
  "booking_id": "31403b0f-6e62-49fb-5fe4-db34cfd42feb",
  "client_reference": "7682197",
  "status": "bkg-ns",
  "status_payment": "pay-ns",
  "destination_id": "RsBU",
  "requested_at": "2015-07-15T12:34:03.872408+08:00",
  "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
  "package": {
    "hotel_id": "NBUd",
    "room_details": {
      "description": "Presidential Suite",
      "food": 2,
      "room_type": "Presidential",
      "room_view": "City",
      "beds": {
        "single": 1
      }
    },
    "check_in_date": "2015-08-04",
    "check_out_date": "2015-08-05",
    "adult_count": 2,
    "room_count": 1
  },
  "guest": {
    "salutation": "Mr.",
    "first_name": "Charlie",
    "last_name": "Smith",
    "email": "charlie.smith@zumata.com",
    "city": "Montreal",
    "state": "QC",
    "street": "123 Outtamy way",
    "postal_code": "H3H0H0",
    "country": "CA",
    "nationality": "CA",
    "contact_no": "+1 514 676-9827",
    "remarks": ""
  },
  "pricing": {
    "zumata": {
      "currency": "USD",
      "value": 21
    },
    "client": {
      "currency": "USD",
      "value": 100
    }
  },
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [
      {
        "penalty_percentage": 100,
        "date_from": "2015-08-01T00:00:00Z",
        "date_to": "2015-08-04T00:00:00Z"
      }
    ]
  }
}

When a pre-booking is succesful, a summary of the details so far is returned. The booking_id is used to update the payment, checking its status and cancelling. No actual booking or payment has been processed at this point.

Fields Value Description
booking_id Type: GUID Unique booking ID of the booking. This field is used for cancelling a booking after it has been completed.

A detailed breakdown of the remaining fields can be found in the booking response section.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

POST /book/[BOOKING_ID]

If clients do not handle user payment on their own, use /book/[BOOKING_ID]/pay/[PAYMENT_ID] endpoint instead.

Request URL

POST https://api-v3.zumata.com/book/[BOOKING_ID]

POST /book/31403b0f-6e62-49fb-5fe4-db34cfd42feb HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

Request Parameters

Parameter Required Value Description
[BOOKING_ID] Yes Type: GUID The booking ID returned from the booking response.

Response Fields

Response body

{
  "booking_id": "31403b0f-6e62-49fb-5fe4-db34cfd42feb",
  "client_reference": "7682197",
  "status": "bkg-ip",
  "status_payment": "acc-rs",
  "destination_id": "RsBU",
  "requested_at": "2015-07-15T12:34:03.872408+08:00",
  "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
  "package": {
    "hotel_id": "NBUd",
    "room_details": {
      "description": "Presidential Suite",
      "food": 2,
      "room_type": "Presidential",
      "room_view": "City",
      "beds": {
        "single": 1
      }
    },
    "check_in_date": "2015-08-04",
    "check_out_date": "2015-08-05",
    "adult_count": 2,
    "room_count": 1
  },
  "guest": {
    "salutation": "Mr.",
    "first_name": "Charlie",
    "last_name": "Smith",
    "email": "charlie.smith@zumata.com",
    "city": "Montreal",
    "state": "QC",
    "street": "123 Outtamy way",
    "postal_code": "H3H0H0",
    "country": "CA",
    "nationality": "CA",
    "contact_no": "+1 514 676-9827",
    "remarks": ""
  },
  "pricing": {
    "zumata": {
      "currency": "USD",
      "value": 21
    },
    "client": {
      "currency": "USD",
      "value": 100
    }
  },
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [
      {
        "penalty_percentage": 100,
        "date_from": "2015-08-01T00:00:00Z",
        "date_to": "2015-08-04T00:00:00Z"
      }
    ]
  }
}

The booking is currently in progress. Query the booking status to check if the booking has completed successfully, or register a webhook with us.

Fields Value Description
booking_id Type: UUID The booking_id from the request.

A detailed breakdown of the remaining fields can be found in the booking response section.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

POST /book/[BOOKING_ID]/pay/[PAYMENT_ID]

Updates a booking with payment information. Prior to calling this endpoint, a call to the payment system should be made. See the payment section for more info.

If clients handle user payment on their own, use POST /book/[BOOKING_ID] endpoint instead.

Request URL

POST https://api-v3.zumata.com/book/[BOOKING_ID]/pay/[PAYMENT_ID]

POST /book/31403b0f-6e62-49fb-5fe4-db34cfd42feb/pay/8eaea1a5-fd66-4411-915f-25b1b011a723 HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

Request Parameters

Parameter Required Value Description
[BOOKING_ID] Yes Type: GUID The booking ID returned from the booking response.
[PAYMENT_ID] Yes Type: UUID The payment ID returned from the payment call.

Response Fields

Response body

{
  "booking_id": "31403b0f-6e62-49fb-5fe4-db34cfd42feb"
}
Fields Value Description
booking_id Type: UUID The booking_id from the request.

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

GET /book/[BOOKING_ID]/status

Retrieves the status and information of a booking request.

Request URL

GET https://api-v3.zumata.com/book/[BOOKING_ID]/status

GET /book/31403b0f-6e62-49fb-5fe4-db34cfd42feb/status HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

Request Parameters

Parameter Required Value Description
[BOOKING_ID] Yes Type: GUID The booking ID returned from the booking response.

Response Fields

Response body

{
  "booking_id": "7c738d11-fbf5-44fc-74ee-0ffc5aaa8984",
  "client_reference": "7682197",
  "status": "bkg-cf",
  "status_payment": "acc-cp",
  "destination_id": "RsBU",
  "requested_at": "2015-07-15T12:34:03.872408+08:00",
  "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
  "package": {
    "hotel_id": "NBUd",
    "room_details": {
      "description": "Presidential Suite",
      "food": 2,
      "room_type": "Presidential",
      "room_view": "City",
      "beds": {
        "single": 1
      }
    },
    "check_in_date": "2015-08-04",
    "check_out_date": "2015-08-05",
    "adult_count": 2,
    "room_count": 1
  },
  "guest": {
    "salutation": "Mr.",
    "first_name": "Charlie",
    "last_name": "Smith",
    "email": "charlie.smith@zumata.com",
    "city": "Montreal",
    "state": "QC",
    "street": "123 Outtamy way",
    "postal_code": "H3H0H0",
    "country": "CA",
    "nationality": "CA",
    "contact_no": "+1 514 676-9827",
    "remarks": ""
  },
  "pricing": {
    "zumata": {
      "currency": "USD",
      "value": 21
    },
    "client": {
      "currency": "USD",
      "value": 100
    }
  },
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [      
      {
        "penalty_percentage": 100,
        "date_from": "2015-08-01T00:00:00Z",
        "date_to": "2015-08-04T00:00:00Z"
      }
    ]
  },
  "booking_details": {
    "customer_reference": "zbr-1234",
    "customer_booking_id": ""
  }
}

Response body - cancelled

{
  "booking_id": "3b0a95ef-fa68-4b1a-9306-3fdb5068d845",
  "client_reference": "7682197",
  "status": "bkg-cx",
  "status_payment": "acc-cx",
  "supplier_name": "Hotelbeds",
  "destination_id": "RsBU",
  "requested_at": "2015-07-15T12:34:03.872408+08:00",
  "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
  "package": {
    "hotel_id": "NBUd",
    "room_details": {
      "description": "Presidential Suite",
      "food": 2,
      "room_type": "Presidential",
      "room_view": "City",
      "beds": {
        "single": 1
      }
    },
    "check_in_date": "2015-08-04",
    "check_out_date": "2015-08-05",
    "adult_count": 2,
    "room_count": 1
  },
  "guest": {
    "salutation": "Mr.",
    "first_name": "Charlie",
    "last_name": "Smith",
    "email": "charlie.smith@zumata.com",
    "city": "Montreal",
    "state": "QC",
    "street": "123 Outtamy way",
    "postal_code": "H3H0H0",
    "country": "CA",
    "nationality": "CA",
    "contact_no": "+1 514 676-9827",
    "remarks": ""
  },
  "pricing": {
    "zumata": {
      "currency": "USD",
      "value": 21
    },
    "client": {
      "currency": "USD",
      "value": 100
    }
  },
  "cancellation_details": {
    "cancelled_at": "2015-11-17T09:57:48.370302Z",
    "api_penalty": {
      "currency": "USD",
      "value": 0
    },
    "api_penalty_percentage": 0
  },
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [      
      {
        "penalty_percentage": 100,
        "date_from": "2015-08-01T00:00:00Z",
        "date_to": "2015-08-04T00:00:00Z"
      }
    ]
  },
  "booking_details": {
    "customer_reference": "zbr-1234",
    "customer_booking_id": ""
  }
}
Fields Value Description
booking_id Type: GUID The booking_id from the request.
client_reference Type: String Custom reference id assigned by the client during pre-book.
status Type: String The status of the booking. See the list of possible status here.
status_payment Type: String The status of the booking. See the list of possible status here.
status_payment_attempt Type: JSON array The list of payment attempts and status.
supplier_name Type: String The name of supplier used for the booking. Avalable only when booking status is confirmed or cancelled.
destination_id Type: String Destination code from the list of destinations. The full list is available here.
requested_at Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
Time when the booking was requested.
confirmed_at Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
Time when the booking was confirmed.
package Type: JSON The package selected for the booking.
guest Type: JSON The guest information of the booking.
pricing Type: JSON The pricing of the booking.
cancellation_policy Type: JSON The cancellation polices for the booking.
cancellation_details Type: JSON The cancellation details of the cancelled booking.
booking_details Type: JSON The booking details of the booking. It will only present after the booking has been confirmed.

Response Fields: package

Fields Value Description
hotel_id Type: GUID The unique ID of the hotel.
room_details Type: JSON The detail of the room booked.
check_in_date Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
The check in date.
check_out_date Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
The checkout date.
adult_count Type: Integer The number of adult for the booking.
child_count Type: Integer The number of children for the booking.
room_count Type: Integer The number of rooms for the booking.

Response Fields: guest

Fields Value Description
salutation Type: String Salutation fields. e.g. 'Mr.’, 'Ms.’, or 'Mrs.’.
first_name Type: String The first name of the guest.
last_name Type: String The last name of the guest.
email Type: String The email of the guest.
city Type: String The address of the guest (city).
state Type: 2 char The state code. The full list of states are available here.
street Type: String The address of the guest (street).
postal_code Type: String The address of the guest (postal code).
country Type: 2 char The ISO 3166 country code. The full list of countries are available here.
nationality Type: 2 char The nationality of the guest. The ISO 3166 country code. The full list of countries are available here.
contact_no Type: String The contact number of the guest.
remarks Type: String Any remarks that the guest passed along the booking.

Response Fields: pricing

The pricing section shows the booking pricing information. The zumata price is the price sold by Zumata to the API consumer. The client price is the price sold by the API consumer to the client (if available/reported).

Fields Value Description
currency Type: String The currency of the value. e.g. USD.
value Type: Float The pricing value (in the currency specified).

Response Fields: status payment attempt

The payment attempts and status.

Fields Value Description
uuid Type: String The payment uuid.
status Type: String The payment status.

Response Fields: Cancellation details

Booking object will contain cancellation_details in case if booking was cancelled.

Fields Value Description
cancelled_at Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
Date when booking was cancelled.
api_penalty Type: JSON The price that was charged to API user for the booking cancellation.
api_penalty_percentage Type: Float The percentage that was charged to the API user for the booking cancellation.
cancellation_note Type: String The extra note regarding the cancellation.

The api_penalty is the price that was charged to the API user for the booking cancellation.

Fields Value Description
currency Type: String The currency of the api_penalty. See the list of currencies here.
value Type: String The amount to be charged.

Response Fields: Booking details

Booking object will contain booking_details once the booking has been confirmed. Your customer might need to show the booking details to the hotel staff during the check-in process.

Fields Value Description
customer_reference Type: String The booking reference number.
customer_booking_id Type: String The booking unique ID.

Response Fields: Booking status

Fields Description
bkg-ns Initial state
bkg-ip Booking in progress
bkg-cf Confirmed
bkg-cx Cancelled
bkg-af Booking acquisition failed
bkg-ps
Confirmation pending on the supplier side. This state happens very rarely and will be updated to a final state (confirmed / failed) typically within an hour. You are advised to watch bookings that fall into this state by polling their status.

Response Fields: Payment status

Fields Description
acc-uk Account status unknown
acc-rs Account reserved
acc-rv Account reversed
acc-cp Account captured
acc-cx Account cancelled
acc-sc Account scheduled
pay-cr-s Payment creation success
pay-si-s Payment signature success
pay-au-s Payment authorization success
pay-ca-s Payment capture success
pay-vo-s Payment void authorization success
pay-re-s Payment refund(credit) success

Error status

Fields Description
acc-ge Account general error
acc-if Account insufficient fund
acc-lr Account low reserve
pay-cr-f Payment creation failure
pay-si-f Payment signature failure
pay-au-f Payment authorization failure
pay-ca-f Payment capture failure
pay-vo-f Payment void authorization failure
pay-re-f Payment refund(credit) failure

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

GET /book/list

Retrieves the list of booking performed.

Request URL

GET https://api-v3.zumata.com/book/list

GET /book/list HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

Request Parameters

Parameter Required Value Description
requested_at_from true Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
The lower bound of the date at which the booking was made.
requested_at_to true Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
The higher bound of the date at which the booking was made.
check_in_date_from true Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
The lower bound of the check_in_date of the booking request.
check_in_date_to true Type: Date
Format: YYYY-MM-DDThh:mm:ss.sTZD
The higher bound of the check_in_date of the booking request.
guest_first_name true Type: String The first_name specified in the booking request.
guest_last_name true Type: String The last_name specified in the booking request.
count true Type: Int The number of booking to return.

Response Fields

Response body

[
  {
    "booking_id": "7c738d11-fbf5-44fc-74ee-0ffc5aaa8984",
    "client_reference": "7682197",
    "status": "bkg-cf",
    "status_payment": "acc-cp",
    "supplier_name": "Hotelbeds",
    "requested_at": "2015-07-15T12:34:03.872408+08:00",
    "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
    "package": {
      "hotel_id": "NBUd",
      "room_details": {
        "description": "Ambassadors",
        "food": 0,
        "room_type": "Ambassadors",
        "room_view": "",
        "beds": {
          "queen": 1
        }
      },
      "check_in_date": "2015-08-04",
      "check_out_date": "2015-08-05",
      "adult_count": 2,
      "room_count": 1
    },
    "guest": {
      "salutation": "Mr.",
      "first_name": "Charlie",
      "last_name": "Smith",
      "email": "charlie.smith@zumata.com",
      "city": "Montreal",
      "state": "QC",
      "street": "123 Outtamy way",
      "postal_code": "H3H0H0",
      "country": "CA",
      "nationality": "CA",
      "contact_no": "+1 514 676-9827",
      "remarks": ""
    },
    "pricing": {
      "zumata": {
        "currency": "USD",
        "value": 5.0
      },
      "client": {
        "currency": "USD",
        "value": 100.0
      }
    },
    "cancellation_policy": {
      "remarks": "",
      "cancellation_policies": [      
        {
          "penalty_percentage": 100,
          "date_from": "2015-08-01T00:00:00Z",
          "date_to": "2015-08-04T00:00:00Z"
        }
      ]
    },
    "booking_details": {
      "customer_reference": "zbr-1234",
      "customer_booking_id": ""
    }
  },
  {
    "booking_id": "9dbcfee0-8d4b-437c-955c-2b6203bb8c12",
   "client_reference": "7682197",
   "status": "bkg-cx",
    "status_payment": "acc-cx",
    "supplier_name": "Hotelbeds",
    "requested_at": "2015-07-15T12:34:03.872408+08:00",
    "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
    "package": {
      "hotel_id": "NBUd",
      "room_details": {
        "description": "Ambassadors",
        "food": 0,
        "room_type": "Ambassadors",
        "room_view": "",
        "beds": {
          "queen": 1
        }
      },
      "check_in_date": "2015-08-04",
      "check_out_date": "2015-08-05",
      "adult_count": 2,
      "room_count": 1
    },
    "guest": {
      "salutation": "Mr.",
      "first_name": "Charlie",
      "last_name": "Smith",
      "email": "charlie.smith@zumata.com",
      "city": "Montreal",
      "state": "QC",
      "street": "123 Outtamy way",
      "postal_code": "H3H0H0",
      "country": "CA",
      "nationality": "CA",
      "contact_no": "+1 514 676-9827",
      "remarks": ""
    },
    "pricing": {
      "zumata": {
        "currency": "USD",
        "value": 5.0
      },
      "client": {
        "currency": "USD",
        "value": 100.0
      }
    },
    "cancellation_details": {
      "cancelled_at": "2015-11-17T09:57:48.370302Z",
      "api_penalty": {
        "currency": "USD",
        "value": 0
      },
      "api_penalty_percentage": 0
    },
    "cancellation_policy": {
      "remarks": "",
      "cancellation_policies": [      
        {
          "penalty_percentage": 100,
          "date_from": "2015-08-01T00:00:00Z",
          "date_to": "2015-08-04T00:00:00Z"
        }
      ]
    },
    "booking_details": {
      "customer_reference": "zbr-1234",
      "customer_booking_id": ""
    }
  }
]

List of booking status response

Response Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned.

POST /cancel

Cancels a booking.

Request URL

POST https://api-v3.zumata.com/cancel

Request Parameters

POST /cancel HTTP/1.1
Host: api-v3.zumata.com
X-Api-Key: <YOUR API KEY>

Request body

{
  "booking_id": "7c738d11-fbf5-44fc-74ee-0ffc5aaa8984"
}
Parameter Required Value Description
booking_id Yes Type: GUID The booking ID returned from the booking response.

Response Fields

Response body

{
  "booking_id": "3b0a95ef-fa68-4b1a-9306-3fdb5068d845",
  "client_reference": "7682197",
  "status": "bkg-cx",
  "status_payment": "acc-cx",
  "supplier_name": "Hotelbeds",
  "destination_id": "RsBU",
  "requested_at": "2015-07-15T12:34:03.872408+08:00",
  "confirmed_at": "2015-07-15T12:44:03.872408+08:00",
  "package": {
    "hotel_id": "NBUd",
    "room_details": {
      "description": "Presidential Suite",
      "food": 2,
      "room_type": "Presidential",
      "room_view": "City",
      "beds": {
        "single": 1
      }
    },
    "check_in_date": "2016-08-04",
    "check_out_date": "2016-08-05",
    "adult_count": 2,
    "room_count": 1
  },
  "guest": {
    "salutation": "Mr.",
    "first_name": "Charlie",
    "last_name": "Smith",
    "email": "charlie.smith@zumata.com",
    "city": "Montreal",
    "state": "QC",
    "street": "123 Outtamy way",
    "postal_code": "H3H0H0",
    "country": "CA",
    "nationality": "CA",
    "contact_no": "+1 514 676-9827",
    "remarks": ""
  },
  "pricing": {
    "zumata": {
      "currency": "USD",
      "value": 21
    },
    "client": {
      "currency": "USD",
      "value": 100
    }
  },
  "cancellation_details": {
    "cancelled_at": "2016-05-17T09:57:48.370302Z",
    "api_penalty": {
      "currency": "USD",
      "value": 8.40
    },
    "api_penalty_percentage": 40
  },
  "cancellation_policy": {
    "remarks": "",
    "cancellation_policies": [      
      {
        "penalty_percentage": 40,
        "date_from": "2016-05-01T00:00:00Z",
        "date_to": "2016-05-31T00:00:00Z"
      }
      {
        "penalty_percentage": 100,
        "date_from": "2015-06-01T00:00:00Z",
        "date_to": "2015-08-04T00:00:00Z"
      }
    ]
  },
  "booking_details": {
    "customer_reference": "zbr-1234",
    "customer_booking_id": "3496"
  },
  "penalty_percentage": 40
}

When the cancellation is successful, a response status 200 is returned together with latest booking status and a penalty percentage.

Fields Value Description
penalty_percentage Type: Number The penalty percentage to pay when cancelling.

Refer to booking status response for explanation of other fields.

Response Errors

Standard errors may be returned.

HTTP Status Code Description
404 Not Found: The booking ID is invalid or not found.
422 Unprocessable entity: The booking is in a non cancellable state.

Payment

All payments are done on a separate system from the hotel api.

Payment flows

To pay for a booking, you need a payment that has been authorized. Complete the create and authorization step to get the payment.

Scenario 1

Clients do not have any interactions with Zumata payment.

Scenario 2

The followings are the steps:

  1. Clients create a payment (provider: cybersource) with callback URL and payload, and get a payment ID
  2. Clients generate a signature with the payment ID, currency, amount and other fields
  3. Clients call cybersource directly
  4. Auth results are form posted to the callback URL
  5. Clients make a booking with the payment ID if auth results are a success

Check out Payment SDK

Scenario 3

The followings are the steps:

  1. Clients lead users to Zumata payment frontend to enter credit card info.
  2. Auth results are form posted to the callback URL
  3. Clients make a booking with the payment ID if auth results are a success

Authentication

Create a payment with an invalid payment key

POST /api/create HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Invalid Payment Key>

{
  "provider": "cybersource",
  "callback_url": "www.my.com/callback"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{}

To make payment for a booking, you will be given an additional Payment Key which is used to interact with the payment subsystem. This Payment Key should be used solely for payment purposes. The Payment Key should be in the request header X-Payment-Key

Environments

Environment Host
Production https://payment-v3.zumata.com
Test https://test-payment-v3.zumata.com

Payment providers

Zumata payment gateways supports different types of payment getaways:

Create a payment

Create a payment with provider as “cybersource”

POST /api/create HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Your Payment Key>

{
  "provider": "cybersource",
  "callback_url": "https://payment.abc.com/callback",
  "callback_payload": "{'name': 'Josh', 'email': 'josh@example.com'}"
}
HTTP/1.1 201 OK
Content-Type: application/json

{
  "id": "c129f788-5c33-11e5-885d-feff819cdc9f"
}

callback_url is required

POST /api/create HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Your Payment Key>

{
  "provider": "cybersource"
}
HTTP/1.1 422 status code 422
Content-Type: application/json

{
  "message":"Validation failed",
  "errors":[{
    "field":"callback_url",
    "code":"missing"
  }]
}

Provider is not supported

POST /api/create HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Your Payment Key>

{
  "provider": "abc",
  "callback_url": "https://payment.abc.com/callback"
}
HTTP/1.1 422 status code 422
Content-Type: application/json

{
  "message":"Provider is not supported"
}

Request URL

POST https://payment.zumata.com/api/create

Request Parameters

Parameter Required Value Description
provider Yes Type: String The payment provider.
callback_url Yes Type: String The callback URL.
callback_payload No Type: String The callback payload.

Response Fields

The response body contain the payment id used for the booking payment request.

Fields Value Description
id Type: String The unique payment ID. This ID is needed for the booking payment request.

Generate a signature

Generate a signature successfully

POST /api/generateSignature/c129f788-5c33-11e5-885d-feff819cdc9f HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Your payment Payment Key>

{
  "bill_to_forename": "Josh",
  "bill_to_surname": "Ziegler",
  "bill_to_address_line1": "1 Card Lane",
  "bill_to_address_city": "My City",
  "bill_to_address_state": "CA",
  "bill_to_address_country": "US",
  "bill_to_address_postal_code": "123456",
  "bill_to_email": "josh@zumata.com",
  "currency": "USD",
  "amount": 123.45,
  "card_type": "001",
  "card_expiry_date": "01-2020",
  "card_cvn": "765"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "signature":"/ru6pD/bnv9kJA5ggLT/GYAfRAThXOK24stvS6H4Ks4=",
  "fields":{
    "access_key":"8f5b160603513d598378b1ab352f08fc",
    "amount":"100",
    "bill_to_address_city":"My City",
    "bill_to_address_country":"US",
    "bill_to_address_line1":"1 Card Lane",
    "bill_to_address_postal_code":"123456",
    "bill_to_address_state":"CA",
    "bill_to_email":"josh@zumata.com",
    "bill_to_forename":"Josh",
    "bill_to_surname":"Ziegler",
    "card_type": "001",
    "card_expiry_date": "01-2020",
    "card_cvn": "765",
    "currency":"SGD",
    "locale":"en",
    "payment_method":"card",
    "profile_id":"96EBC32C-0B9B-4693-9B9D-72565E56E0F8",
    "reference_number":"c129f788-5c33-11e5-885d-feff819cdc9f",
    "signature":"/ru6pD/bnv9kJA5ggLT/GYAfRAThXOK24stvS6H4Ks4=",
    "signed_date_time":"2015-10-05T05:09:29Z",
    "signed_field_names":"access_key,locale,payment_method,profile_id,reference_number,signed_date_time,signed_field_names,transaction_type,transaction_uuid,unsigned_field_names,amount,currency,bill_to_forename,bill_to_surname,bill_to_email,bill_to_address_line1,bill_to_address_city,bill_to_address_country,card_cvn,card_expiry_date,card_type,bill_to_address_state,bill_to_address_postal_code",
    "transaction_type":"authorization",
    "transaction_uuid":"cfe0bda8-6433-4d4c-a2af-178a0efbbb08",
    "unsigned_field_names":"card_number"
  }
}

Generate a signature with missing fields

POST /api/generateSignature/c129f788-5c33-11e5-885d-feff819cdc9f HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Your payment Payment Key>

{}
HTTP/1.1 422 status code 422
Content-Type: application/json

{
  "message":"Validation failed",
  "errors":[
    {"field":"bill_to_forename","code":"missing"},
    {"field":"bill_to_surname","code":"missing"},
    {"field":"bill_to_email","code":"missing"},
    {"field":"bill_to_address_line1","code":"missing"},
    {"field":"bill_to_address_city","code":"missing"},
    {"field":"bill_to_address_country","code":"missing"},
    {"field":"currency","code":"missing"},
    {"field":"card_type","code":"missing"},
    {"field":"card_expiry_date","code":"missing"},
    {"field":"card_cvn","code":"missing"},
    {"field":"amount","code":"invalid"}
]}

Card type and currency are not supported

POST /api/generateSignature/c129f788-5c33-11e5-885d-feff819cdc9f HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/json
X-Payment-Key: <Your payment Payment Key>

{
  "bill_to_forename": "Josh",
  "bill_to_surname": "Ziegler",
  "bill_to_address_line1": "1 Card Lane",
  "bill_to_address_city": "My City",
  "bill_to_address_state": "CA",
  "bill_to_address_country": "US",
  "bill_to_address_postal_code": "123456",
  "bill_to_email": "josh@zumata.com",
  "currency": "YEN",
  "amount": 123.45,
  "card_type": "001",
  "card_expiry_date": "01-2020",
  "card_cvn": "765"
}
HTTP/1.1 422 status code 422
Content-Type: application/json

{
  "message":"Card type and currency are not supported"
}

Clients only need to generate this signature if they want to use their own payment frontend (Scenario 2). After a signature is generated, clients can send all the returned fields together with card number to Cybersource for authorization. Check out Payment SDK

Request URL

POST https://payment.zumata.com/api/generateSignature/[PAYMENT_ID]

Request Parameters

Parameter Required Value Description
currency Yes Type: String The payment currency
amount Yes Type: Number The payment amount
bill_to_forename Yes Type: String The foremane
bill_to_surname Yes Type: String The surename
bill_to_address_line1 Yes Type: String The address line
bill_to_address_city Yes Type: String The city
bill_to_address_country Yes Type: String Two-letter country code
bill_to_address_state Yes for US and Canada Type: String Two-letter state code
bill_to_address_postal_code Yes for US and Canada Type: String The postal code
bill_to_email Yes Type: String The email
card_type Yes Type: String 001 for Visa; 002 for MasterCard; 003 for Amex
card_expiry_date Yes Type: String The format is mm-yyyy
card_cvn Yes Type: String The security code of the credit card

Response Fields

Fields Value Description
Signature Type: String The generated signature
Fields Type: Array The returned fields

Payment frontend

Invalid payment key

POST / HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/x-www-form-urlencoded

currency=USD&amount=123.45&X-Payment-Key=xxx=&callback_url=www.my.com/callback&callback_payload={'name': 'josh', 'email':'josh@zumata.com'}&signature=xxx
HTTP/1.1 401 Unauthorized
Content-Type: text/html
<!doctype html>
<html>
  <body>
    <form method="POST" id="payForm" action="www.my.com/callback">
      <input type="text" name="authorized" value="false">
      <input type="text" name="errorMessage" value="Invalid payment key">
      <input type="text" name="errorDetails" value="null">
      <input type="text" name="payload" value="{&#39;name&#39;: &#39;josh&#39;, &#39;email&#39;:&#39;josh@zumata.com&#39;}">

      <input type="submit">
    </form>
    <script>
      document.getElementById("payForm").submit();
    </script>
  </body>
</html>

Signature did not match

POST / HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/x-www-form-urlencoded

currency=USD&amount=123.45&X-Payment-Key=xJwu9yr8TynLGAU2pUhqJVrHFD9NEW/xVuQ+L4X1snU=&callback_url=www.my.com/callback&callback_payload={'name': 'josh', 'email':'josh@zumata.com'}&signature=xxx
HTTP/1.1 422 status code 422
Content-Type: text/html
<!doctype html>
<html>
  <body>
    <form method="POST" id="payForm" action="www.my.com/callback">
      <input type="text" name="authorized" value="false">
      <input type="text" name="errorMessage" value="Signature did not match">
      <input type="text" name="errorDetails" value="null">
      <input type="text" name="payload" value="{&#39;name&#39;: &#39;josh&#39;, &#39;email&#39;:&#39;josh@zumata.com&#39;}">

      <input type="submit">
    </form>
    <script>
      document.getElementById("payForm").submit();
    </script>
  </body>
</html>

Missing fields without callback_url

POST / HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 422 status code 422
Content-Type: text/html
<!doctype html>
<html>
  <head>
    <title>Payment - Powered by Zumata</title>
  </head>

  <body>
    <h1>Error!</h1>

    <p>Validation failed</p>
    <p>[{&#34;field&#34;:&#34;X-Payment-Key&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;currency&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;callback_url&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;signature&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;amount&#34;,&#34;code&#34;:&#34;invalid&#34;}]</p>
  </body>
</html>

Missing fields with callback_url

POST / HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/x-www-form-urlencoded

callback_url=www.my.com/callback
HTTP/1.1 422 status code 422
Content-Type: text/html
<!doctype html>
<html>
  <body>
    <form method="POST" id="payForm" action="www.my.com/callback">
      <input type="text" name="authorized" value="false">
      <input type="text" name="errorMessage" value="Validation failed">
      <input type="text" name="errorDetails" value="[{&#34;field&#34;:&#34;X-Payment-Key&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;currency&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;signature&#34;,&#34;code&#34;:&#34;missing&#34;},{&#34;field&#34;:&#34;amount&#34;,&#34;code&#34;:&#34;invalid&#34;}]">
      <input type="text" name="payload" value="">

      <input type="submit">
    </form>
    <script>
      document.getElementById("payForm").submit();
    </script>
  </body>
</html>

Currency was not supported

POST / HTTP/1.1
HOST: payment.zumata.com
Content-Type: application/x-www-form-urlencoded

currency=YEN&amount=123.45&X-Payment-Key=xJwu9yr8TynLGAU2pUhqJVrHFD9NEW/xVuQ L4X1snU=&callback_url=www.my.com/callback&callback_payload={'name': 'josh', 'email':'josh@zumata.com'}&signature=/Jhf5uEEnxBpNz2btkd8qi2Rrj08QMNSgoTSGRl71xY=
HTTP/1.1 422 status code 422
Content-Type: text/html
<!doctype html>
<html>
  <body>
    <form method="POST" id="payForm" action="www.my.com/callback">
      <input type="text" name="authorized" value="false">
      <input type="text" name="errorMessage" value="This currency was not supported">
      <input type="text" name="errorDetails" value="null">
      <input type="text" name="payload" value="{&#39;name&#39;: &#39;josh&#39;, &#39;email&#39;:&#39;josh@zumata.com&#39;}">

      <input type="submit">
    </form>
    <script>
      document.getElementById("payForm").submit();
    </script>
  </body>
</html>

Request URL

POST https://payment.zumata.com/

Request Parameters

Parameter Required Value Description
currency Yes Type: String The payment currency; currency must be supported in its cybersource profiles
amount Yes Type: Number The payment amount
X-Payment-Key Yes Type: String The payment key
callback_url Yes Type: String The callbck URL
callback_payload No Type: String The callback payload
signature Yes Type: String The signature; How to generate it in Go

Response Fields

The response is the payment frontend html page

Currencies

The current list of supported currencies that may be used when calling endpoints which support a currency parameter. In making calls to ZUMATA endpoints, please send only the currency codes.

Code Label
AUD Australian Dollar
CAD Canadian Dollar
CHF Swiss Franc
EUR Euro
GBP Pound Sterling
HKD Hong Kong Dollar
JPY Japanese Yen
NZD New Zealand Dollar
SGD Singapore Dollar
USD United States Dollar

Static Data

Environments

Environment Host
Test beta.data.zumata.com (HTTP)
Production data.zumata.com (HTTP)

Useful static data file downloads

Active hotel list (id, name, address, geo)

Static Data Hotel Response Format

Response Fields: Hotel (long format)

Long format (long format hotel object)

{
  "address": "110 Tanah Merah Coast Road ,Singapore 498800",
  "amenities": {
    "airConditioning": true,
    "airportTransportation": false,
    "businessCenter": true,
    "carRentDesk": false,
    "childrenAllowed": false,
    "clothingIron": true,
    "coffeeTeaMaker": false,
    "combination": false,
    "continentalBreakfast": false,
    "dataPorts": false,
    "dryCleaning": false,
    "electronicRoomKeys": false,
    "exteriorRoomEntrance": false,
    "familyRooms": false,
    "fitnessFacility": false,
    "gameRoom": false,
    "golfCourse": false,
    "hairDryer": false,
    "handicapAccessible": true,
    "inHouseBar": false,
    "inHouseDining": false,
    "inRoomMovies": false,
    "indoorPool": false,
    "interiorRoomEntrance": true,
    "kitchen": false,
    "map": false,
    "meetingRooms": false,
    "miniBarInRoom": false,
    "nonSmokingRooms": false,
    "outdoorPool": false,
    "parkingGarage": true,
    "petsAllowed": true,
    "restrictedAccess": false,
    "roomService": false,
    "safe": false,
    "sauna": false,
    "tVInRoom": false,
    "tennisCourt": false,
    "twentyFourHourSecurity": false,
    "valetParking": false,
    "videoCheckOut": false,
    "voiceMail": false,
    "wakeUpService": true,
    "whirpool": false
  },
  "city": "Singapore",
  "country": "Singapore",
  "country_code": "SG",
  "description": "Property Category: Unknown. Property Type: Inn. Total rooms and suites: 76. Floors: 3. Property description- Welcome to the Days Inn Olathe Medical Center, KS. We are located on the south end of Olathe off of exit 215 from I-35 approx. 30 miles south of Kansas City. Our property is in the south parking lot of the Great Mall of the Great Plains. There are several restaurants nearby. Olathe Medical Center is across the street. We do offer refrigerators and microwaves in some rooms based on availability. Complimentary Deluxe Continental Breakfast is included as well as Complimentary Wireless Internet Access.. Onsite facilities information- ParkingProperty was built in 1999. Hotel Currency: USD.",
  "highest_daily_rate": 0,
  "id": "yAbP",
  "image_details": {
    "count": 1,
    "prefix": "https://s3-ap-southeast-1.amazonaws.com/zumata/assets/hotels/2.0/138d1b34-24bb-44f3-5c53-8c84f32223b4/images",
    "suffix": ".jpg"
  },
  "latitude": 1.31622,
  "longitude": 104.01537,
  "lowest_daily_rate": 0,
  "meta_image_details": {
    "count": 0,
    "descs": null,
    "prefix": "",
    "suffix": ""
  },
  "name": "Saf Yacht Club Changi Resort Rooms",
  "postal_code": "",
  "rating": 3,
  "state_province": "",
  "trip_advisor_rating": 0,
  "trip_advisor_review_count": 0,
  "trustyou_rating": 61,
  "trustyou_review_count": 154,
  "phone": "6758 3032",
  "fax": "6389 3754",
  "email": "",
  "website": ""
}
Fields Value Description
id Type: String The unique ID of the hotel.
name Type: String The name of the hotel.
phone Type: String The phone of the hotel.
fax Type: String The fax of the hotel.
email Type: String The email of the hotel.
website Type: String The website of the hotel.
address Type: String The address of the hotel.
amenities Type: JSON The amenities provided by the hotel.
city Type: String The city of the hotel.
country Type: String The country name of the hotel.
country_code Type: String The country code (ISO 3166-1 alpha 2) of the hotel.
state_province Type: String The hotel’s state province.
postal_code Type: String The hotel’s postal code.
latitude Type: Float The latitude of the hotel.
longitude Type: Float The longitude of the hotel.
description Type: String The description of the hotel.
rating Type: Float The rating of the hotel.
highest_daily_rate Type: Float The highest daily rate of the hotel.
lowest_daily_rate Type: Float The lowest daily rate of the hotel.
image_details Type: JSON The images of the hotel.
meta_image_details Type: JSON The meta images of the hotel.
trip_advisor_rating Type: Integer The hotel’s rating on tripadvisor.com.
trip_advisor_review_count Type: Integer The number of reviews on tripadvisor.com for this hotel.
trustyou_rating Type: Integer The hotel’s rating on trustyou.com.
trustyou_review_count Type: Integer The number of reviews on trustyou.com for this hotel.
policy Type: HTML HTML formatted general hotel policy.

Response Fields: Hotel (short format)

Short format (short format hotel object)

{
  "address": "110 Tanah Merah Coast Road ,Singapore 498800",
  "city": "Singapore",
  "country": "Singapore",
  "country_code": "SG",
  "approximate_cost": 0,
  "id": "yAbP",
  "image_details": {
    "count": 1,
    "prefix": "https://s3-ap-southeast-1.amazonaws.com/zumata/assets/hotels/2.0/138d1b34-24bb-44f3-5c53-8c84f32223b4/images",
    "suffix": ".jpg"
  },
  "latitude": 1.31622,
  "longitude": 104.01537,
  "name": "Saf Yacht Club Changi Resort Rooms",
  "rating": 3,
  "trip_advisor_rating": 0,
  "trip_advisor_review_count": 0,
  "trustyou_rating": 61,
  "trustyou_review_count": 154
}
Fields Value Description
id Type: String The unique ID of the hotel.
name Type: String The name of the hotel.
address Type: String The address of the hotel.
city Type: String The city of the hotel.
country Type: String The country of the hotel.
country_code Type: String The country code (ISO 3166-1 alpha 2) of the hotel.
latitude Type: Float The latitude of the hotel.
longitude Type: Float The longitude of the hotel.
approximate_cost Type: Float The hotel’s approximate cost.
rating Type: Float The rating of the hotel.
image_details Type: JSON The images of the hotel.
trip_advisor_rating Type: Integer The hotel’s rating on tripadvisor.com.
trip_advisor_review_count Type: Integer The number of reviews on tripadvisor.com for this hotel.
trustyou_rating Type: Integer The hotel’s rating on trustyou.com.
trustyou_review_count Type: Integer The number of reviews on trustyou.com for this hotel.

Response Fields: Image details

Parameter Value Description
count Type: Integer The total number of images available for this hotel.
prefix Type: String The prefix of the image URL.
suffix Type: String The suffix of the image URL.

The format of the image URL: prefix + / + [image index] + suffix

The [image index] always start with 0 and end with count - 1 (zero-based)

Example image URLs for image details with image count of 4:

https://s3-ap-southeast-1.amazonaws.com/zumata/assets/hotels/2.0/138d1b34-24bb-44f3-5c53-8c84f32223b4/images/0.jpg

https://s3-ap-southeast-1.amazonaws.com/zumata/assets/hotels/2.0/138d1b34-24bb-44f3-5c53-8c84f32223b4/images/3.jpg

Response Fields: Hotel amenities

Hotel amenities object is a map of string to boolean, click here for full list of all available amenities.

Available amenities

airConditioning, airportTransportation, businessCenter, carRentDesk, childrenAllowed, clothingIron, coffeeTeaMaker, combination, continentalBreakfast, dataPorts, dryCleaning, electronicRoomKeys, exteriorRoomEntrance, familyRooms, fitnessFacility, gameRoom, golfCourse, hairDryer, handicapAccessible, inHouseBar, inHouseDining, inRoomMovies, indoorPool, interiorRoomEntrance, kitchen, map, meetingRooms, miniBarInRoom, nonSmokingRooms, outdoorPool, parkingGarage, petsAllowed, restrictedAccess, roomService, safe, sauna, tVInRoom, tennisCourt, twentyFourHourSecurity, valetParking, videoCheckOut, voiceMail, wakeUpService, whirpool

Static Data Endpoints

Destination Auto Suggestions Endpoint

Hotel Reviews Endpoint

Country and states Endpoints

GET /destinations/[DEST_ID]/[LANG]/[FORMAT].json

Retrieves hotels by destination id.

Request URL

GET http://data.zumata.com/destinations/[DEST_ID]/[LANG]/[FORMAT].json

GET /destinations/RsBU/en_US/long.json HTTP/1.1
Host: data.zumata.com

Request Parameters:

Parameter Required Value Description
[DEST_ID] Yes Type: String Destination code from the list of destinations. The full list of destinations is available here.
[LANG] Yes Type: String The language of the returned content.
[FORMAT] Yes Type: String The format of the returned content.

Supported languages:

en_US, ar_SA, cs_CZ, da_DK, de_DE, el_GR, es_ES, es_MX, fi_FI, fr_FR, fr_CA, in_ID, it_IT, ja_JP, ko_KR, ms_MY, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, vi_VN, zh_CN, zh_TW

Supported formats:

long, short

Response

Response body (long format). Please see details explanation for [long format hotel object] here.

[
  [long format hotel object],
    .
    .
    .
]

The response body is in JSON array format and it contains a list of hotels objects that associated with the [DEST_ID]. The fields of hotels objects are controlled by the [FORMAT] provided in the URL.

Response body (short format). Please see details explanation for [short format hotel object] here.

[
  [short format hotel object],
    .
    .
    .
]

GET /hotels/[HOTEL_ID]/[LANG]/[FORMAT].json

Retrieves hotel by hotel id.

Request URL

GET http://data.zumata.com/hotels/[HOTEL_ID]/[LANG]/[FORMAT].json

GET /hotels/yAbP/en_US/long.json HTTP/1.1
Host: data.zumata.com

Request Parameters:

Parameter Required Value Description
[HOTEL_ID] Yes Type: String The hotel id returned from destination endpoint result. The full list of hotels is available here.
[LANG] Yes Type: String The language of the returned content.
[FORMAT] Yes Type: String The format of the returned content.

Supported languages:

en_US, ar_SA, cs_CZ, da_DK, de_DE, el_GR, es_ES, es_MX, fi_FI, fr_FR, fr_CA, in_ID, it_IT, ja_JP, ko_KR, ms_MY, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, vi_VN, zh_CN, zh_TW

Supported formats:

long, short

Response

Response body (long format). Please see details explanation for [long format hotel object] here.

[long format hotel object]
      +
{
  "destination_ids": ["RsBU"],
  "original_name": "Saf Yacht Club Changi Resort Rooms"
}

Additional Fields: Hotel (long format)

The response body is in JSON format and it is similar to hotels objects but with two additional fields.

Fields Value Description
destination_ids Type: JSON Array A list of destination ids that the hotel associated to.
original_name Type: String The hotel name before translation.

Response body (short format). Please see details explanation for [short format hotel object] here.

[short format hotel object]
      +
{
  "original_name": "Saf Yacht Club Changi Resort Rooms"
}

Additional Fields: Hotel (short format)

The response body is in JSON format and it is similar to hotels objects but with one additional fields.

Fields Value Description
original_name Type: String The hotel name before translation.

POST /hotels/[LANG]/[FORMAT].json

Retrieves hotels by hotel ids.

Request URL

POST http://data.zumata.com/hotels/[LANG]/[FORMAT].json

POST /hotels/en_US/long.json HTTP/1.1
Host: data.zumata.com
Content-Type: application/json

Request Parameters:

Parameter Required Value Description
[LANG] Yes Type: String The language of the returned content.
[FORMAT] Yes Type: String The format of the returned content.

Supported languages:

en_US, ar_SA, cs_CZ, da_DK, de_DE, el_GR, es_ES, es_MX, fi_FI, fr_FR, fr_CA, in_ID, it_IT, ja_JP, ko_KR, ms_MY, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, vi_VN, zh_CN, zh_TW

Request Body:

Request body

{
  "hotel_list": ["Kh6r", "jGSw", "dcfd"] 
}

The request body is in JSON format and it contains a list of hotel-ids.

Parameter Required Value Description
hotel_list Yes Type: String Array The list of hotel-ids.

Supported formats:

long, short

Response:

The response body is in JSON format and it contains a list of hotel id key and hotels objects value pairs. The full list of hotel ids is available here. The fields of hotels objects are controlled by the [FORMAT] provided in the URL.

Response body (long format). Please see details explanation for [long format hotel object] here.

{
  "Kh6r": {
    [long format hotel object]
          +
    "original_name": "Graha Beach Senggigi Hotel"
  },
  "jGSw": {},
  "dcfd": {}
}

Additional Fields: Hotel (long format)

The response body is in JSON format and it is similar to hotels objects but with one additional field.

Fields Value Description
original_name Type: String The hotel name before translation.

Response body (short format). Please see details explanation for [short format hotel object] here.

{
  "Kh6r": {
    [short format hotel object]
          +
    "original_name": "Graha Beach Senggigi Hotel"
  },
  "jGSw": {},
  "dcfd": {}
}

Additional Fields: Hotel (short format)

The response body is in JSON format and it is similar to hotels objects but with one additional field.

Fields Value Description
original_name Type: String The hotel name before translation.

GET /autosuggest

Retrieves the destination auto suggestions based on the types and term in the parameters. (NEW) It is recommended to use the new city_en_US type as this will return a much richer list of locations. The response for this has a region_id field which can be used with a microservice to map regionids directly to hotel id’s and then you can use those id’s with the hotel_list endpoint.

Request URL

GET http://data.zumata.com/autosuggest?[PARAMETERS]

GET /autosuggest?types[]=city&types[]=poi&types[]=hotel&types[]=airport&term=singapore HTTP/1.1
Host: data.zumata.com

Request Parameters:

Parameter Required Value Description
term Yes Type: String The phrase that you wish to search for.
types[] Yes Type: String The destination type that you wish to search for. Can be one of city, poi, airport, multiairport and hotel. (NEW) An additional option is city_en_US. You must specify at least one destination type.
limit No Type: Integer Limit the results for each destination types.

Response body

Response Fields:

{
  "term": "singapore",
  "results": {
    "city": [{
      "id": 87099,
      "term": "Singapore, Singapore",
      "data": {
        "dest_id": "f75a8cff-c26e-4603-7b45-1b0f8a5aa100",
        "longitude": 103.8509491,
        "latitude": 1.2800945,
        "type": "city",
        "city": "Singapore",
        "country": "Singapore",
        "state": "",
        "hotel_count": 104,
        "dest_short_id": "RsBU"
      },
      "score": 1802
    }],
    "poi": [{
      "id": 80645,
      "term": "National Library Board Singapore",
      "data": {
        "dest_id": "f75a8cff-c26e-4603-7b45-1b0f8a5aa100",
        "longitude": 103.854275,
        "latitude": 1.298378,
        "type": "civic",
        "city": "Singapore",
        "country": "Singapore",
        "state": "",
        "hotel_count": 104,
        "dest_short_id": "RsBU"
      },
      "score": 0
    }],
    "hotel": [{
      "id": 76594,
      "term": "Park Regis Singapore",
      "data": {
        "hotel_id": "6c47e9db-cc00-404e-7fa1-8bc3d3f7414a",
        "dest_id": "f75a8cff-c26e-4603-7b45-1b0f8a5aa100",
        "longitude": "103.8445",
        "latitude": "1.2881",
        "type": "hotel",
        "city": "Singapore",
        "country": "Singapore",
        "state": "",
        "hotel_short_id": "VUAq",
        "dest_short_id": "RsBU"
      },
      "score": 157126
    }]
  }
}
Fields Value Description
term Type: String The phrase that you searched for.
results Type: JSON A map with destination type as key and array of auto suggest result objects as value. The auto suggest result objects are sorted by their score in ascending order.

Response Fields: auto suggest result object

Fields Value Description
id Type: Integer The unique ID for each auto suggest result (within the specific destination type).
term Type: String The full name of the destination.
score Type: Integer The ranking of the destination (for results ordering).
data.dest_short_id Type: String The unique ID of the destination.
data.dest_id Type: GUID The unique ID of the destination. (deprecated)
data.region_id Type: String The unique ID of the region. (only returned in city_en_US results)
data.hotel_short_id Type: String The unique ID of the hotel. (for hotel results only)
data.hotel_id Type: GUID The unique ID of the hotel. (deprecated)
data.longitude Type: Float The longitude of the destination.
data.latitude Type: Float The latitude of the destination.
data.type Type: String The type of the destination.
data.city Type: String The city of the destination.
data.country Type: String The country of the destination.
data.state Type: String The state of the destination.
data.hotel_count Type: Integer The total number of available hotels in the destination (not real-time).

GET /hotel_reviews/[HOTEL_ID]

Retrieves the hotel reviews.

Request URL

GET http://data.zumata.com/hotel_reviews/[HOTEL_ID]?[PARAMETERS]

GET /hotel_reviews/yAbP HTTP/1.1
Host: data.zumata.com
X-Api-Key: <YOUR API KEY>

Request Parameters:

Parameter Required Value Description
lang No Type: String Control the language of the returned content.

Supported languages:

en_US, ar_SA, cs_CZ, da_DK, de_DE, el_GR, es_ES, es_MX, fi_FI, fr_FR, fr_CA, in_ID, it_IT, ja_JP, ko_KR, ms_MY, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, vi_VN, zh_CN, zh_TW

Response Fields

Response body

{
  "meta": {
    "code": 200
  },
  "response": {
    "lang": "en",
    "language_meta_review_list": [],
    "reviews_count": 5377,
    "trip_type_meta_review_list": [],
    "category_list": [],
    "good_to_know_list": [],
    "ty_id": "a890c974-76f1-4dd5-92f7-43e75e2e487c",
    "gender_talks_about": null,
    "summary": {
      "hotel_type": {
        "text": "Very good budget hotel."
      },
      "score_description": "Very Good",
      "text": "Very good budget hotel. Close to MRT. Located near shopping areas and has easy access to public transportation. Management, housekeeping and reception are great. Popular among solo travelers.",
      "popular_with": {
        "text": "Popular among solo travelers."
      },
      "popularity": 25,
      "location_nearby": {
        "text": "Close to MRT."
      },
      "score": "84",
      "location": {
        "text": "Located near shopping areas and has easy access to public transportation."
      },
      "reviews_distribution": [{
        "reviews_count": 13,
        "stars": 1
      }, {
        "reviews_count": 75,
        "stars": 2
      }, {
        "reviews_count": 373,
        "stars": 3
      }, {
        "reviews_count": 1990,
        "stars": 4
      }, {
        "reviews_count": 2929,
        "stars": 5
      }],
      "summary_sentence_list": [{
        "text": "Management, housekeeping and reception are great.",
        "category_id_list": ["15e", "15g", "15b"],
        "sentiment": "pos"
      }],
      "highlight_list": [{
        "text": "Close to transport",
        "confidence": 100.0,
        "category_id_list": ["14", "14a"]
      }, {
        "text": "Hotel staff was very friendly",
        "confidence": 100.0,
        "category_id_list": ["ddbc", "15"]
      }]
    },
    "badge_list": [{
      "text": "Great Overall Ranking",
      "subtext": "Top 24% in city",
      "badge_type": "ranking",
      "badge_data": {
        "popularity": 24.845161
      }
    }],
    "hotel_type_list": [{
      "sentiment": "pos",
      "text": "Guests <pos>recommend this hotel for budget travelers</pos>.",
      "popularity": 10.718901996672212,
      "highlight_list": [],
      "score": 95,
      "short_text": "Fine for a budget trip",
      "category_id": "16k",
      "sub_category_list": [],
      "category_name": "Budget Hotel"
    }]
  }
}
Fields Value Description
meta Type: JSON The response meta data.
response Type: JSON The hotel reviews data.

Response Fields: meta

Fields Value Description
code Type: Integer The HTTP status code of the response.

Response Fields: response

Fields Value Description
ty_id Type: String TrustYou ID of the hotel.
lang Type: String Language of the review as requested.
hotel_type_list Type: JSON Array List of hotel type objects.
category_list Type: JSON Array List of category objects. The summary of guest sentiment in the various categories supported by TrustYou.
good_to_know_list Type: JSON Array List of category objects. Interesting tidbits about the hotel – infrequent categories that are still characteristic of the hotel.
summary Type: JSON Array List of summary objects. The summary sentence describes the hotel’s reputation.
language_meta_review_list Type: JSON Array List of filtered review objects. Reviews filtered by different languages.
trip_type_meta_review_list Type: JSON Array List of filtered review objects. Reviews filtered by different trip types (families, couple, solo and etc).
gender_talks_about Type: JSON Object with two properties, women and men, each containing a list of category objects.
reviews_count Type: Integer Number of verified reviews this summary is based on.
badge_list Type: JSON Array List of badge objects. Contains one ranking badge, any number of hotel type badges, and any number of category badges.

hotel_type_list, category_list, good_to_know_list, location_meta_review_list, trip_type_meta_review_list, gender_talks_about and summary object will all contain null if there is not enough information available.

Response Fields: category object

Fields Value Description
category_id Type: Integer ID uniquely identifying a category.
category_name Type: String Name of the category.
short_text Type: String A short description of this category and its sentiment.
summary_sentence_list Type: JSON Array List of sentences which, when joined together, form a summary of all sub categories. Show only the first 1, 2 or 3 sentences if you have limited room; they are sorted by decreasing importance.
score Type: Integer Score of the category.
sentiment Type: String Sentiment of the category (pos, neu, neg).
count Type: Integer Number of distinct reviews where a category is mentioned. Sort by this value to obtain the most or least frequent categories.
relevance Type: Float Float value that quantifies the relevance of the category to the hotel. The higher the value, the more indicative the category is of the hotel as a whole.
highlight_list Type: JSON Array List of highlights for this category. These are short texts that illustrate this category’s sentiment. Up to 3 highlights are currently returned, depending on availability. The list of highlights may be an empty list, even though the category has a count greater than zero.
sub_category_list Type: JSON Array List of category objects. Categories that give further information about a category. The hierarchy of categories is never more than 2 levels deep.

Response Fields: summary sentence

Fields Value Description
text Type: String Text of the sentence, with trailing full stop.
sentiment Type: String Overall sentiment of this sentence (pos, neu, neg, or mixed).
category_id_list Type: [JSON Array] List of category IDs which are mentioned in this sentence. Please refer to http://api.trustyou.com/hotels/categories for list of all categories.

Response Fields: highlight

Fields Value Description
text Type: String Text of the highlight, guaranteed to be in the current display language controlled by lang.
confidence Type: Float A float between 1 and 100, inclusive, which represents the certainty about the quality of the highlight. Use this property to sort or filter highlights by their probability of being grammatically correct. May be null if there is not enough information to calculate this value.
category_id_list Type: [JSON Array] List of category IDs that this highlight belongs to. Please refer to http://api.trustyou.com/hotels/categories for list of all categories.

Response Fields: hotel type object

Hotel type objects are identical to category objects, with the difference that there are no count or relevance properties. Instead, hotel types should be sorted by their popularity.

Fields Value Description
popularity Type: Float Float between 1 and 100, inclusive, 1 being the best. A value of 4 means the hotel is in the fourth percentile of hotels of this type in its city.

Response Fields: filtered review object

Fields Value Description
filter Type: String Object which identifies by which criteria data was filtered for this filtered review. Currently holds two properties: trip_type, whose value is one of business, couple, solo, family, friends, and language.
reviews_percent Type: Integer How many of this hotel’s reviews fall into this filter. Integer between 0 and 100.
category_list Type: JSON Array List of category objects. The summary of guest sentiment in the various categories supported by TrustYou.
good_to_know_list Type: JSON Array List of category objects. Interesting tidbits about the hotel – infrequent categories that are still characteristic of the hotel.
summary Type: JSON Array Abbriged summary objects, which only contains the score, score_description and popularity properties.

Response Fields: summary object

Fields Value Description
score Type: Integer The TrustYou Score of the hotel.
score_description Type: String Textual description of the TrustScore, e.g. “Excellent”.
popularity Type: Float Normalized ranking of the hotel, e.g. “hotel is in the top x% in the city”
text Type: String A summary sentence describing the hotel’s reputation, including remarks about its hotel type and nearby points of interest.
reviews_distribution Type: JSON The histogram of review scores.

Response Fields: reviews distribution

Fields Value Description
stars Type: Integer Score range of reviews. Integer between 1 - 5 (representing a score range of 0—20 on a scale to 100).
reviews_count Type: Integer Number of reviews for this star rating.

Response Fields: badge object

Fields Value Description
badge_type Type: String One of category, ranking or hotel_type.
text Type: String A textual, general description of the badge.
subtext Type: String Text incorporating the badge’s score or rank.
badge_data Type: String An object containing data specific to a badge. Fields vary per badge type.

Response Fields: ranking badge

A badge displaying the overall ranking. This badge is always generated.

Fields Value Description
badge_data.popularity Type: Float The overall ranking, as contained in the summary object.

Response Fields: hotel type badge

A badge for each hotel type for which a hotel is especially popular. A hotel type badge is generated if the hotel is in the top 10th percentile of popularity in its city for that hotel type.

Fields Value Description
badge_data.popularity Type: Float The hotel type popularity.
badge_data.category_id Type: String The category id of the hotel type. Please refer to http://api.trustyou.com/hotels/categories for list of all categories.

Response Fields: category badge

A badge for each category about which guests talk particularly positively. This badge is generated for a category if a hotel is in the top 10 within its city for that category. These rankings are based on a mixture of the category score, and an extra factor, based on the intensity of positive sentiment that guests show when mentioning this category.

Fields Value Description
badge_data.rank Type: Integer The rank of the hotel in its city for this category.
badge_data.category_id Type: String The category id of the badge. Please refer to http://api.trustyou.com/hotels/categories for list of all categories.

GET /region/[REGION_ID]/zumata_hotels

Retrieves the ZUMATA hotel id’s associated with a region_id. To be used in conjunction with the autosuggest city_en_US type and hotel_list search endpoint.

Request URL

GET http://data.zumata.com/region/[REGION_ID]/zumata_hotels

GET /region/[REGION_ID]/zumata_hotels HTTP/1.1
Host: data.zumata.com

Request Parameters:

Parameter Required Value Description
REGION_ID Yes Type: String Specifies the region_id requested to search for hotel_ids.

Response Fields

Response body

["4PXS","fAkN","4yAU","XFQ9","4QJD","5CCH","j5IN","9BMx","po2m","W3kr","yhO0","jcgK","VLjS","NrwW","tMSf","uDcp","FllO","LdMR","Zyxz","NMoy","Ux5C","MUBs","bIUX","T9cE","qaXp","c0ya","Qim1","8dS6","YktO","atH8","hklH","REzZ","TYQR","cjT6","ze9Z","VF3U","8zvi","7uLH","S7zW","mLcW","Hwwg","1Z6R","WoMd","RdhW","SXXe","4iO3","dnhy","fM4D","KDao","FkVS","8pgC","lXJq","IqwD","zXRb","Ykfj","RU9i","y7XA","K5Rm","jzzR","8BCr","C22y","09uu","5Lcg","8Ycj","AfAE","c4Lp","CqJo","dhXv","eWQU","Ghq0","GqdP","jdQp","JKiJ","kl0V","kXQM","l5ok","NsWr","nZTZ","o8e2","ohkA","TFem","YwiE","ZuTP","ZYM4"]
Fields Value Description
[Array] of hotel id Type: Array List of hotel_id’s present in the region

GET /countries

Retrieves the ISO 3166 country codes and names.

Request URL

GET http://data.zumata.com/countries?[PARAMETERS]

GET /countries HTTP/1.1
Host: data.zumata.com

Request Parameters:

Parameter Required Value Description
lang No Type: String Control the language of the returned content.

Supported languages:

en_US

Response Fields

Response body

{  
   "AD":"Andorra",
   "AE":"United Arab Emirates",
   "AF":"Afghanistan",
   "AG":"Antigua and Barbuda",
   "AI":"Anguilla",
   "AL":"Albania",
   "AM":"Armenia",
   "AO":"Angola",
   "AQ":"Antarctica",
   ... [truncated for brevity]
}
Fields Value Description
country code Type: String The ISO 3166 country code.
country name Type: String Canonical country name.

GET /states/[COUNTRY]

Retrieves state codes and names for selected country (if available).

Request URL

GET http://data.zumata.com/states/[COUNTRY]?[PARAMETERS]

GET /states/CA HTTP/1.1
Host: data.zumata.com

Request Parameters:

Parameter Required Value Description
[COUNTRY] Yes Type: String ISO 3166 country code. The full list of countries is available here.
lang No Type: String Control the language of the returned content.

Supported languages:

en_US

Response Fields

Response body

{  
   "AB":"Alberta",
   "BC":"British Columbia",
   "MB":"Manitoba",
   "NB":"New Brunswick",
   "NL":"Newfoundland and Labrador",
   "NS":"Nova Scotia",
   "NT":"Northwest Territories",
   "NU":"Nunavut",
   "ON":"Ontario",
   "PE":"Prince Edward Island",
   "QC":"Quebec",
   "SK":"Saskatchewan",
   "YT":"Yukon"
}
Fields Value Description
state code Type: String The state code.
state name Type: String The state name.

Rate limits

Limits are placed on the number of api-v3.zumata.com Web service requests you may make using your API key.

Hourly Limit: 1,000 requests per hour Daily Limit: 10,000 requests per calendar day For each API key, these limits are applied across all api-v3.zumata.com Web services requests. Exceeding these limits will lead to your API key being temporarily blocked from making further requests. Depending on the limit exceeded, the block will be lifted automatically by waiting until the next hour or calendar day.

Rate Limit Time Periods

Hourly Limit

The hourly counters for your API key reset at the beginning of every hour.

Example: If you started making requests at 10:00AM and made your 1,000th request of the hour at 10:40AM, your API key would become temporarily blocked. This temporary block of your API key would be lifted at 11:00AM, at which point you could make more web service requests (assuming you hadn’t also exceeded your daily limit).

Daily Limit

The daily counters for your API key reset at midnight UTC.

Example: If you started making requests at 00:00:00 UTC and made your 10,000th request of the day at 16:00:00 UTC, your API key would become temporarily blocked. This temporary block of your API key would be lifted at 00:00:00 UTC of the following day, at which point you could make more web service requests.

Rate Limit Error Response

{
  "ID": "rate_limit",
  "Message": "Rate limit exceeded",
  "URL": "http://developer.zumata.com/"
}

If your API key exceeds the rate limits, you will receive a response with an HTTP status code of 503, Service Unavailable. The response body will contain an error message reading “503 Service Unavailable (Rate Limit Exceeded).” For example, a JSON request that has exceed the rate limits would respond with:

For more details on how errors are returned, see [error section].

Need Higher Limits? If you’re building an application that needs higher rate limits, we’d be happy to work with you. Contact us for more details.

Errors

Certain, general errors will be returned in a standardized way from all api-v3.zumata.com Web services. Additional, service-specific error messages may also be returned (see individual service documentation for those details). The following list describes the general errors any application may return.

Error message structure

Sample bad request error

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 157

{
  "id": "bad_request",
  "message": "check_in_date and/or check_out_date not present in search query params",
  "url": "http://developer.zumata.com/"
}

Standard HTTP error status code is returned to the response header in the event of an error. 4xx errors are usually request errors and 5xx errors are server errors.

The body structure of an error message includes a machine-readable error id, a human-readable error message, and a url pointing to further information about the error and how to resolve it.

Field Description
id Error id (e.g. bad_request, forbidden, not_found, server_error, supplier_error).
message Human-readable error message.
url The URL to the documentation page.

Error message structure: ID

HTTP Status Code ID Description
400 bad_request Some parameters passed to the endpoint is invalid. Check the API documentation.
401 invalid_api_key Invalid API Key. See authentication section.
403 forbidden Request failed because user does not have authorization to access a specific resource.
404 not_found The endpoint was not found, check the request URL. This also occurs when a specified entity for a request was not found.
422 unprocessable_entity The entity is in a state that doesn’t allow the operation.
500 server_error Something went wrong on the server, check status site and/or report the issue.
500 supplier_error Supplier error
503 Rate limit reached. See rate limits section

Application

We provide a desktop application for consuming the API where you can search, book, cancel…

download windows version (Windows 7 or newer)

download mac version (OSX 10.9 or newer)