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.
Step 1 : Import suppliers#
/api/supplier) endpoint to create suppliers.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
Supplier contact
Step 2 : Import products for suppliers#
Guidelines for Products Quality#
Products granularity#
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#
Product title and description#
ALENTOUR / DISCOVER Channel#
Booking URL#
Booking Engine#
Online_Bookable#
Price the product#
Images#
Product opening days, hours, slots#
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”)
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" ] ] },
}
]
}
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
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” ] ]
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
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
Product itinerary#
product.itinerary field can be used to describe how an experience unfolds.a simple activity with one or more steps,
a multi-day circuit,
hop-on hop-off routes,
or a free-text itinerary when a fully structured breakdown is not available.
Structured itinerary: use
type+unitType+ orderedunitsanditems.Unstructured itinerary: use
type = UNSTRUCTURED+unstructuredItinerary. (NOT RECOMMENDED)
PT2H30M or P2D./n separator.Global structure
"itinerary": {
"type": "STANDARD",
"unitType": "ITEM",
"duration": "PT4H",
"foodMenus": {
"en": "Seasonal tasting menu available on request"
},
"units": [
{
"number": 1,
"title": {
"en": "Main itinerary"
},
"description": {
"en": "The guest follows the experience in the order described below."
},
"duration": "PT4H",
"items": [
{
"number": 1,
"title": {
"en": "Meet your guide"
},
"description": {
"en": "Meet 15 minutes before departure."
},
"types": ["START", "ITINERARY_ITEM"],
"duration": "PT15M",
"stop": true,
"location": {
"externalId": "meeting-point",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAmeetingpoint",
"name": { "en": "Tourist Office Meeting Point" },
"latitude": 48.8602,
"longitude": 2.3417,
"postalAddress": {
"formattedAddress": { "en": "2 Rue de Rivoli, 75001 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAmeetingpoint",
"internalPoi": "poi-meeting-point"
}
}
}
]
}
]
}
Different itinerary types#
STANDARD: Use this for most experiences where the itinerary is a simple ordered list of steps.MULTIDAY: Use this when the itinerary is naturally broken down into several days. In that case, usingunitType = DAYis recommended.HOP_ON_HOP_OFF: Use this for route-based products such as sightseeing buses or boats. In that case, usingunitType = ROUTEis recommended.UNSTRUCTURED: Use this when you want to expose a localized free-text itinerary instead of a structured list of units and items.
Ordering#
itinerary.units[0]is the first unit,itinerary.units[1]is the second unit,and so on.
items are also read in sequence:itinerary.units[0].items[0]is the first step of the first unit,itinerary.units[0].items[1]is the second step of the first unit,etc.
number starting at 1.Food and accommodation fields#
foodMenus(itinerary level) is expected forSTANDARDorUNSTRUCTUREDitineraries.foodAndDrinks(unit level) is expected only forMULTIDAYitineraries.accommodations(unit level) is expected only forMULTIDAYitineraries.
Note
For
HOP_ON_HOP_OFFitineraries, do not usefoodAndDrinksoraccommodationsat unit level.For non-
MULTIDAYstructured itineraries, keep unit-level meal/accommodation details empty.
Location types for itinerary items#
The types array can contain one or several values among:
START: start point of the unit. Must be combined withITINERARY_ITEM.END: end point of the unit. Must be combined withITINERARY_ITEM.REDEMPTION: location where the traveler redeems the ticket or voucher.POINT_OF_INTEREST: notable place visited or seen during the experience.ITINERARY_ITEM: basic itinerary step.
Location structure#
"location": {
"externalId": "louvre-pyramid",
"provider": "GOOGLE",
"providerReference": "ChIJb8Jg9pRu5kcRj7p1x6mG2WQ",
"name": {
"en": "Louvre Pyramid"
},
"latitude": 48.860611,
"longitude": 2.337644,
"postalAddress": {
"formattedAddress": {
"en": "Cour Napoléon, 75001 Paris, France"
},
"city": {
"en": "Paris"
},
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJb8Jg9pRu5kcRj7p1x6mG2WQ",
"internalPoi": "poi-001"
}
}
Note
providerReferencemust not be sent withoutprovider.If
identifiersalready contains the same key asprovider, then its value must matchproviderReference.identifiersmay be used to keep references coming from several external systems.
Examples by itinerary type#
1) Standard itinerary
unitType: ITEM.Example - guided city tour
"itinerary": {
"type": "STANDARD",
"unitType": "ITEM",
"duration": "PT3H",
"units": [
{
"number": 1,
"title": { "en": "Tour itinerary" },
"items": [
{
"number": 1,
"title": { "en": "Meet the guide" },
"types": ["START", "ITINERARY_ITEM"],
"duration": "PT15M",
"location": {
"externalId": "meeting-point",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAmeetingpoint",
"name": { "en": "Tourist Office Meeting Point" },
"latitude": 48.8602,
"longitude": 2.3417,
"postalAddress": {
"formattedAddress": { "en": "2 Rue de Rivoli, 75001 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAmeetingpoint",
"internalPoi": "poi-meeting-point"
}
}
},
{
"number": 2,
"title": { "en": "Cathedral visit" },
"types": ["POINT_OF_INTEREST", "ITINERARY_ITEM"],
"stop": true,
"admissionIncluded": true,
"duration": "PT45M",
"location": {
"externalId": "cathedral",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAcathedral",
"name": { "en": "Notre-Dame Cathedral" },
"latitude": 48.8530,
"longitude": 2.3499,
"postalAddress": {
"formattedAddress": { "en": "6 Parvis Notre-Dame - Pl. Jean-Paul II, 75004 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75004",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAcathedral",
"internalPoi": "poi-cathedral"
}
}
},
{
"number": 3,
"title": { "en": "Tour ends at the market square" },
"types": ["END", "ITINERARY_ITEM"],
"location": {
"externalId": "market-square",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAmarketsquare",
"name": { "en": "Market Square" },
"latitude": 48.8566,
"longitude": 2.3522,
"postalAddress": {
"formattedAddress": { "en": "Place du Marche, 75004 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75004",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAmarketsquare",
"internalPoi": "poi-market-square"
}
}
}
]
}
]
}
2) Multi-day itinerary
unitType: DAY.Example - 2-day excursion
"itinerary": {
"type": "MULTIDAY",
"unitType": "DAY",
"duration": "P2D",
"units": [
{
"number": 1,
"title": { "en": "Day 1 - Arrival and discovery" },
"duration": "P1D",
"foodAndDrinks": { "en": "Dinner included" },
"accommodations": { "en": "4-star hotel" },
"items": [
{
"number": 1,
"title": { "en": "Hotel check-in" },
"types": ["START", "ITINERARY_ITEM"],
"location": {
"externalId": "hotel-checkin",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAhotelcheckin",
"name": { "en": "Hotel Reception" },
"latitude": 48.8652,
"longitude": 2.3215,
"postalAddress": {
"formattedAddress": { "en": "10 Avenue de l'Opera, 75001 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAhotelcheckin",
"internalPoi": "poi-hotel-checkin"
}
}
},
{
"number": 2,
"title": { "en": "Sunset walking tour" },
"types": ["ITINERARY_ITEM", "POINT_OF_INTEREST"],
"duration": "PT2H",
"location": {
"externalId": "old-town",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAoldtown",
"name": { "en": "Old Town District" },
"latitude": 48.8581,
"longitude": 2.3470,
"postalAddress": {
"formattedAddress": { "en": "Quartier Historique, 75004 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75004",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAoldtown",
"internalPoi": "poi-old-town"
}
}
}
]
},
{
"number": 2,
"title": { "en": "Day 2 - Main highlights" },
"duration": "P1D",
"items": [
{
"number": 1,
"title": { "en": "Breakfast at the hotel" },
"types": ["ITINERARY_ITEM"],
"location": {
"externalId": "hotel-restaurant",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAhotelrestaurant",
"name": { "en": "Hotel Restaurant" },
"latitude": 48.8653,
"longitude": 2.3217,
"postalAddress": {
"formattedAddress": { "en": "10 Avenue de l'Opera, 75001 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAhotelrestaurant",
"internalPoi": "poi-hotel-restaurant"
}
}
},
{
"number": 2,
"title": { "en": "Departure" },
"types": ["END", "ITINERARY_ITEM"],
"location": {
"externalId": "hotel-checkout",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAhotelcheckout",
"name": { "en": "Hotel Check-out Desk" },
"latitude": 48.8652,
"longitude": 2.3216,
"postalAddress": {
"formattedAddress": { "en": "10 Avenue de l'Opera, 75001 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAhotelcheckout",
"internalPoi": "poi-hotel-checkout"
}
}
}
]
}
]
}
3) Hop-on hop-off itinerary
unitType: ROUTE.Example - sightseeing bus
"itinerary": {
"type": "HOP_ON_HOP_OFF",
"unitType": "ROUTE",
"duration": "PT1H45M",
"units": [
{
"number": 1,
"title": { "en": "Red route" },
"description": { "en": "Historic center loop" },
"items": [
{
"number": 1,
"title": { "en": "Central station" },
"types": ["START", "ITINERARY_ITEM"],
"stop": true,
"location": {
"externalId": "stop-central-station",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAcentralstation",
"name": { "en": "Central Station Stop" },
"latitude": 48.8440,
"longitude": 2.3748,
"postalAddress": {
"formattedAddress": { "en": "Place de la Gare, 75012 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75012",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAcentralstation",
"internalPoi": "poi-stop-central-station"
}
}
},
{
"number": 2,
"title": { "en": "Museum district" },
"types": ["POINT_OF_INTEREST", "ITINERARY_ITEM"],
"stop": true,
"location": {
"externalId": "stop-museum-district",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAmuseumdistrict",
"name": { "en": "Museum District Stop" },
"latitude": 48.8608,
"longitude": 2.3266,
"postalAddress": {
"formattedAddress": { "en": "Rue du Musee, 75001 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75001",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAmuseumdistrict",
"internalPoi": "poi-stop-museum-district"
}
}
},
{
"number": 3,
"title": { "en": "Central station" },
"types": ["END", "ITINERARY_ITEM"],
"location": {
"externalId": "stop-central-station",
"provider": "GOOGLE",
"providerReference": "ChIJAQAAcentralstation",
"name": { "en": "Central Station Stop" },
"latitude": 48.8440,
"longitude": 2.3748,
"postalAddress": {
"formattedAddress": { "en": "Place de la Gare, 75012 Paris, France" },
"city": { "en": "Paris" },
"zipCode": "75012",
"countryCode": "FR"
},
"identifiers": {
"GOOGLE": "ChIJAQAAcentralstation",
"internalPoi": "poi-stop-central-station"
}
}
}
]
}
]
}
4) Unstructured itinerary
units.Example - unstructured itinerary
"itinerary": {
"type": "UNSTRUCTURED",
"duration": "PT8H",
"unstructuredItinerary": {
"en": "Meet your guide at 08:30./nDeparture at 09:00 for the vineyard./nGuided tasting before lunch./nReturn to the city center around 17:00.",
"fr": "Rendez-vous avec votre guide à 08:30./nDépart à 09:00 pour le vignoble./nDégustation guidée avant le déjeuner./nRetour au centre-ville vers 17:00."
},
"foodMenus": {
"en": "Wine tasting and lunch included"
}
}
Validation rules#
Note
itineraryis optional.If
type = UNSTRUCTURED, thenunstructuredItineraryis required andunitsmust not be sent.If
typeis anything other thanUNSTRUCTURED, thenunitsis required andunstructuredItinerarymust not be sent.unitsmust contain at least 1 entry when used.Each unit must contain at least 1 item.
durationis optional at itinerary, unit and item levels, but when present it must be a valid ISO 8601 duration.
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#
Create new products
Update products
Deprecate a product (make it unavailable)
Undeprecate a product (make it available)
Delete a product