Used by 400 Specialist Tour & Activity Operators worldwide

home > support > API > useful information for developers

Useful information & assorted notes

Making products available to the API

This section is for Tour Operators only, Marketplace Agents can jump straight down to "Usage throttling".

The following criteria must be met before a Tour will be available via the API:

Account settings
1. You must upgrade to a paid TourCMS account if you haven't done so already
2. You must configure at least one of your Channels for the TourCMS Marketplace. To do this log in to TourCMS, head to TourCMS Marketplace, click Configure and fill in the required details
3. You must switch on the API. To do this head to Configuration & setup > API, tick Enable then Save changes
Individual product settings
1. The Tour must be set to Distributed (in the Setup page for the Tour, under the General tab)
2. The Tour must have all the basic Marketplace fields completed. To see which information you still need to fill in head to Tours > Descriptions & Images for the tour and look on the Incomplete data tab

Additionally some API calls will - by default - only return products that have availability loaded.

The TourCMS Marketplace page inside TourCMS will be useful as you progress loading your products, it shows which of your products are Fully setup (so should show up in API calls), which Could be made better (perhaps have overly short descriptions or fairly small images) and which have Incomplete data.

Product Page URLs

To ensure quality TourCMS periodically checks each Tour Product Page URL and if the page cannot be found the item will be hidden from the API until the URL is updated or the page is back online. If Tours are switched on for the Marketplace and have all the required data completed but are not appearing in API searches or on widgets it could be that your Product Page URLs have been set incorrectly, TourCMS has detected a problem and removed them from the API until the problem is fixed.

If this is the case when you head to TourCMS Marketplace you will see the Tours listed under the "Incomplete data" column, we will also send occasional emails to channel owners notifying them of the problem.

In some cases this may cause a Catch-22 situation, whereby you are developing a new Operator website using the XML API or WordPress plugin, in this case you should set a temporary product page URL that points to a holding / home page on your website and then update once the correct pages exist.

Updating Product Page URLs programatically

The Update Tour method can be used to fix product Page URLs, there are a couple of different ways to approach this:

If you are importing product data into your own database - You may want to check the tour_url returned in the XML, if it is not correct you could update TourCMS with the correct URL by calling Update Tour
If you are using the API directly - You may want to set up job that runs once a day or so to check for any Tours that are returning errors. To search for Tours that have problem URLs just make a call to Search Tours passing in 404_tour_url=error, then for each of those just update TourCMS with the correct URL by calling Update Tour

Usage throttling

API use is restricted to 3000 GET and 3000 POST calls per hour (consider caching of some GET requests).

If you are a Marketplace agent this is 3000 calls per channel per hour (i.e. lots!) We reserve the right to alter this limit based on usage patterns. Current usage status is returned in the header:

X-RateLimit-Limit the current limit in effect
X-RateLimit-Remaining the number of hits remaining before you are rate limited

You can also call the Rate Limit Status method to find your current remaining number of hits, calls to this method do not count towards your limit.

Result formats

Data format

XML is UTF-8 encoded
URLs will come through URL encoded
Fields that allow HTML content will be returned as HTML entities. The only HTML elements allowed in content are: <strong><em><ul><li>
Fields containing character data are made XML safe by converting some characters to their HTML entity versions. This conversion applies to ", ', &, < and >
In multi-line data, newlines are not returned as HTML entities
All data is returned as XML (although client libraries may offer alternatives). Future updates to the API may enable direct return of other datatypes, these would be accessed by changing .xml in the method URL to another datatype (e.g. .json)
Dates are YYYY-MM-DD format

Images

There will be at least one image in the API, it will be at least 342 pixels wide
If the image uploaded is large enough, TourCMS will generate several alternative sizes, maintaining the original aspect ratio (shape):
- Thumbnail: max 342 pixels wide
- Default: max 800 pixels wide
- Large: max 1500 pixels wide
- Extra Large: max 1920 pixels wide
- Original: The original image uploaded by the user, only available via the list images API call.
You are welcome to just embed / link to any of the images except the original, or download and serve them from your own hosting
Image URLs are served securely (https) by default.

Unique product IDs

There are 3 core IDs that you will see returned in the data:

Account ID - This is unique per TourCMS account. A single account can have multiple channels (each channel perhaps featuring different products, different language but same products or different prices but same products)
Tour ID - Unique per Account ID but will be non-unique over multiple accounts
Channel ID - Unique per channel

Hence if you care about removing duplicate tours, filter by a combination of Account ID / Tour ID.

You can filter by combination of Channel ID / Tour ID however if you are connected to the same TourCMS supplier account over multiple of their sales channels, you could have duplicate tours (e.g. an English version plus a French version)

