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.
Please report any bugs to api@wego.com.
There're 4 main components that you'll most likely care about:
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.
Search
Allows you to start a hotel search and retrieve results. There are 2 kinds of searches: live search and historical search.
Hotel Details
Get details of a hotel, like its address, amenities, photos.
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:
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.
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.
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):
GET http://api.wego.com/hotels/api/search/new?location_id=7046&check_in=2011-08-15&check_out=2011-08-18
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.
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
Konata sees a hotel (The Westin Sydney, hotel_id 272921) that she likes and clicks to see more details of the hotel.
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.
Konata looks at the list of rates from different partners, and decides to pick the cheapest rate from cheapest-partner.com.
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:
GET http://api.wego.com/hotels/api/search/redirect/4819451?hotel_id=272921&room_rate_id=12
If the search done was a historical search, redirecting to a partner will not need a search_id (since it isn't available), but you can still redirect to a partner using the /hotels/api/search/redirect/direct API method:
GET http://api.wego.com/hotels/api/search/redirect/direct?hotel_id=272921&room_rate_id=12&check_in=20/02/2012&check_out=21/02/2012
Regardless of which API method was used, Konata will now be redirected to the partner's site so that she can continue her booking directly with them.
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.
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.
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"
}
count - The number of results returned.query - The query param sent to the APIlocations array:
id - ID of the location.name - A more descriptive name of the location that includes its country and state (if applicable) and the number of hotels.country_name - Full country namecountry_code - Two-letter country code (see ISO 3166-1 alpha-2 codes).state_name - The location's statestate_code - Three-letter state code Is a list of hotels returned from the search query.
id - The hotel idname - The full hotel namestars - Star rating of the hotel. This is a number from 0 to 5.rank - Hotel's rank (by popularity). The most popular hotel has a rank of 1.address - Address of the hotel.latitude - Latitude of the hotel.longitude - Longitude of the hotel.property_type - Type of property (e.g. is this a "hotel" or a "resort"?). Possible values:1 - Hotel2 - Hostel3 - Bed and Breakfast4 - Serviced Apartment5 - Resort6 - Villa7 - Motelbrand - ID of the brand of the hotel.recent_snippet - Recent snippetsatisfaction - Guest satisfaction score. This is a number from 0 to 5.url - The permalink of the hoteltotal_reviews - The number of total reviews.negative - Number of positive reviews this hotel has.positive - Number of positive reviews this hotel has.neutral - Number of neutral reviews this hotel has.map - Whether this hotel has longitude and latitude attributes.desc - Description of the hotel.searched - Indicates whether this was the hotel that was searched.image - An image url of the hotel.rooms_count - Total number of rooms in the hotel.room_rates_count - summary_room_rates - Summarizes the minimum room rate for each provider:id - Room rate IDcurrency_sym - Currency symbolprovider_name - Provider name. Example: Ratestogoprice_str - Price per room, per night.room_rate_min - Returns the minimum rate rate from the result set:
id - Room rate IDcurrency_sym - Currency symbolprovider_name - Provider name. Example: Ratestogoprice_str - Price per room, per night.offer - Any offers currently available in the hotel.
mm - Marketing messageid - The offer IDt - The titledirect_providers - A list of all the providers that can be directly redirected to (available only in historical search):
id - Room rate IDprovider_name - Provider name. Example: RatestogoThe 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:
longitude - Longitude location value of the hotel.latitude - Latitude location value of the hotel.postal_code - Postal code of the hotel.fax - Fax number of the hotel.reservation_phone - Reservation phone of the hotel.cancellation_policy -Cancellation policy of the hotel.videos - An array of video urls.images - An array of images of the hotel. url - url of the imagedescription - description of the imageproperty_amenities - An array of the hotels' property-level amenities. Each item in the array is the name of an amenity.room_amenities - An array of the hotels' room-level amenities. Each item in the array is the name of an amenity.concepts - An array of concepts for this hotel, each containing:
concept_id - ID of the concept. A concept ID is one of: 1 (overall), 2 (rooms), 3 (location), 4 (service), 5 (facilities), 6 (boutique), 7 (budget), 8 (business-friendly), 9 (family-friendly), 10 (food), 11 (hip), 12 (luxurious), 13 (modern), 14 (peaceful), 15 (pool), 16 (romantic), 17 (shopping), 18 (spa), 19 (traditional), 20 (value).score - The hotel's "score" for this concept. Score ranges from 0 to 5, with 0 meaning the hotel ranks poorly for this concept, and 5 meaning the hotel ranks strongly for this concept.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 error codes are:
location-not-found-error - Unrecognized location.ARG-required - The HTTP argument ARG is required for this request, e.g., check_in-required.network-error - A network error has occurred.unknown-error - An exceptional error that we didn't expect has occurred (we're human too). If you encounter this error, please let us know at api@wego.com.All API methods are HTTP GET requests and require API key-based authentication. The response data format is in JSON.
Search for a Wego Hotels location matching a query.
GET http://api.wego.com/hotels/api/locations/search?q=queryExample: http://api.wego.com/hotels/api/locations/search?q=sydney
Parameters:
q - required - The query (URL encoded).lang - Language of results. Possible values: en, zh-cn (Simplified Chinese), zh-hk (Traditional Chinese, Hong Kong), zh-tw (Traditional Chinese, Taiwan), ko (Korean). Defaults to en.page - Page of results to return. Use this together with per_page.per_page - Number of results to return per page. Use this together with page. Defaults to 10.callback - JSON-P callback function name.The response is a hash with the following key-values:
query - The query used.count - Number of locations in locations (see below).locations - Array of locations, sorted from most relevant to least relevant.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_outExample: http://api.wego.com/hotels/api/search/new?location_id=7046&check_in=2011-08-15&check_out=2011-08-18
Parameters:
location_id - required - The location ID of the location to search for. See /locations/search for details on getting the location ID.check_in - required - Check-in date in YYYYMMDD format.check_out - required - Check-out date in YYYYMMDD format.rooms - Number of hotel rooms required. Defaults to 1.guests - Number of guests staying. Defaults to 2.callback - JSON-P callback function name.ts_code - The ts_code used to track searches.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.
Retrieve results of a Wego Hotels search.
GET http://api.wego.com/hotels/api/search/search_id
Parameters:
search_id - required - ID of search for retrieving "live" prices together with the hotel. If not given, or if the search doesn't exist or has expired, the best seen prices in the last week are returned.refresh - Whether to refresh the results with any new results since the last request. This is useful when retrieving results page by page to prevent new results from changing the order of results by keeping the result set fixed. Possible values: true, false. Defaults to false.currency_code - Currency to display prices in - use ISO 4217 3-letter currency codes. Defaults to USD.sort - Determines how the results are sorted. Possible values: popularity (Wego Popularity Rank), name (hotel name), price, satisfaction (guest satisfaction score), stars (hotel star rating). Defaults to popularity.order - Sort order. Possible values: asc (ascending), desc (descending). Defaults to asc (this means the default sort order if neither sort nor order are provided is from most popular to least popular).page - Page of results to return. Use this together with per_page. Defaults to nil (which causes all results to be returned).per_page - Number of results to return per page. Use this together with page. Defaults to 10 if page is given, otherwise it's unused and all results are returned.lang - Language of results. Possible values: en, zh-cn (Simplified Chinese), zh-hk (Traditional Chinese, Hong Kong), zh-tw (Traditional Chinese, Taiwan), ko (Korean). Defaults to en.callback - JSON-P callback function name.In addition, the following additional parameters are supported for filtering the result set:
text_filter - Filters results to only hotels with hotel name or address matching the given string. E.g. http://api.wego.com/hotels/api/search/4835403?text_filter=rafflesstars[] - Filters results to only hotels with the given star rating(s). Note that this is an array of integers from 1 to 5. E.g. http://api.wego.com/hotels/api/search/4835403?stars[]=4&stars[]=5property_types[] - Filters results to only hotels of the given property type(s). Note that this is an array of integers representing property types. Possible values: 1 (hotel), 2 (hostel), 3 (bed and breakfast), 4 (apartment), 5 (resort), 6 (villa), 7 (motel). E.g. to get only hostels and resorts: http://api.wego.com/hotels/api/search/4835403?property_types[]=2&property_types[]=5amenities[] - Filters results to only hotels of the given key amenity ID(s). Note that this is an array of integers representing amenities. Possible values: 1 (Internet access), 2 (pool), 3 (parking), 4 (restaurant), 5 (fitness center/spa). E.g. http://api.wego.com/hotels/api/search/4835403?amenities[]=1&amenities[]=2satisfaction_min - Filters results to only hotels with a satisfaction score greater than or equal to the given score. Note that satisfaction is a float value from 0 to 5. E.g. http://api.wego.com/hotels/api/search/4835403?satisfaction_min=4.5district - Filters results to only hotels that are in the given district ID. E.g. http://api.wego.com/hotels/api/search/4835403?district=123price_min - Filters results to only hotels with at least 1 rate that's greater than or equal to the given price. The currency used is the currency that the results are in. E.g. http://api.wego.com/hotels/api/search/4835403?price_min=100price_max - Filters results to only hotels with at least 1 rate that's less than or equal to the given price. The currency used is the currency that the results are in. E.g. http://api.wego.com/hotels/api/search/4835403?price_max=200providers[] - Filters results to only return hotels with the specified providers. Note that this is an array of provider codes. You can retrieve the provider codes using the Providers API: http://api.wego.com/hotels/api/providers http://api.wego.com/hotels/api/search/4835403?providers[]=agoda.com&providers[]=booking.com&providers[]=hrs.comex_providers[] - Filters results to not return hotels with the specified providers. Note that this is an array of provider codes. You can retrieve the provider codes using the Providers API: http://api.wego.com/hotels/api/providers http://api.wego.com/hotels/api/search/4835403?ex_providers[]=agoda.com&ex_providers[]=booking.com&ex_providers[]=hrs.comThe response is a hash with the following key-values:
fetched_rates_count - The total number of live room rates that are fetched.fetched_hotels_count - The total number of hotels that are fetched every time the search is run.count - Number of hotels in hotels (see below).per_page - The total number of hotels returned per page.current_page - The page this search is returning.total_count - Total number of hotels seen so far in this search.filtered_count - This count represents the total number of hotels that satisfy any filters. For example, if a filter for "5-star hotels only" is applied, filtered_count would return the number of 5-star hotels.hotels - Array of hotel results, sorted from least expensive to most expensive.Retrieve results of a Wego Hotels historical search.
GET http://api.wego.com/hotels/api/search/historical?location_id=location_idExample: http://api.wego.com/hotels/api/search/historical?location_id=866
Parameters:
location_id - required - The location ID of the location to search for. See /locations/search for details on getting the location ID.currency_code - Currency to display prices in - use ISO 4217 3-letter currency codes. Defaults to USD.sort - Determines how the results are sorted. Possible values: popularity (Wego Popularity Rank), name (hotel name), price, satisfaction (guest satisfaction score), stars (hotel star rating). Defaults to popularity.order - Sort order. Possible values: asc (ascending), desc (descending). Defaults to asc (this means the default sort order if neither sort nor order are provided is from most popular to least popular).page - Page of results to return. Defaults to 1.
per_page - Number of results to return per page. Defaults to 20.
lang - Language of results. Possible values: en, zh-cn (Simplified Chinese), zh-hk (Traditional Chinese, Hong Kong), zh-tw (Traditional Chinese, Taiwan), ko (Korean). Defaults to en.callback - JSON-P callback function name.In addition, the following additional parameters are supported for filtering the result set:
text_filter - Filters results to only hotels with hotel name or address matching the given string. E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&text_filter=spastars[] - Filters results to only hotels with the given star rating(s). Note that this is an array of integers from 1 to 5. E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&stars[]=4&stars[]=5property_types[] - Filters results to only hotels of the given property type(s). Note that this is an array of integers representing property types. Possible values: 1 (hotel), 2 (hostel), 3 (bed and breakfast), 4 (apartment), 5 (resort), 6 (villa), 7 (motel). E.g. to get only hostels and resorts: http://api.wego.com/hotels/api/search/historical?location_id=866&property_types[]=2&property_types[]=5amenities[] - Filters results to only hotels of the given key amenity ID(s). Note that this is an array of integers representing amenities. Possible values: 1 (Internet access), 2 (pool), 3 (parking), 4 (restaurant), 5 (fitness center/spa). E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&amenities[]=1&amenities[]=2satisfaction_min - Filters results to only hotels with a satisfaction score greater than or equal to the given score. Note that satisfaction is a float value from 0 to 5. E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&satisfaction_min=4.5district - Filters results to only hotels that are in the given district ID. E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&district=123price_min - Filters results to only hotels with at least 1 rate that's greater than or equal to the given price. The currency used is the currency that the results are in. E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&price_min=100price_max - Filters results to only hotels with at least 1 rate that's less than or equal to the given price. The currency used is the currency that the results are in. E.g. http://api.wego.com/hotels/api/search/historical?location_id=866&price_max=200The response is a hash with the following key-values:
count - Number of hotels in hotels (see below).per_page - The total number of hotels returned per page.current_page - The page this search is returning.filtered_count - This count represents the total number of hotels that satisfy any filters. For example, if a filter for "5-star hotels only" is applied, filtered_count would return the number of 5-star hotels.hotels - Array of hotel results, sorted from least expensive to most expensive.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_idExample: http://api.wego.com/hotels/api/search/show/4820672?hotel_id=8012
Parameters:
search_id - required - ID of search for retrieving "live" prices together with the hotel. If not given, or if the search doesn't exist or has expired, the best seen prices in the last week are returned.hotel_id - required - ID of the hotel.currency - Currency to display prices in - use ISO 4217 3-letter currency codes. Defaults to USD.lang - Language of results. Possible values: en, zh-cn (Simplified Chinese), zh-hk (Traditional Chinese, Hong Kong), zh-tw (Traditional Chinese, Taiwan), ko (Korean). Defaults to en.callback - JSON-P callback function name.The response is a hotel.
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_idExample: http://api.wego.com/hotels/api/search/show/historical?hotel_id=8012
Parameters:
hotel_id - required - ID of the hotel.currency - Currency to display prices in - use ISO 4217 3-letter currency codes. Defaults to USD.lang - Language of results. Possible values: en, zh-cn (Simplified Chinese), zh-hk (Traditional Chinese, Hong Kong), zh-tw (Traditional Chinese, Taiwan), ko (Korean). Defaults to en.render - Format of the response. Useful if you are only interested in a certain portion of the details. Currently only supports the value direct_providers, which will only return the direct_providers element.callback - JSON-P callback function name.The response is a hotel.
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_idExample: http://api.wego.com/hotels/api/search/redirect/4820672?hotel_id=8012&room_rate_id=1
Parameters:
search_id - required - ID of search for retrieving "live" prices together with the hotel. If not given, or if the search doesn't exist or has expired, the best seen prices in the last week are returned.hotel_id - required - The ID of the hotel in the search resultsroom_rate_id - required - The room rate id in the search resultsts_code - The ts_code used to track clicksGet a page that redirects to one of our partners' sites from one of the rates in a historical 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/direct?hotel_id=hotel_id&room_rate_id=room_rate_id&check_in=check_in&check_out=check_out
Parameters:
hotel_id - required - The ID of the hotel in the search resultsroom_rate_id - required - The room rate id in the search resultscheck_in - The check-in date. Must be in dd/mm/yyyy format. If not provided, defaults to 7 days from current datecheck_out - The check-out date. Must be in dd/mm/yyyy format. If not provided, defaults to 8 days from current datets_code - The ts_code used to track clicks