home > support > API > Marketplace API > useful information

Useful information & assorted notes

Making products available to the API

This section is for Suppliers only, Partners can jump straight down to "Usage throttling".

The following criteria must be met before a Tour/Hotel 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 websites 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 and tick Enable and then Save changes
2. Individual product settings
   1. The Tour/Hotel must be switched on for onlnine bookings (in the Setup page for the Tour, under the General tab)
   2. The Tour/Hotel must be switched on distribution by the TourCMS Marketplace (in the Setup page for the Tour, under the General tab)
   3. The Tour/Hotel must have all the basic Marketplace information completed. To see which information you still need to fill in for a particular Tour just head to Tours/Hotels in TourCMS then click 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 Live in the Marketplace (so should show up in API calls) and which are Not distributed or Incomplete.

Product Page URLs

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. To ensure quality TourCMS periodically checks each Tour/Hotel 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 this is the case when you head to TourCMS Marketplace you will see a box listing the Product Page URLs with problems and quick links to fix them, we will also send occasional emails to account 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 / Joomla plugins, 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.

Usage throttling

API use is restricted to 2000 GET calls per hour, POST is unlimited.

If you are a marketplace partner this is 2000 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><h1><h2><h3><h4><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

• You can serve the images from media.tourcms.com if you wish
• The TourCMS media server can handle both HTTPS and HTTP traffic
• The thumbnail image is returned full size. You could use a code function to make the image the size you wish. Alternatively you could set the image width (e.g. width="100") and leave the height unset. This will make the web browser do the resizing. Or you could use CSS such as style="width: auto !important;height: 40px;" (on the img). That is what we use

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.

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 Marketplace partners

Permissions

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

i.e. Generally affiliates/partners can see and sell product. 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 partner login is a test harness to easily review responses to various XML calls
• The marketplace partner login also has an API log so you can review recently made API requests and their responses as well as failure reasons

Knowing when tour/hotel descriptions change

Some partners maintain their own version of the tour/hotel text descriptions. The descriptions_last_updated field (on the tour/hotel) can be used to check when the supplier/tour operator last changed their description

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!