To tell if it is the same tour from the same tour operator supplier, just in a different sales channel (e.g. perhaps with a different description language), check Account ID / Tour ID combination

Unique booking / customer IDs

There are 3 core IDs that you will see returned in the data:

Account ID - This is unique per TourCMS account
Customer ID - Unique per Account ID but will be non-unique over multiple accounts
Booking ID - Unique per Account ID but will be non-unique over multiple accounts

Additional Information for TourCMS Marketplace Agents

Permissions

Permissions are set by the TourCMS account owner. All agents can see dates, prices, availability & create new bookings (via API and booking engine) and create enquiries (via API)

Granular permissions
Level	Description
1 - Sell only	For advertisers See products, dates, prices & availability See clicks Create enquiries (Via API) Create bookings (Via API and via booking engine) Generally used when a tour operator/supplier wants someone to promote their product but if they are paying an annual listing fee (rather than on a success basis) they don't want to disclose how successful the advertising has been.
2 - Summary statistics	For agents/affiliates (DEFAULT) See basic booking / customer information - Lead customer name, travel dates, sale value & commission (if set) See own enquiries .... and also all actions that 1 can do Designed where you don't want to over disclose customer personal information e.g. with an affiliate who only referred you web traffic (that subsequently turned into a booking) rather than an actual customer booking
3 - Full detail	For travel agents See name, address, full details for all customers on the booking See list of payments See customer special requests See customer travel insurance details See booking summary (e.g. the same as %summary_sale_table%) .... and also all actions that 1 and 2 can do You can disclose the customer information to the agent at this permission level as the chances are they gave you the booking in the first place hence already have that information. Agents will will NOT see profit margin, costs or which suppliers have been used.

i.e. Generally affiliates/marketing partners can see and sell product. Traditional Travel Agents can see bookings/enquiries.
Tour operators can see and alter customer / booking data

Seeing no data

You can only see data from TourCMS accounts you are connected to. The onus is on the TourCMS account to give permission for you to see their data (perhaps after a commercial conversation)
The API will normally only return data from TourCMS accounts that are paying (i.e. not free trial accounts) and are in good standing

Testing

Inside the Marketplace agent login is a test harness to easily review responses to various XML calls
The Marketplace agent login also has an API log so you can review recently made API requests and their responses as well as failure reasons

Bookings, enquiries etc

A booking is date/product specific. An enquiry is a request such as a lead, contact us, phone back, brochure request etc.

Enquiries are much simpler and if you don't want to spend too much time in development, use enquiries

When an enquiry is put into TourCMS if a member of staff subsequently uses that customer record to manually create a booking, the correct agent tracking (and commission etc) will be applied to the new booking

Taking bookings

Using the various API calls it is possible to completely obscure that TourCMS is being used. Or send trafic to the supplier's website or down their booking engine (that you can brand as your own)

You can send traffic to the websites as returned via the XML. If you use the tracking URL a 365 day cookie will be set on the consumer's browser on the TourCMS domain. Future bookings from that consumer will be assigned to you
You can take the booking on your website (with your design of booking engine) but with the functionality as configured by the operator of the product you are booking. If they have integrated a payment gateway into their booking engine that payment gateway will be used
You can use the live booking API!

Product prices

The majority of API calls give you RETAIL (sale) prices. These can be shown directly to consumers

If you (as a travel agent) are working on commission OR net rates, the RETAIL prices will carry through the booking howevery your BALANCE OWING will take into account your commission or your agreed net rate. i.e. you will pay less than the retail price at point of paying

If you want to know what the net rates will be ahead of time, they can be found via the Show Tour Departures API call.

If you are working with some suppliers on commission and some on net rates, TourCMS will work this out for you automatically

Tour operator vs Agent API credentials

Each travel agent with a TourCMS Marketplace agent account will have their own API credentials. These credentials are found via the travel agent login.

Each tour operator / supplier account, available via Configuration & Setup - API, has their own API credentials. These API credentials create bookings that pickup the correct tracking from 3rd party affiliates & travel agents, rather than being locked to a single travel agent.

Travel agent credentials should be used to build an agent website featuring tours from multiple TourCMS supplier accounts.

Tour operator / supplier credentials should be used to build the tour operator's own website.

Special case (Advanced): If you are working as a travel agent AS WELL AS featuring your own tours (from your own TourCMS supplier account) then use agent API credentials for search (all tours), use the travel agent API credentials to book 3rd party product, but use your tour operator / supplier API credentials to book your own product. (This ensures that all TourCMS affiliate tracking works as it should do, for your own bookings of your own tours from your own supplier account)

API checklist

TourCMS do NOT mandate that we ratify or check your API integration - however - for some larger projects we do. This is what we will check

