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.
User-Agent
All requests to TourCMS API should include a HTTP User-Agent header. This should be something that can identify your account and the specific application that is connecting to the TourCMS API, e.g. User-Agent: Example Tours Website or User-Agent: Example Tours Accounting.
Please also include your Marketplace ID (0 in supplier accounts) and Channel ID in brackets following your user agent string. If you are using a TourCMS-provided client library there is no need to take this step as by default the library will add these details for you when you provide a User-Agent string. E.g.: User-Agent: Example Tours Website (0_3930)
Request Id
To aid in tracking/troubleshooting specific requests we would suggest sending an X-Request-Id request header when calling TourCMS API. This value of this header should be at least somewhat unique over a period of time, and should change with each request request. A randomly generated UUID4 is often used and is a good option. E.g.: X-Request-Id: 2357bed7-a764-48b5-9719-d2f54d5401b3.
Additionally TourCMS will return you an X-Correlation-Id header as part of the response. This is TourCMS internal reference for the request and you may wish to log this too.
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 limitedYou 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).