Booking Interface

There are 2 environments for the XML service, development and live. You will be granted access to the development system at first until everything is tested. Then, you will be given access to the live system to start putting bookings through. Both the interactive portal and all XML requests require your login details.

All mapping files and property detail files are available via the interactive portal.

Development

Service URL: https://xmldev-xml.xml.world/

Interactive Portal: https://xmldev-xml.xml.world/portal.php

Live

Service URL: https://xml.xml.world/

Interactive Portal: https://xml.xml.world/portal.php

You will require various ID’s to use the XML functionality: PropertyIDs, MealBasisIDs, etc. You can find complete up-to -date lists through the interactive portal. The lists can be electronically scraped.

If new Properties are added, the new ID and information will be available here. Please do not contact the supplier or Experience Engine for this.

Example URL:

https://xml.xml.world/portal.php?action=exportPropertyIDs

We provide data in CSV and JSON formats. We highly recommend using the JSON format as it can contain extended data such as a full list of available images. The equivalent static data files have JSON on the end. Example:

https://xml.xml.world/portal.php?action=exportPropertyIDsJSON

Please be aware that we may add fields as necessary. Where suitable, we will add to the end of the CSV file, but we highly recommend associating the headers with the data to prevent issues when importing.

Each and every data parameter in the API is characterised as one of the following types. Please adhere to these specifications for all data submitted in requests.

• String: Character data. To avoid errors, please remember to either escape XML syntactically-significant characters (e.g. ‘>’ → ‘>’) or to encapsulate as CDATA. Must use UTF-8 encoding.
• String Enum: As per String data, but restricted to only the given set of values.
• Integer: Whole numbers with no fractional/decimal part. Digits only, with no thousand separators or other formatting characters. Please note that the integers could be up to 64bit unsigned. The only integer currently larger than 32bit unsigned is the RoomID.
• Date String: A date in the format of YYYY-MM-DD. Year part should be padded with zeroes to 4 digits, and month & day zero-padded to 2 digits.
• Decimal: Numbers containing fractional/decimal digits (e.g. 123.45), usually representing a currency amount. No formatting characters (inc. currency symbols) except decimal place indicator, which shall be a full-stop/period. In response data, where fractional part is zero (e.g. 123.00) the digits after the decimal place may be omitted (e.g. 123).
• Boolean: Indicates values of a true/false, yes/no nature. Values of ‘True’ and ‘False’ only, but these are not case-sensitive.

API Versions

API versions less than 6.0 are no longer supported.

Additional XML Elements

All connections must be able to accept any new elements added to the API without breaking, as long as the additions do not change the structure of the Response.

Best practice and booking flow

The recommended booking flow is to search and then book. An additional availability request prior to booking is discouraged as unnecessary and potentially problematic. The XML returns the cheapest price for any given room. If you search and get a RoomID, a later availability search may not return that RoomID if it is no longer the cheapest option even though it is still bookable. The BookRequest checks availability and will return a failure if the room is not available.

To avoid over or under charge scenarios, we strongly recommend that you include the TotalPrice element in your BookRequests.

You should always check the Response to ensure that the Request operation completed successfully. If issues arise because the response was not checked, you will be liable for any charges incurred. For example, if you send a CancelRequest and do not check / handle a failure (could be no response, or a specific Exception sent by us), you are still liable for what is most likely still a live booking.

RoomID and PropertyRoomTypeID

The RoomID returned by XML is the current contract price for the room. However, it is not a fixed price. If the contract price changes (e.g. with a special offer) then the price will change to reflect this. It is important to understand that this is also not a ‘physical’ room type. If you need to map against physical room types (e.g. a ‘Standard Room’ at ‘Example Hotel’) please map against the static PropertyRoomTypeID. Older connections may not have this enabled unless requested. Please contact us if this is required or to discuss further.

Adults, Children and Infants

Please note that the numbers returned in responses may not match those submitted in your request. This is because the response shows how the numbers are charged. For instance, if you submit a child with age 17 and the hotel prices children over 15 as adults then that child will be counted as an adult in the response. The total number of passengers in the response should always match the request.

Also, please note that Infants are still accepted but are deprecated as of documentation version 1.6.5. It is strongly recommended to only send Children elements and they should all have an appropriate ChildAge (0 – 17). Notification will be given before the removal of Infants from the Request part of the API.

Meal Basis

If not set, or set to ‘0’ in a SearchRequest, the SearchResponse will attempt to return the cheapest rooms for each meal basis available. For example, a Beach Front Villa, All Inclusive and a Beach Front Villa, Room Only. However, this will depend upon how the Property is contracted and so it may be necessary to do a search for each meal basis individually. If this is the case, your SearchResponse will include the cheapest available option for each room type (for example the Room Only rate). Please discuss with the contract manager for the Property in question.

Whitelisting and IPs

We do not currently whitelist.

Please respect the TTL on our DNS and do not cache the IPs for our XML for any longer period.

Room Names and Views

The default is to return both the room name and the view as one element ‘Name’. Example: ‘Example Villa Sea View’. If you want the return to be split out into a Name and View, please contact us. Split out, you will then receive a Name: ‘Example Villa’ and a View element ‘Sea View’.

If you have this setting enabled and the View is not available, it may be missing or self-closing in the response.

OnRequest Rooms

Some room types may have OnRequest set to True in the response (only bookable manually via the Supplier and not via the XML). Additionally, some rooms may have rules about the minimum number of days between booking and arrival. If your request is within this limit the room will be returned as OnRequest. For example, if a Supplier only accepts bookings at least 3 days in advance of arrival and you do a search for arrival in 2 days, all rooms in the search response will be marked as OnRequest.

OnRequest rooms will have all other details returned as per the API.

If you do not wish to receive OnRequest rooms in responses, please contact us.

Ratecodes

The XML does not directly support ratecodes as they add a manual burden to an electronic system, and we discourage their use. However, if the Supplier or Distribution Channel require ratecodes, there is a portal where you can find ratecodes from RMI or add any ratecodes required by other Suppliers:

https://xml.xml.world/ratecodes/

Ratecodes cannot be sent in requests. If a Supplier requires you to use ratecodes, add one or more at the URL above. We search all ratecodes provided and return the cheapest rooms found for your request. To book, please use the RoomID as normal.

IMPORTANT: Rate codes are CASE SENSITIVE. Also, Iif you do not wish to use a rate code anymore or it has expired, please remove it. Some suppliers will return no results if any rate code requested is invalid or expired. This is beyond our control and can lead to the failure of any search involving a property with a bad rate code regardless of which property has the bad rate code.

Currency

All price amounts are in USD across the entire system unless explicitly stated. If necessary, this will usually be discussed in more detail at the time of contracting.

Timeouts

Timeouts are 30 seconds for a SearchRequest and 60 seconds for any other request.

Modifications

Modifications are currently not supported. Please cancel and rebook.

References

There are four references which might be part of the BookResponse and BookingResponse

• BookingReference: Our reference. Always present.
• TradeReference: As provided by you at time of booking.
• SupplierReference: May be omitted.
• PropertyReference: Some bookings do not have the confirmation reference available at the time of booking. If we do have a reference, it will be here. Please note that this may, for some Suppliers, appear later in the BookingResponse.

Supplier Notes

We strive to keep our API consistent regardless of the Supplier we are connecting you to, however sometimes the Supplier’s API does not allow full compatibility.

SwapSystems

On BookRequest the Request field cannot be send to the supplier and is dropped.

As the interface is stateless, the login details are required on every call to the interface. The current version of this API you have implemented is also required.

The current supported versions are “6.0” and any documented versions greater than this. It is recommended to use the latest version.

Parameters

Every call made to the interface will have the following status response in addition to any call specific data that is returned. The Success element will contain the values True or False. If False, the Exception will contain details of the problem. Each response will also contain a RequestInfo tag which has several elements inside of it. These are not required to be parsed and are only used for manual tracing purposes.

Please note that responses with the Success element set to False will have their respective response tags unless the failure is due to an error which prevents the request at least reaching the stage where credentials have been validated. For example, a Search request which has an incorrect Duration will return a SearchResponse tag, but where a request contains invalid credentials, or is malformed, the return will be a Response tag.

Parameters

The following methods are supported by the Booking Interface:

• Search: booking criteria (e.g. locations, dates and passenger breakdown) passed to the system and a result set containing availability-checked and priced property results will be returned
• Book: information returned in the Search response used with additional information (e.g. passenger details), to make bookings in the system
• Booking Details: returns the full details of a booking from the system
• Cancel: send a cancellation for a previously made booking