Introduction

Lemax API is a web service based on SOAP, and as such uses XML for data exchange and is technology independent. Using API doesn’t require installation of any kind. Its purpose is the integration of the client’s website with Lemax Software back office, i.e. display of the information from the client’s back office on the client’s website, and booking of client’s products directly from their website.

Lemax Software offers various means of integration, but API provides the most flexibility and customization options.

This is not a documentation of all API features (complete API documentation can be found here), but a short guide on getting started, since our API is rather extensive. The purpose of this document is for you to figure out exactly what you’ll be looking for in the API documentation when you start the implementation phase.

Lemax booking process

Our booking process consists of four consecutive steps: search, search results, detailed view and booking.

Usually, customers want to do a search of your products by using various filters. This leads them to the second step – search results, a list containing the products that match their applied filters. Customers can then click on a particular product in the search results to see more information about it, which leads them to a detailed view of that product. From there, they can proceed to booking the product.

In case there’s only one product in the search results, that step can be skipped and you can redirect straight to the detailed view of that product. Also, you may wish to implement a way to go straight to the booking step from the search results, without necessarily going to the detailed view.

Lemax Software supports a multitude of different types of products, all of which belong to one of the three product type groups: accommodations (hotels, hostels, vessels, private accommodations…), tours (simple tours, advanced tours, activities…) and transportation (transfers, charter flights, rent-a-car…). The booking process for each type of product is the same, but each product type group has its own API methods.

Booking process steps

Search

Searching is performed with a search box, which consists of a number of filters / search fields.

Use GetSearchFields method to fetch the data for the search fields you want (the same method is used for all three product type groups – accommodations, tours and transportation).

GetSearchFields method takes a GetSearchFieldsParameters class as an input parameter. That class has the following properties:

• LanguageID – ID of the language in which the data in the response will be.
• ObjectTypeIDList – If objectTypeIDList is not empty, only categories, countries, regions and destinations that contain the objects of those types will be returned.
• ObjectTypeGroupIDList – If objectTypeGroupIDList is not empty, only categories, countries, regions and destinations that contain the objects whose type belongs to the group contained in that list will be returned.
• CategoryIDList – If categoryIDList is not empty only countries, regions and destinations that contain the objects in those categories will be returned.
• CountryID – Only regions and destinations that are in the country with that ID will be returned.
• RegionID – Only destinations that are in the region with that ID will be returned.

GetSearchFields method returns a SearchFields object. Its properties are:

• Categories – List of available categories to search from.
• CountryList – List of available countries to search from.
• RegionList – List of available regions to search from.
• DestinationList – List of available destinations to search from.

Of course, you don’t have to use all (or any, for that matter) of those search fields, and you can implement your own additional filters, like date pickers for travel dates, inputs for the number of people that will use the booked product or inputs for the price range.

Search results

Search results, as mentioned previously, is a list of products that match the search criteria.

Each product type group has its own API method for fetching search results. These are: GetSearchResults (for accommodations), GetPackageSearchResults (for tours, which are also called package tours) and GetTransportationSearchResults (for transportation).

Each of these three search methods has its own input parameter class: GetSearchResultsParameters, GetPackageSearchResultsParameters and GetTransportationSearchResultsParameters.

Since each product type group is unique, each of these classes has some unique search properties, but they all share the basic and most important ones. Some of them are:

• StartDate – Start date for period in which unit should be available. If startDate is set to NULL or is equal to endDate, availability is not checked.
• EndDate – End date for period in which unit should be available. If endDate is set to NULL or startDate, availability is not checked.
• CountryIDList – List of countryIDs. If the list is set, the method returns only objects that are located in one of the countries whose countryID is on the list.
• RegionIDList – List of regionIDs. If the list is set, the method returns only objects that are located in one of the regions whose regionID is on the list.
• DestinationIDList – List of destinationIDs. If the list is set, the method returns only objects that are located in one of the destinations whose destinationID is on the list.
• ObjectAttributeFilterList – When objectAttributeFilterList is not empty, objects in response will be filtered out by given attributes in objectAttributeFilterList. This parameter is used to filter objects by Name, Stars, etc.
• UnitAttributeFilterList – When unitAttributeFilterList is not empty, units in response will be filtered out by given attributes in unitAttributeFilterList. This parameter is used to filter units by Capacity, Air Conditioning, etc.
• OutParameterList – This is used to limit the amount of information about objects and units in the response. Only information listed in the outParameterList will be returned. For example, you can use it to fetch only object’s or unit’s photos, description or map coordinates, instead of complete objects with their units and all of their properties.
• OnlyOnSpecialOffer – The response contains only objects that have a special offer.
• ObjectIDList – List of Object IDs. The search will return only objects whose IDs are on the list. If the list is NULL or empty, the parameter is ignored.
• CurrencyID – ID of the currency in which the prices should be returned.
• LanguageID – ID of the language in which the data in the response should be.
• PriceFrom – If priceFrom is set, the method returns only units with price greater or equal to priceFrom.
• PriceTo – If priceTo is set, the method returns only units with price lesser or equal to priceTo.

