Wego Hotels API v3 documentation

The Wego Hotels API allows developers to interact with the Hotels product of Wego.com programmatically via HTTP requests. All API methods are HTTP requests and responses are in JSON format unless otherwise stated.

To register for API access, you can sign up on WegoAffiliateNetwork.com and check the API box. One of our sales executives will then get in touch with you. Alternatively, you can send an email to affiliates.support@wego.com expressing your interest.

Please report any bugs to api@wego.com.

Table of Contents

Core Concepts

What can you do with the API?

There're 4 main components that you'll most likely care about:

  1. Locations
    Use this to map user location queries to Wego location IDs. E.g. you will probably provide your users with a text field for entering the location when searching for hotels. The Locations API allows you to lookup text queries like "sydney" to get a list of matching locations and their IDs.

  2. Search
    Allows you to start a hotel search and retrieve results. There are 2 kinds of searches: live search and historical search.

  3. Hotel Details
    Get details of a hotel, like its address, amenities, photos.

  4. Booking a room with our partners
    Taking users to continue the booking process for a room at one of our partners' sites.

The typical use case of a user searching for hotels would involve:

  1. A user, let's call her Konata, is looking for hotels in Sydney. She types in "sydney" into a text field on your search form.

  2. You send a Locations API /hotels/api/locations/search request to lookup the location ID of "Sydney":

    GET http://api.wego.com/hotels/api/locations/search?q=sydney

    The API responds (in JSON format) with:

                {
                    "count": 3,
                    "locations": [{
                        "name": "Sydney, NSW, Australia - 795 hotels",
                        "country_name": "Australia",
                        "country_code": "AU",
                        "state_name": "New South Wales",
                        "id": 7046,
                        "state_code": "NSW"
                    },
                    {
                        "name": "Sydney, Canada - 53 hotels",
                        "country_name": "Canada",
                        "country_code": "CA",
                        "state_name": null,
                        "id": 8564,
                        "state_code": null
                    },
                    {
                        "name": "North Sydney, SK, Canada - 2 hotels",
                        "country_name": "Canada",
                        "country_code": "CA",
                        "state_name": "Saskatchewan",
                        "id": 18410,
                        "state_code": "SK"
                    }],
                    "query": "sydney"
                }
              

    This means there are 3 locations that match "sydney", id 7046 in Australia, id 8564 in Canada and id 18410 in Saskatchewan, Canada. You'll have to either present Konata with the 3 locations and ask her to pick the one she meant, or pick one for her (not recommended).

    On Wego.com, we use an autosuggest widget to present users with matching locations.

  3. Konata picks Sydney in Australia - she had no idea there was a Sydney in Canada!
  4. You can now perform a search. There are 2 types of searches you can perform: live and historical. A live search will perform a real-time search on Wego's partners' sites for rates in a given location and date range. A historical search will return recently seen rates for a given location and does not require a date range to return search results.

    When doing a historical search, you send a Historical Search API /hotels/api/search/historical request to search for hotels in Sydney (location ID 7046):

    GET http://api.wego.com/hotels/api/search/historical?location_id=7046

    The API responds with a list of hotel search results. Proceed to step 8 for the next step when doing a historical search.

    When doing a live search, you send a Search API /hotels/api/search/new request to start a search for hotels in Sydney (location ID 7046), including your user's IP address and your ts_code in the query:

    GET http://api.wego.com/hotels/api/search/new?location_id=7046&check_in=2011-08-15&check_out=2011-08-18&user_ip=61.8.64.0&ts_code=abc01

    (Your ts_code is a unique identifier that we issue to you when you register for API access. We use it to attribute searches and referral clicks to your account.)

    The API responds with:

    {
      "search_id": 4819451
    }

    You can use the search_id to fetch search results with the /hotels/api/search/search_id API method.

  5. Konata is shown a page where results from the /hotels/api/search/search_id method are displayed.

    It's best to wait at least 10 seconds after starting the search, (it's good practice to keep the user distracted by telling her that her search is in progress), and then requesting and showing her the set of all results from the /hotels/api/search/search_id API method:

    GET http://api.wego.com/hotels/api/search/4819451

  6. Konata sees a hotel (The Westin Sydney, hotel_id 272921) that she likes and clicks to see more details of the hotel.

  7. You send a Hotel Details API /hotels/api/search/show/search_id?hotel_id=hotel_id request to retrieve the details of The Westin Sydney:

    GET http://api.wego.com/hotels/api/search/show/4819451?hotel_id=272921

    The API responds with the hotel details which you can use to construct the hotel details page.

  8. Konata looks at the list of rates from different partners, and decides to pick the cheapest rate from cheapest-partner.com.

  9. You lookup the id for the rate (12) and use the /hotels/api/search/redirect/search_id API method to redirect the user to cheapest-partner.com's site (including your ts_code in the query):

    GET http://api.wego.com/hotels/api/search/redirect/4819451?hotel_id=272921&room_rate_id=12&ts_code=abc01

    If the search done was a historical search, redirecting to a partner will not need a search_id (since it isn't available).

Authentication / Rate-limiting

All API requests require you to authenticate with your API key (given to you by Wego). Always pass along the api_key parameter in your API requests, e.g.

GET http://api.wego.com/hotels/api/search/new?api_key=12345abcdef&location_id=6667

Your API key is used to track usage and to limit the number of API requests you can make (for some API methods). The API rate limits have not been decided at this time.

Live Search vs Historical Search

Wego provides 2 ways of searching for hotel rates: live search and historical search. Live search will return "live" rates, i.e. the latest prices for a room of a hotel as indicated by a partner. Historical searches, on the other hand, will not search partner sites for rates but will instead return the best rates returned from past live searches. These "historical" rates can be anything from 1 to 7 days old, and may also no longer be available on the partner's site.

In terms of API usage, live search API methods require polling to retrieve all the search results. Historical searches will return search results immediately.

In general, live searches are the way to go if the user knows which dates they will be travelling on, while historical searches are great if the user is just browsing for hotels with no specific dates in mind.

Response types

Location

The location type represents a location in the Wego Hotels location database.

A sample location response in JSON looks like:

{
          "count": 3,
          "locations": [{
              "name": "Sydney, NSW, Australia - 795 hotels",
              "country_name": "Australia",
              "country_code": "AU",
              "state_name": "New South Wales",
              "id": 7046,
              "state_code": "NSW"
          },
          {
              "name": "Sydney, Canada - 53 hotels",
              "country_name": "Canada",
              "country_code": "CA",
              "state_name": null,
              "id": 8564,
              "state_code": null
          },
          {
              "name": "North Sydney, SK, Canada - 2 hotels",
              "country_name": "Canada",
              "country_code": "CA",
              "state_name": "Saskatchewan",
              "id": 18410,
              "state_code": "SK"
          }],
          "query": "sydney"
      }

Hotel Results

Is a list of hotels returned from the search query.

Hotel

The hotel type represents a hotel in the Wego Hotels database.

It has all the attributes of the hotel hash in the hotel results response and these additional attributes:

Errors

The API returns appropriate HTTP status codes. In addition, the API also includes error information in the response body. Error responses have a single error property that is a string describing the error, e.g.:

{ "error": "forbidden" }

An additional details property is sometimes available for further diagnostics.

Possible errors are:

API Methods

All API methods are HTTP GET requests and require API key-based authentication. The response data format is in JSON.

Request Description Example
/hotels/api/locations/search Search for a Wego Hotels location http://api.wego.com/hotels/api/locations/search?q=sydney
/hotels/api/search/new Start a new hotel search http://api.wego.com/hotels/api/search/new?location_id=7046&check_in=2011-08-15&check_out=2011-08-18&user_ip=61.8.64.0&ts_code=abc01
/hotels/api/search/search_id Get results of a search http://api.wego.com/hotels/api/search/12345
/hotels/api/search/historical Perform a historical search http://api.wego.com/hotels/api/search/historical?location_id=7046
/hotels/api/search/show/search_id Get details of a hotel from a search http://api.wego.com/hotels/api/search/show/45678?hotel_id=12345
/hotels/api/search/show/historical Get details of a hotel without performing a live search http://api.wego.com/hotels/api/search/show/historical?hotel_id=12345
/hotels/api/search/redirect/search_id Redirect to our partner's site from a live rate http://api.wego.com/hotels/api/search/redirect/45678?hotel_id=12345&room_rate_id=1&ts_code=abc01

Search for a Wego Hotels location matching a query.

GET http://api.wego.com/hotels/api/locations/search?q=query

Example: http://api.wego.com/hotels/api/locations/search?q=sydney

Parameters:

The response is a hash with the following key-values:

/hotels/api/search/new - Start a new hotel search

Start a new Wego Hotels search.

GET http://api.wego.com/hotels/api/search/new?location_id=location_id&check_in=check_in&check_out=check_out&user_ip=user_ip&ts_code=ts_code

Example: http://api.wego.com/hotels/api/search/new?location_id=7046&check_in=2011-08-15&check_out=2011-08-18&user_ip=61.8.64.0&ts_code=abc01

Parameters:

The response is a search_id that is a unique ID for the search. E.g.:

{
  "search_id": "4820672"
}

Use the search_id in the /hotels/api/search/search_id API method to get the results of the search.

/hotels/api/search/search_id - Get results of a search

Retrieve results of a Wego Hotels search.

GET http://api.wego.com/hotels/api/search/search_id

Example: http://api.wego.com/hotels/api/search/4820672

Parameters:

In addition, the following additional parameters are supported for filtering the result set:

The response is a hash with the following key-values:

Retrieve results of a Wego Hotels historical search.

GET http://api.wego.com/hotels/api/search/historical?location_id=location_id

Example: http://api.wego.com/hotels/api/search/historical?location_id=866

Parameters:

In addition, the following additional parameters are supported for filtering the result set:

The response is a hash with the following key-values:

/hotels/api/search/show/search_id - Get details of a hotel (live search)

Retrieve details of a hotel from a live search given its ID.

GET http://api.wego.com/hotels/api/search/show/search_id?hotel_id=hotel_id

Example: http://api.wego.com/hotels/api/search/show/4820672?hotel_id=8012

Parameters:

The response is a hotel.

/hotels/api/search/show/historical - Get details of a hotel (historical search)

Retrieve details of a hotel given its ID. This method is similar to /hotels/api/search/show/search_id but does not require a search_id.

GET http://api.wego.com/hotels/api/search/show/historical?hotel_id=hotel_id

Example: http://api.wego.com/hotels/api/search/show/historical?hotel_id=8012

Parameters:

The response is a hotel.

/hotels/api/search/redirect - Redirect to partners' sites from a live rate

Get a page that redirects to one of our partners' sites from one of the rates in a live search. The response is an HTML page that redirects to one of our partners' sites, not JSON.

GET http://api.wego.com/hotels/api/search/redirect/search_id?hotel_id=hotel_id&room_rate_id=room_rate_id&ts_code=ts_code

Example: http://api.wego.com/hotels/api/search/redirect/4820672?hotel_id=8012&room_rate_id=1&ts_code=abc01

Parameters: