Guidelines - How to#
At this point we will assume you got the info from Introduction and Quick Start sections to get full access to our API.
These guidelines cover the same process for the Sandbox API where you should make your tests for integration, and for the production API where the booking happens.
Sandbox API swagger UI consumer API is available at :
Sandbox-consumer API swagger UI consumer API is available at :
Sandbox API swagger UI content partner API is available at :
Production API swagger UI consumer API is available at :
Production API swagger UI content partner API is available at :
Step 1 : Import suppliers#
A supplier is an entity that provides one or several product(s) for the final customer (traveller). Each supplier is identified on Amadeus Discover side by a unique ID.
A supplier can have an unlimited number of products. To be able to push products, you’ll link them to a supplier.
First step is to use “Create a new supplier” (POST on
/api/supplier) endpoint to create suppliers.Guidelines for Suppliers Quality
ALENTOUR / DISCOVER Channel
Amadeus Discover is operating under Alentour branding for the French market. In your import, please make sure “Channel” field is filled properly for each supplier:
Channel = ALENTOUR for all products located in FRANCE
Channel = DISCOVER for all products located OUTSIDE OF FRANCE
Booking Engine
Booking Engine information is key to identify your products in our catalogue.
At your account creation, we did setup a booking engine linked to your account.
Supplier contact
Please provide a maximum of elements on supplier (address, city, telephone, website, zip code, country).
This is particularly important on Amadeus Discover platform side to identify duplicates of activities.
Step 2 : Import products for suppliers#
Amadeus Discover team will check the data quality and iterate with you to obtain expected data quality.
Ultimately, sign off will be granted to go Live on our production DB.
In order to provide travellers relevant activity products, it is crucial to have a good level of quality for product data.
This implies that products titles, descriptions and booking links should be available in several languages, to reach locals
as well as tourists from abroad.
It should be possible to locate the product and to give travellers visibility on the price, the duration and
the cancellation policy for the activity. Nice photos are also key to boost products visibility.
With a great diversity of products, not all fields might be relevant for all products. Nevertheless, we recommend respecting a maximum of following guidelines for the products to raise the odds that activities are returned in relevant contexts and get booked.
Guidelines for Products Quality#
Products granularity#
In order to provide good visibility on products to travellers, it is preferable to have products that cover an activity with a clear scope (unique duration, price, precise description of what the activity covers…). There might be different options for the same product, leading to a minimum and maximum price for the product, but the different options should have the same pricing structure, the same duration, the same location).
For example, a 1h kayak initiation shouldn’t be under the same product as a half day kayak ride, even though they are both kayak offers.
Key elements for production Sign Off#
Product location :#
- Geolocation: Longitude / Latitude
Example {“geoHash”: “eysbgkkcj”, “latitude”: 36.717856, “longitude”: -4.420733}
It us used to locate the product on the map, and to return the product in search with a distance criterion.
- Address
- ZipCode
- City
- Country (Country Code)
Product title and description#
Title, Description, Short Description fields are localized.
4 languages are supported in Amadeus Discover platform: German, English, French and Spanish.
Please import these fields using Json format.
Example : {“de”: “meine Prüfungen in verschiedenen Sprachen”, “en”: “my tests in different languages”, “es”: “mis test en diferentes idiomas “, “fr”: “mes tests dans différentes langues”}
ALENTOUR / DISCOVER Channel#
Amadeus Discover is operating under Alentour branding for the French market.
In your import, please make sure “Channel” field is filled properly for each product:
- Channel = ALENTOUR for all products located in FRANCE
- Channel = DISCOVER for all products located OUTSIDE OF FRANCE
Booking URL#
Booking URL is a localized field, that we use to redirect travellers to finalize their bookings.
It is a json field, precising the link in the 4 supported languages.
The Booking URL should also include a way to identify that the lead has been generated through Amadeus Discover / Alentour (header / parameter…).
Example :
NB : Additionally, Amadeus Discover Platform is transmitting dynamically tracking parameter to identify the customer organization on Discover side.
If booking URLs is the same for all languages, adapting to browser language
Booking Engine#
Booking Engine information is key to identify your products in our catalogue.
At your account creation, we did setup a booking engine linked to your account.
Online_Bookable#
This field is crucial to identify whether a product is bookable or not through Amadeus Discover platform. It is a localized field, and the value needs to be provided for each of the 4 languages supported in the Platform.
A product can be considered bookable in a language if a booking URL is provided for this language. Of course it is preferable if title / description are also available in these languages.
Example {“de”: true, “en”: true, “es”: true, “fr”: false}
NB : Default English in the search
NB : empty > Bookable, please precise False or poor user experience
Price the product#
It is crucial to provide travellers visibility on product price to generate bookings through Amadeus Discover Platform.
This can be fed using “Min price” and “Max price” fields at product level.
Min price should cover the “baseline” price, rather that a very specific rate that is available for specific travellers only (ex child rate). Maximum price should represent the maximum price in high season and with all options.
Please feed both Min Price and Max price, if you have a unique price, please use the same value for both fields.
For some peculiar activities such as restaurants, we need you to fill the priceLevel field defined as a “quartile” (ranging from 1 to 4) to indicate how cheap/expensive a restaurant is.
Additionally, we have an extra field averagePrice to feed, if possible, an average price of a meal.
NB : In the case the product is bookable for free – but still needs to be booked (example : restaurants, free tours), please input “0” for both minimum and maximum price.
Images#
You may (and should) import several images for products using “galleryImages” . Images are key to attract travellers and boost bookings. For each imported image, please precise title, url and order.
Image with order “0” will be used as thumbnail image and pre-processed on Amadeus Discover side for a performant display.
JSON format looks like :
“galleryImages”: [
{
“title”: “string”,
“url”: “string”,
“order”: 0
}
],
…
Product opening days, hours, slots#
At the moment a product is pushed to Amadeus Discover platform, static elements about product opening hours / days / existing slots can be defined to better identify when it is relevant for travelers,
Live availability will need to be checked later in the booking flow, but this first static level of information allows already the traveler to identify on which days, dates, hours the activity exists and could be available.
Based upon Octo standard, our products hold a field “availabilityType” to define if a product would be typed as OPENING_HOURS (typically used for a shop or a restaurant) or START_TIME (typically used for an event such as a concert on christmas night).
The 1st way is a classical opening hours for typically a restaurant, or a shop (this reflects Octo “availabilityType”: “OPENING_HOURS”)
The 2nd way is the event like type, typically for concert / opera event (this reflects Octo “availabilityType”: “START_TIME”)
Example for a restaurant
Let’s consider a restaurant, easy case let’s say the restaurant is open all year, from tuesday to saturday from 10:00 to 23:00 and closed on sunday and monday as in the calendar:
Here we will define product.availabilityPeriods input as 1 opening weeklyPeriods with the following JSON:
Restaurant example opening period
"availabilityType": "OPENING_HOURS",
"availabilityPeriods": {
"weeklyPeriods": [
{
"description": "Open all year - Tuesday to saturday",
"startDate": "2023-01-01",
"endDate": "2023-12-31",
"sunday": { "open": false, "hours": null },
"monday": { "open": false, "hours": null },
"tuesday": { "open": true, "hours": [ [ "T1000", "T2300" ] ] },
"wednesday": { "open": true, "hours": [ [ "T1000", "T2300" ] ] },
"thursday": { "open": true, "hours": [ [ "T1000", "T2300" ] ] },
"friday": { "open": true, "hours": [ [ "T1000", "T2300" ] ] },
"saturday": { "open": true, "hours": [ [ "T1000", "T2300" ] ] },
}
]
}
Example for an diving centre
Let’s dive into a more complex case like a diving centre, let’s say the centre is open during spring time may & june all day on saturdays only from 12:00 to 17:00, and in summer time july & august every days all days and all day with 2 exceptions as closing days like national day 14th july (France) and 15th august as in the calendar:
Here we will define product.availabilityPeriods input as 2 opening weeklyPeriods and then declare the 14th July and 15th August in the closedDayList:
Diving centre example opening periods with closing periods
"availabilityType": "OPENING_HOURS",
"availabilityPeriods": {
"weeklyPeriods": [
{
"description": "Spring time opening on saturdays",
"startDate": "2023-05-06",
"endDate": "2023-06-24",
"sunday": { "open": false, "hours": null },
"monday": { "open": false, "hours": null },
"tuesday": { "open": false, "hours": null },
"wednesday": { "open": false, "hours": null },
"thursday": { "open": false, "hours": null },
"friday": { "open": false, "hours": null },
"saturday": { "open": true, "hours": [ [ "T1200", "T1700" ] ] }
},
{
"description": "Summertime opening",
"startDate": "2023-07-01",
"endDate": "2023-08-31",
"sunday": { "open": true, "hours": null },
"monday": { "open": true, "hours": null },
"tuesday": { "open": true, "hours": null },
"wednesday": { "open": true, "hours": null },
"thursday": { "open": true, "hours": null },
"friday": { "open": true, "hours": null },
"saturday": { "open": true, "hours": null },
"closedDayList": ["2023-07-14", "2023-08-15"]
}
]
}
Note
Implicit rules description for weeklyPeriods
Multiple object in weeklyPeriods can exist yet they cannot overlap each others
“closedDayList” must be enclosed in between startDate & endDate - can be null or empty
“startDate” is mandatory ISO 8601
“endDate” is optional ISO 8601 - can be null → means open until endoftime.
“endDate” must be after the “startDate”
“sunday” –> “saturday” fields must all exist with the following conditions:
subfield “open”, a boolean, must be set at TRUE OR FALSE - cannot be null
subfield “hours” (ISO 8601 time only) matrix [ [ start-time , end-time ], [ …, … ], ] - can be fully or partially fed as:
Valid Ex : [ “T1200”, “T2100” ] - Means open from 12:00 to 21:00
Valid Ex : [ “T1200”, null ] - Means open from 12:00, no info on the closing time
Valid Ex : null - Means we have no info
Valid Ex : [ [“T1200”, “T2100” ], [“T2200”, null ] ] - Means opens from 12:00 to 21:00 and after 22:00
Invalid Ex (Time spans must not overlap each other) : [ [“T1200”, “T2100” ], [“T1400”, “T1500” ] ]
Example for an opera / concert / theatre event
Let’s consider an opera event, let’s say opera performances will take place the 2 first weeks of august wednesday to sunday starting at 20:00 and one special night on 31st august with 2 performances: at 19:00 and at 23:00.
Here we will define product.availabilityPeriods input with 1 entry as spontaneousPeriod as in the follwing JSON:
Opera example opening period
"availabilityType": "START_TIME",
"availabilityPeriods": {
"spontaneousPeriod": {
"description": "Opera 2 weeks performance and Special 31st august night",
"eventDateList": [
"2023-08-02T20:00", "2023-08-03T20:00", "2023-08-04T20:00", "2023-08-05T20:00", "2023-08-06T20:00",
"2023-08-09T20:00", "2023-08-10T20:00", "2023-08-11T20:00", "2023-08-12T20:00", "2023-08-13T20:00",
"2023-08-31T19:00", "2023-08-31T23:00" ]
}
}
Note
Implicit rules description for spontaneousPeriod
Only one ‘spontaneousPeriod’ JSON object can exist - independent from another “weeklyPeriods” object if any exist.
“eventDateList”: [“20230111T07:00”, “2023-01-12T07:40”, “2023-01-12T09:40”, “20230113”], defined as an array[n] of DateTime ISO 8601
Must be date or datetime ISO 8601 - cannot hold duplicates - cannot be null or empty
Nice to have elements to boost product visibility#
Categories (impact rate : x/5) RESTAURANTS + list
Activity duration (impact rate : x/5)
Price – pricing unit (impact rate : x/5)
Website (impact rate : x/5)
Ratings
GO LIVE on production DB#
You can now replicate the steps as validated in Sandbox to import your catalogue in our Production environment.
You may access the list of your active products via the following endpoint : GET/api/products
You may access the list of your suppliers via the following endpoint : GET /api/suppliers
You now need to implement appropriate processes to keep your catalogue up to date.
Create new products
Update products
Deprecate a product (make it unavailable)
Undeprecate a product (make it available)
Delete a product