Sign off list
Reference number	Description
1	Commercially sensitive data Net rates (i.e. commercial rates sold by a supplier and given to a travel agent) should never be exposed to customers Likewise, suppliers will give you average transaction size, click to book ratio etc. This should not be exposed to customers either
2	API credentials If you are building an application for members of staff to use, please ensure that only administrators may set and see TourCMS API credentials. In particular this is the case if you are storing tour operator API credentials as these are the most powerful set and can be used to adjust any booking in the system (on that account) If a website / distributor is both a travel agent AND a supplier to itself (i.e. has a tour operator account), ensure that API credential use is correct. (See note above about using supplier API credentials when booking your own product and travel agent credentails when booking a 3rd party supplied product).
3	Quality control All tours in the TourCMS API have a minimum amount of data completed; so you can be sure products have base descriptions, geolocation, at least one image etc. Additional quality control is available to allow agents/affiliate to only feature tours that meet or exceed our Content Quality Guidelines including large image sizes and improved descriptions. Quality control can be used on a per API request basis, however we would recommend agents/affiliates switch on quality control inside their TourCMS control panel, ensuring quality control is in place automatically wherever available.
4	Hotel pickup points Ensure that hotel pickups are added at point of booking. It is possible to create bookings without hotel pickups but generally hotel pickup selection should be shown and handled. UI design notes Hotel pickups can be time sensitive - e.g. a hotel may be on a route for a morning tour but not an afternoon tour. This is why pickups are on the check availability API You know the time of the pickup (e.g. 10:00 or 14:00) - don't let the customer pick the 14:00 for a 11:00 tour start time Some tours have freetext "on request" hotel pickup capabilities. Check if this needs to be supported in your UI.
5	Display the date "note" Particularly when offering clients the ability to choose between various components available on a certain date the start/end date, start/end time is NOT sufficient to distinguish between all trips. The "note" can often be vital (e.g. could be zone information for a transfer, or a specific language that the tour is being run in). User interfaces for selecting between the available components should at a minimum show dates, times and "note" field where they differ between the components returned.
6	Total sale price may not be total of all the components There can be booking fees. There can be discounts for adding multiple components to the same basket. Check the value that comes back from booking start - rather than adding individual component sale prices.
7	Credit card fee type (Tour operators only) Ensure that the credit card fee (received from response from booking_start - creditcard_fee_type) - transmitted through to create_payment
8	Airport transfer information collected For product type 2 - Transport/Transfer - please collect the following information: Mandatory (most of the time!) Airline/Train name Flight/Train number Arrival Time Hotel name Consider adding Origin Destination Hotel address Greeting board details Luggage (e.g. Skis) This should be sent through in the note, on the component, in booking_start as follows: `Airline : ABCDEF Flight : GHIJKL`
9	Total customers Ensure that the correct total_customers is sent to booking start. If you don't know how many total customers you have, if you have a booking including one tour with 4 people & another tour with 3 people our general advice is to send 4 not 7 as the total_customers number.
10	API caching If calling the API in live time - that - as far as possible - API requests for tour search, details & dates/prices are cached (e.g. for 10 minutes). (Booking should always be done on live API calls though). Further information on caching
11	Agent reference On booking start and IF you are making a booking in a 3rd party system outside of TourCMS, please send the 3rd party system booking reference to TourCMS as agent_ref. Additionally, it is helpful if you preceed with your service name e.g. GLOBALOTA-123456. Define your service name as you like (we know the booking was made by you via other tracking). You MAY just have a booking reference, no service name, but it is preferable to have a service name. This agent reference, apart from being used for vouchers (see below) is helpful to tour operators to manually reconcile bookings between your system and TourCMS, if necessary IF you are only making the booking in TourCMS (and not your own system simultaneously) you may leave agent_ref blank
12	Voucher bar codes Please read and ensure you implement our guidance on vouchers and barcodes.
13	Your own email notifications (to supplier) If you are an Online Travel Agent (OTA), you send email notifications to the supplier (TourCMS powered tour operator) telling them about their new booking. Unless otherwise agreed with the supplier, please continue to send your email notifications even if you are also sending the booking via our TourCMS API (Many will ask you to turns your email notifications off, but best to wait for them to tell you, rather than assuming). The email address to send to is email_customer from Show Channel.
14	Defaulting next bookable date on a single tour page On a single tour page, when you are showing an available date calendar (probably informed by Dates & Deals)), default the next bookable date to next_bookable_date from Show Tour API rather than the first date in the dates & deals API. The next bookable date from tour show updates quicker than the dates & deals API (which is heavily cached), so this will be a more accurate approach
15	Supplier sign off to go live YOU MUST contact any supplier before you turn on for bookings and wait for their sign off / agreement to go live Specifically, please do not go live on a Friday.