Useful information & assorted notes (article)

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:

1. 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 into TourCMS, head to Partners, click Data Quality and fill in the required details
   3. You must switch on the API. To do this head to Configuration > System& setup > API, tick Enable then Save changes
2. 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 Data Quality 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 improved (perhaps have overly short descriptions or fairly small images) and which must be fixed.

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 Data Quality you will see the Tours listed under the "product must be fixed", 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/homepage on your website and then update once the correct pages exist.

Updating Product Page URLs programmatically

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 a 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 calls per hour (consider caching), POST is unlimited.

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 not served securely (https) by default, however:
  • Images on the domain media.tourcms.com can just have the http swapped out with https
  • Images on the domain rackcdn.com change the http to https but also change the .rXX.part of the hostname to .ssl. (where XX will be numbers, e.g. http://1ba477c.r92.cf1.rackcdn.com/1/1/default.jpg would become https://1ba477c.ssl.cf1.rackcdn.com/1/1/default.jpg
  • The following PHP code will convert any TourCMS Marketplace image URL into a secure version:

// Function to convert http TourCMS Marketplace image URLs to https ones

functiontour_image_secure($url){
$url=str_replace("http://","https://",$url,$count=1);
$urlparts=explode('.',$url);

 // check for presence of 'r' segment
if(preg_match('/r\d+/',$urlparts[1])){
$urlparts[1]='ssl';
 // put url back together
$url=implode('.',$urlparts);
}
return($url);
}

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)

i.e. Generally affiliates/marketing partners can see and sell a 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 traffic 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 however 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 DeparturesAPI 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 pick up 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

Airline : ABCDEF
Flight  : GHIJKL