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.

Warning

This method is only accessible using a multi-property (Source or Travel Agent) API account.

Table of Contents
  1. URL Endpoint
  2. Method Parameters
  3. Error Handling
  4. Usage
  5. JSON Response Schema
  6. JSON Response Example

URL Endpoint

/availability

Method Parameters

Basic parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
checkin date (ISO 8601) from today
to (today + 3 years)
YES &checkin=2024-02-29  
checkout date (ISO 8601) from (checkin + 1)
to (checkin + 30)
NO* checkin + 1 day &checkout=2024-03-07 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.


Filters

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

Geolocation

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 &region=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.


Output settings

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.

Advanced parameters

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.


Error handling

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

Usage

Integration

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.

Form Fields

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.

Location & Geocoding

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.

Booking URLs

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.

Special Offers

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.

Property & Rate Photos

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

Sorting

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.

Paging

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.

JSON Response Schema

{
  "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-02-29"
    },
    {
      "type": "URL",
      "name": "checkout",
      "value": "2024-03-07"
    },
    {
      "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
              }
            ]
          }
        ]
      }
    ]
  }
}
  

JSON Response Example