home > support > API > getting started

Getting started with TourCMS API

How the platform is organised

API users

Broadly speaking there are two types of organisation accessing TourCMS API:

Operators

Access TourCMS back office to load tours & activities to sell.

Marketplace Agents

Use TourCMS to sell tours & activities loaded into TourCMS by Operators.

Common terminology

The main products & services exposed via TourCMS are referred to as Tours. This is regardless of whether they are actually tours, activities, transfers etc.

Individual instances of a Tour - for example the 8am departure on the 3rd September - are referred to as Departures*. Tour Departures are priced using Rates, e.g. an "Adult" rate, a "Child" rate etc.

When you reserve/book a Tour for a Customer you will create a Booking.

Tours and Bookings are accessed via Channels. Channels allow operators to expose their core Tour data while applying a specific branding, descriptions, markups, exchange rates etc. As an Operator you will have one or more Channels, as a Marketplace Agent you will be connecting to Channels created by the Operators you resell.

* Other pricing structures are supported by TourCMS, including "Freesale seasons" and limited "Hotel" type pricing, however these are not in wide use and largely not supported by Marketplace Agents.

Connecting & Authenticating

TourCMS API is accessed via HTTP and authentication is via a signed hash created using a shared secret API key.

Operators will have an API key for each Channel they create, Travel Agents have a single API key for use across all Channels they connect to.

Full detail on creating the Authorization header is available, however there are client libraries and sample code for many popular programming languages that will make things easier.

API limits

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.

Data formats

• XML is UTF-8 encoded
• URLs are 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 <br> tags
• Dates are YYYY-MM-DD format

Images

• There will be at least one image for a given tour 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). Generally most TourCMS accounts have large images uploaded in 3:2 aspect ratio.
  • 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 endpoint.
• 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.

Next page

Here the getting started guide differs depending on whether you are accessing TourCMS as an Operator (loading your own tours & activities to sell) or a Marketplace Agent (selling tours & activities loaded by others).

Part two (for Operators)   Part two (for Marketplace Agents)