Since transportation are usually not connected to only one destination, but two (pickup and drop off locations), they don’t use only one list for countries, regions and destinations, but two for each.

You can make a filter / search field for any property in those input parameter classes. For instance, you can make a section of the search box that will contains check boxes for unit attributes, like Air conditioning, Satellite TV, Balcony, Sea view etc. For each check box checked, you will then add that unit attribute to the UnitAttributeFilterList.

Each search method returns a distinct response object: SearchResults (accommodations), PackageSearchResults (tours) or TransportationSearchResults (transportation).

Some of the properties of SearchResults are:

• AccommodationObjectList – List of objects returned in search results. Each AccommodationObject on this list contains detailed information about that accommodation object, like name, description, list of photos, list of accommodation units etc.
• DestinationList – List of destinations in which objects from AccommodationObjectList are located.
• RegionList – List of regions in which destinations from DestinationList are located.
• CountryList – List of countries in which regions from RegionList are located.
• ObjectLocationList – List of coordinates for the objects returned in search results.
• TotalNumberOfResults – Total number of objects that match input parameters in GetSearchResults.
• PageSize – Number of results returned per page.
• CurrentPage – Defines which page of the response is returned. If number that exceeds the total number of pages is sent, the last page is returned.

PackageSearchResults inherits SearchResults, so it has all the same properties, plus one more – PackageTourList. That property contains the list of package tours returned by the search method.

Each PackageTour in PackageTourList has the following properties:

• PackageUnitList – List of package units in the package tour.
• DaysList – Distinct list of days from the package period list.
• DistinctPackagePeriodList – Distinct list of package periods from the package unit list.
• PackageTourName – Name of the package tour.

TransportationSearchResults doesn’t inherit SearchResults, but it has similar properties, and instead of AccommodationObjectList, it has TransportationList. Each Transportation object on that list contains detailed information about that transportation, like the name, description, list of photos and transportation units.

Detailed view

Detailed view of a product is used to display much more information about a particular product than it is displayed in the search results.

Again, each product type group has its own method for fetching detailed information about a product: GetDetailedDescription (accommodations), GetPackageDetailedDescription (tours) and GetTransportationDetailedDescription (transportation).

And once again, each of those methods has its own input parameters class: GetDetailedDescriptionParameters, GetPackageDetailedDescriptionParameters and GetTransportationDetailedDescriptionParameters.

GetDetailedDescriptionParameters and GetTransportationDetailedDescriptionParameters have a lot of the same properties:

• StartDate – Start date of the period for which the unit prices will be returned. If startDate is NULL, it will be set to current’s date following day.
• EndDate – End date of the period for which the unit prices will be returned . If endDate is NULL, it will be set to seven days after startDate.
• NumberOfPersons – Number of persons for which the price will be calculated. If numberOfPersons is NULL, one person is assumed.
• ObjectID – ID of the object whose detailed description is returned. This is a required parameter.
• CurrencyID – ID of the currency in which the unit prices will be calculated.
• LanguageID – ID of the language in which the data in the response will be.
• UnitID – If unitID is set, the method returns only the unit with that ID from the object’s unit list.
• UnitTypeID – If unitTypeID is set, the method returns only the units of that type.
• UnitCategoryID – If unitCategoryID is set, the method returns only the units from that category.
• ObjectURL – SEO (search engine optimization) object URL. If this parameter is set, the method ignores objectID and languageID parameters and returns the object that the objectURL links to. The language is determined from the URL as well, because each object has a different URL for each supported language.

GetPackageDetailedDescriptionParameters is a bit different from them and lacks many of those properties. Some of the important properties of this class are:

• PackageTourID – ID of the package tour whose detailed description is returned. This is a required parameter.
• ObjectIDList – List of object’s IDs whose detailed information will be returned (package tours can contain multiple accommodation objects). For objects whose ID is not on this list, only basic information will be returned.
• Periods – List of periods for which detailed information will be returned. For other periods that are not on this list only basic information will be returned.
• OutParameterList – This is used to limit the amount of information about objects and units in the response. Only information listed in the outParameterList will be returned.

Each method for fetching the detailed description returns a distinct response object: AccommodationObjectDetails, PackageTourDetails or TransportationDetails.

They all share some common properties:

• Destination – Destination in which the returned object is located.
• Region – Region in which the returned Destination is located.
• Country – Country in which the returned Region is located.
• PeriodList – Period list for prices of services of the units contained by the returned object.
• Currency – Currency in which the prices returned by the method are.
• Language – Language in which the data returned by the method is.

The main property of the AccommodationObjectDetails is AccommodationObject. It contains all the information about a particular accommodation from the back office, such as a name, description, lists of attributes, photos, units, categories, price lists, SEO data, cancellation policy etc.

The main property of the PackageTourDetails is PackageTour. It inherits AccommodationObject and so it has the same properties, describing a single package tour in great detail. It also has additional properties unique to package tours. PackageTourDetails also contains a list of AccommodationObject objects, which contain the details of all the accommodation objects connected to that package tour.

Likewise, the main property of the TransportationDetails is Transportation. It also inherits AccommodationObject, while having additional properties unique to transportations, providing all the details about a single transportation object from the back office.

So, each of these main properties contains details about the object. It also contains the list of units of that object, and each unit object has all the details about that unit. For instance, a hotel would be an object. AccommodationObject contains the details of that hotel. A hotel room is a unit of the object. AccommodationObject has a list of units (list of AccommodationUnit objects), and each AccommodationUnit object contains the details of the room it represents.

Booking

On the booking step customers can choose the number of units being booked, the number of people who will be using those units, additional services if the booked unit has any, leave their personal information and choose a payment method.

 

We recommend using our premade booking form in the form of an iFrame element. It offers less customization options than if you’re making your own booking form, but it is completely automated. It calculates the price of the reservation based on the number of units, people, and selected additional services, automatically applies special offers and discounts, creates new customers from provided personal information and it has built in payment options, including integration with numerous payment providers such as PayPal. It also adjusts its appearance and options based on slight differences between different product types. For instance, when booking tours, customers can’t choose arbitrary dates, because tours have fixed departure dates and duration, so the booking form lets you choose one of the available departure dates.

Of course, you can make your own online booking form. In that case, you will have to take care of all those things yourself. To help you get started, we’ll suggest some API methods that you can use, and you can check the API documentation to gain more insight into using those methods.

You can display additional services, special offers, discounts, cancellation policy etc. for the unit being booked by using the detailed description methods covered in the previous step. For calculating the reservation’s price, you can use GetReservationCalculation. You can get available payment methods by using GetPaymentMethods. Use CreateReservation to make the reservation.

Examples of work done with our API

Additional tips

• In order to appear on the client’s website, units in the back office need to be set with a status “Published on web”. Units with the status “Active” will be available for searching and booking in the Lemax back office, but will not be returned by API methods.
• Objects and units in the back office are cached for 30 minutes, meaning any change done to them in the back office will be visible on the website after half an hour. Cache can be cleared in the back office on Options -> General settings.
• You should strive to minimize the number of API calls to improve the performance of the website.
• If you are using our API, we will provide you with an API username and password. You need to include those in the header of the SOAP envelope of every API call you make.
• SEO data needs to be cached for at least 15 minutes, but we recommend caching it for an hour, to eliminate round trips between servers for every request. SEO data is not changed frequently and is suitable for caching, and failing to do so will negatively impact your site performance. While you are developing you can turn off caching or reduce caching time, but when the site goes live, you should follow this recommendation.