Multi-property availability search method returns a list of available properties. Each result includes the minimum price, distance and sub-result with the pricing of each room rate available. Some additional information is provided, like the currency, property and room photos, etc.
This method is only accessible using a multi-property (Source or Travel Agent) API account.
/availability
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| checkin | date (ISO 8601) | from today to (today + 3 years) |
YES | – | &checkin=2024-11-05 | |
| checkout | date (ISO 8601) |
from (checkin + 1) to (checkin + 30) |
NO* | checkin + 1 day | &checkout=2024-11-12 | When used, number of nights is automatically calculated. Limitations apply (see nights). |
| nights | integer | 1 – 30 | NO* | 1 | &nights=2 | |
| adults | integer | 1 – max capacity | NO | 2 | &adults=2 | The value is PER ROOM. Maximum value is automatically calculated based on the property's maximum possible room capacity. |
| children | integer | 0 – (max capacity-1) | NO | 0 | &children=1 | The value is PER ROOM. Maximum value equals (maximum capacity - 1). |
| infants | integer | 0 – (max capacity-1) | NO | 0 | &infants=1 | The value is PER ROOM. Maximum value equals (maximum capacity - 1). |
| rooms | integer | 1 – 5 | NO | 1 | &rooms=2 | |
| party | JSON string | NO** | - |
One room: &party=[{"adults": 2}] Two rooms with mixed occupancies: &party=[{"adults":2, "children":[2,6]},{"adults":3}] |
Array of JSON objects representing number of adults and children. "adults": (REQUIRED - integer) The number of adults staying in the room. "children": (OPTIONAL - array of integers) The ages of any children staying in the room. |
* Use either checkout or nights, never both. checkout parameter takes precedence if both present.
** Use either party or rooms + adults + children + infants, never both. party parameter takes precedence if both present.
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| name | string | varchar(255) | NO | – | &name=Cavo%20Tagoo | Property name. Supports substring search e.g. name=Cavo |
| properties | string | varchar(4000) | NO* | – | &properties=HOTELCODEA,HOTELCODEB | A list of property codes |
| rating | integer | 1 – 5 | NO | – | &rating=5 &rating=3,4,5 |
New! Filters result based on rating (stars, diamonds, etc) |
| board | integer | 1 – 23 | NO | – | &board=19 &board=3,19,21 |
New! Returns properties that have rates with specified board type, includes only those rates in the result |
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| location | string | varchar(255) | NO* | – | &location=Athens |
Any location text will be recognized and geolocation will be performed. Quota limits apply |
| lat | decimal(18,15) | -90.0 – 90.0 | NO* | – | &lat=37.9404933&lon=23.7138433 |
Latitude / Longitude in decimal degrees. Radius Mode (REQUIRED): Location to search from when using radius search. Bounding Box Mode (OPTIONAL): Central point (distances will be calculated from this) on bounding box searches. |
| lon | decimal(18,15) | -180.0 – 180.0 | ||||
| radius | double | 1-100 | NO† | 1 | &radius=5 | Value in kilometers. |
| lat1 | decimal(18,15) | -90.0 – 90.0 | NO‡ | – | &lat1=37.0&lon1=23.0 |
Latitude / Longitude in decimal degrees. Bottom left corner (southwest) on bounding box searches. |
| lon1 | decimal(18,15) | -180.0 – 180.0 | ||||
| lat2 | decimal(18,15) | -90.0 – 90.0 | NO‡ | – | &lat2=38.0&lon2=24.0 |
Latitude / Longitude in decimal degrees. Top right corner (northeast) on bounding box searches. |
| lon2 | decimal(18,15) | -180.0 – 180.0 | ||||
| region | string | ISO 3166-1-alpha-2 | NO | GR | ®ion=GB | Specifies geocoding region bias. Default value is subject to change |
If your API account is not restricted to a set of properties, one of properties, location, and coordinate parameters are REQUIRED.
* Parameters properties, location, and coordinate parameters are mutually exclusive:
a) When using the properties parameter, location and coordinate parameters will be ignored.
b)
When using the location parameter, coordinate parameters will be ignored. If you expect hundreds or thousands
of unique queries per day, please consider using your own geolocation solution (server or client-side) and search
using coordinates directly.
c) You can search in a radius from a center point or use a bounding box.
† If you search from a center point, the radius parameter is REQUIRED (in Km).
‡ When performing bounding box search, you can also pass the lat, lon parameters. The coordinates will not be used for geolocation but they will be used to calculate distances. For example, you can pass the coordinates of a city's center and all distances will be calculated and sorted from that point. If omitted, the center of the bounding box will be automatically used for distances.
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| sort_by | string | DISTANCE NAME POPULARITY PRICE |
NO | PRICE | &sort_by=POPULARITY | |
| sort_order | string | ASC DESC |
NO | ASC | &sort_order=DESC | Default sort order is DESC when sort_by=POPULARITY |
| max_properties | integer | 1 – ∞ | NO | ∞ | &max_properties=10 | Maximum properties to return. A value of 50 or lower is recommended |
| max_rates | integer | 1 – ∞ | NO | ∞ | &max_rates=3 | Maximum rates per property to return. A value of 3 or lower is recommended |
| max_room_rates | integer | 1 – ∞ | NO | ∞ | &max_room_rates=1 |
Maximum rates per room type to return. A value of 1 is recommended. Can be combined with the max_rates parameter |
| no_policies | boolean | NO | – | &no_policies | Do not include rate policies on response (use this when searching many rates/properties) | |
| include_noavl | boolean | NO | false | &include_noavl |
Returns all properties even when no available rates are found. NOTE: Only works for source-bound API accounts |
|
| payments | boolean | NO | false | &payments=1 | Returns payments & cancellation_fees fields. |
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| remote_country | string | ISO 3166-1-alpha-2 | NO* | – | &remote_country=US |
Specifies remote user's country. Use ip address geolocation. Required for working with markets. |
| remote_ip | string | Dot-decimal notation | NO* | – | &remote_ip=94.71.170.105 |
Specifies remote user's ip address. Alternative to country. Required for working with markets. Only IPv4 supported. |
| device | string | MOBILE DESKTOP |
NO* | – | &device=MOBILE |
Specified user device. Used to unlock special pricing policies. |
| bk_code | string | varchar(255) | NO | – | &bk_code=SPECIALRATES | Returns private rates that are enabled by specified booking code |
| voucher | string | varchar(255) | NO | – | &voucher=VCH123 | Unlocks special offers |
* You can use remote_country or remote_ip. If you use both, remote_country takes precedence and remote_ip is ignored.
HTTP Response Status Code is 200 on all successful responses in json and xml formats. Other possible status codes are described on the table below:
| STATUS CODE | CONDITION |
|---|---|
| 200 | Successful request. |
| 403 | Invalid HTTP Method, Invalid Credentials, Quota limits exceeded, Unencrypted connection, etc. |
| 503 | Unknown error or temporary unavailability |
| 500 | All other invalid requests or responses. Described by error_code |
A sample error response can be seen below. The nature of the error encountered is described by error_code and error_msg in human-readable format, while http_code will always reflect the HTTP Response Status Code.
<?xml version="1.0" encoding="UTF-8"?>
<response>
<method>https://rest.reserve-online.net/availability</method>
<http_method>GET</http_method>
<http_code>500</http_code>
<error_code>INVALID_PARAM</error_code>
<error_msg>Missing location parameters.</error_msg>
<arguments>
<param name="sort_by" type="URL">POPULARITY</param>
<param name="checkout" type="URL">2010-05-04</param>
<param name="adults" type="URL">2</param>
<param name="rooms" type="URL">1</param>
<param name="checkin" type="URL">2010-05-03</param>
<param name="children" type="URL">0</param>
</arguments>
<data/>
</response>
The possible error_codes returned by this method are described on the table below. The consumer service should be able to gracefully respond to these errors by inspecting the code. Notice: error_msgs are subject to change and should not be used in your error handling code.
| ERROR_CODE | HTTP_CODE | DESCRIPTION |
|---|---|---|
| OK | 200 | The request completed successfully. |
| NO_HOTELS_FOUND | 200 | No properties found in specified location. |
| NO_AVAILABILITY | 200 | No available rooms found to satisfy your query. |
| INTERNAL_ERROR | 500 | Internal service error. This is usually a bug in our code and we will be notified immediately. |
| FORBIDDEN | 403 | The credentials are invalid. |
| INVALID_RESPONSE_TYPE | 403 | The response type is not supported (e.g. when requesting json when only xml is supported). |
| INVALID_METHOD | 403 | Method requested is not supported (e.g. POST is not supported, use GET). |
| NO_AUTH | 403 | No authentication header found. |
| INVALID_AUTH | 403 | Invalid username or password. |
| INVALID_PARAM | 500 | When missing or invalid request parameters are passed. Check the error_msg for details. |
| GEO_INVALID_REQUEST | 500 | The location parameter is invalid (returned by our Geocoding provider). |
| GEO_OVER_QUOTA | 500 | You cannot make any more location queries (returned by our Geocoding provider). |
| GEO_NO_RESULTS | 500 | Location not found (returned by our Geocoding provider). |
The author should provide an availability form for the clients using the service and all user-defined fields like: check in date, check out date OR number of nights, number of rooms, number of adults and children staying and a location field. Posting the form should result in a server-side request that will call this web service and, after it receives the result, display the formatted HTML output to the user. The result can be displayed in a separate page or in the same page if it is an AJAX request.
It is recommended that Date form fields should use a date picker widget in order to provide a user-friendly experience. A free and open-source datepicker is included with JQuery UI and can be easily integrated.
Numeric parameters should be select box fields. Note that not all fields are required (e.g. rooms) and can be safely omitted.
The location field can be passed as a parameter to the web service and the service will perform server-side geocoding for you. Although this is the simplest and easier way to integrate this, it is NOT recommended. The Geocoding provider used by our service has quotas on the number of requests per day and the service does not guarantee that a geocoding query will be successful. If you wish to bias the geocoding results for a specific country, you can use the region parameter. For example, if you wish for "Zante" to mean Zante, CA, USA, you need to pass region=US.
If you expect heavy use of your service, it is HIGHLY RECOMMENDED to implement client-side geocoding with Javascript. The way the quota works is by IP address. If you put the geocoder in your JavaScript code, it's rendering in the browser and therefore counts against the IP address quota of the browser, not your site. After retrieving the geocoding results, you can submit coordinates instead of the location string and this will result in a much faster response by the service because no roundtrip between us and our geo provider will occur.
Searching for availability with coordinates has two modes. The first accepts a single coordinate set and a radius value (in kilometers). The second method accepts two sets of coordinates, the south-west point and the north-east point of a geographic region. The second method is used internally when only a location string is submitted.
Searching with coordinates allows for some interesting client-side applications, like providing the user with the option to manually select a location on a map and select a radius of search. That way, no geocoding is necessary. Careful not to allow for radius greater than 100, it will result in an error.
Feel free to include a map in your results page with pins at the location of each property in the result set. A set of coordinates is returned for each property and it is recommended that you include a map to pinpoint its location.
The availability process returns multiple booking URLs (bookurl) for each property. The primary booking URL redirects to the property's booking engine page and automatically performs availability for the requested dates. If you use the booking URLs returned for each rate, then the same availability request is performed but the chosen rate is displayed first followed by the rest of the available rates in a separate result table. You can append the &direct parameter on each rate's booking URL to automatically select and display the payment form for the rate.
The availability process performs dynamic pricing operations on the rate. This may result in different rate pricing which is usually part of a special offer that is applicable for the requested period. The service, provides a special field for each rate that can used to identify if a special offer has been applied and what was the reduction in price. The discount field can be used to calculate the original price (if discount > 0.00) and display a message to the client that the rate is part of a special offer.
For each property and for each rate the url of the primary photo is returned. The photo can be used in your availability result either directly or by downloading it and caching it on your server. It is safe to cache the photo until the url is changed since everytime the hotelier uploads a new photo for the property or for a particular room type a new photo ID is generated. If you detect that a different photo url is returned, it means that it's time to invalidate your cache. The dimensions of the photos are always 90×60. A different method can be used to download more photos and dimensions (see Property Search & Information methods in WebHotelier's API directory).
By default, the results are sorted by price, the property that has the rate with the lowest price is always displayed first. It is recommended for best results that the author uses sort by POPULARITY, with this kind of sort the properties that are more probable to result in a client conversion will be displayed first.
It is also recommended that the author should provide a setting for the sort type and allow the client to select the order in which to display the results.
If the returned result contains more that 20 properties, it is recommended to break the result to multiple pages. If you choose to do this, it is HIGHLY RECOMMENDED to cache the result so no subsequent requests are required when the user selects another page.
{
"method": "http://rest.reserve-online.net/availability",
"http_method": "GET",
"http_code": 200,
"error_code": "OK",
"error_msg": "",
"params": [
{
"type": "URL",
"name": "checkin",
"value": "2024-11-05"
},
{
"type": "URL",
"name": "checkout",
"value": "2024-11-12"
},
{
"type": "URL",
"name": "location",
"value": "Santorini"
}
],
"data": {
"hotels": [
{
"code":STRING, // Property code
"name":STRING, // Property name
"url":URL, // Property website url (empty if not defined)
"rating":INTEGER, // Property rating (empty if not defined)
"currency":ISO 4217, // Property default currency code
"avlurl":URL,// API URL for single-property availability request
"infourl":URL,// API URL for property info request
"bookurl":URL, // Property booking engine url (empty if not defined)
"minprice":MONEY, // Property minimum room price (optional, exists only when defined)
"photo":URL, // Property photo url - Small size (empty if not defined)
"photoM":URL, // Property photo url - Medium size (empty if not defined)
"photoL":URL // Property photo url - Large size (empty if not defined)
"distance":DECIMAL, // Distance of property from the requested location in km
"location": {
"lat":DECIMAL, // Property geo location latitude (empty if not defined)
"lon":DECIMAL, // Property geo location longitude (empty if not defined)
"name":STRING, // Property location name (empty if not defined)
},
"type":STRING, // Property type (empty if not defined)
"rates": [ // List of property rates
{
"id":INTEGER, // Rate id
"type":STRING, // Rate room code (each rate belongs to only one room)
"board":INTEGER // Board ID (empty if not defined). See Board Types
"url":URL, // Booking engine availability url with the specified parameters
"room":STRING, // Rate room name
"roomurl":URL, // API URL for room info request
"remaining":INTEGER, // Remaining available rooms
"rate":STRING, // Rate name
"rate_desc":STRING, // Rate short description
"photo":URL, // Room photo url - Small size
"photoM":URL, // Room photo url - Medium size
"photoL":URL, // Room photo url - Large size
"stay":MONEY, // Room price (exclusive of extras and taxes)
"extras":MONEY, // Extras amount
"taxes":MONEY, // Taxes amount
"excluded_charges":MONEY, // Excluded charges amount
"price":MONEY, // Total rate price. This is the final price in case of booking.
"retail":MONEY, // Retail room price (appears only for TA/CORP accounts)
"discount":MONEY, // Discount amount
"margin":MONEY, // Difference between retail and NET price (appears only in TA/CORP accounts)
"payment_policy":STRING, // Payment policy description
"payment_policy_id":INTEGER, // Payment policy id (for internal use)
"cancellation_policy":STRING, // Cancellation policy description
"cancellation_policy_id":INTEGER, // Cancellation policy id (for internal use)
"cancellation_penalty":STRING, // Cancellation penalty description
"cancellation_expiry":ISO 8601, // Free cancellation expiry date timestamp (empty if no free cancellation is set)
"payments": [(Appears only for payments=1)
{
"due":ISO 8601, // Payment due date
"amount":MONEY // Amount to be paid until the above date
}
],
"cancellation_fees": [(Appears only for payments=1)
{
"after":ISO 8601, // Cancellation fee is applied if the reservation is cancelled after this date
"fee":MONEY // Cancellation fee amount that applies after the above date
}
],
"labels": [ // Optional. Exists only if labels are defined for the rate.
{
"code":STRING, // Enumerated value. See Rate Labels. More new values may be added at any time.
"title":STRING // Simple label description
}
]
}
]
}
]
}
}
