Experience authentic Spanish culture at Teatro Flamenco Madrid...", "galleryImages": [ { "url": "https://...", "order": 1 } ], "minPrice": 44.0, "maxPrice": 44.0, "priceCurrency": "EUR", "bookingUrl": "https://...", "geoLocation": { "latitude": 40.4231478, "longitude": -3.7044556, "geoHash": "ezjmgwy3zu" }, "rating": 4.7133756, "numberOfRatings": 471 } ``` Read [`references/product-schema.md`](references/product-schema.md) if the app needs a per-call search identifier or shows opening hours, cancellation policy, duration, languages or classification. For a specific field, search that file by its exact name, then read the containing section for related fields and constraints. ## Examples ### Example 1: "Things to do" landing page for a city Developer asks: *"Build a 'Things to do' landing page for a city."* Implementation: 1. Call top activities as in the quick start, with the page's city as `cityName`. 2. Render a card grid with `title`, `galleryImages[0].url` as the photo, `minPrice` + `priceCurrency`, and a short excerpt of the sanitized `description`. 3. Call to action: open `bookingUrl` in a new tab. Result: a generic top activities feed for the city. ### Example 2: Personalized recommendations Developer asks: *"Add personalized experience recommendations to my app."* Implementation: 1. For a worked example, a couple in Madrid on leisure who like food, art and live music, with a €20-€150 budget: send the recommended-products quick-start body, adding `"tripContext": "leisure"`. 2. Render the response as a card grid, sanitizing `description`. Result: a personalized recommendation feed. ### Example 3: Similar-products carousel Developer asks: *"Add a carousel of experiences similar to the one being viewed."* Implementation: 1. Call recommended products with `recommendationFilters.title` set to the viewed product's title and no `interests`, plus the same destination. For a worked example, `{ "iataCode": "MAD", "title": "Teatro Flamenco Madrid: Live the Flamenco Experience" }` returns other flamenco shows, such as Corral de la Morería and Café Ziryab, among other Madrid highlights. 2. Drop the viewed product from the results by `productId` - the seed itself comes back. Result: a "similar to" carousel. ### Example 4: Activity detail page Developer asks: *"Build a detail page for an activity a user favourited earlier."* Implementation: 1. Look up the favourite's stored `productId` and call get product with it. 2. Treat a `404` as "no longer available", separately from other errors. 3. Render the sanitized description, gallery images and opening hours (`availabilityPeriods` - see the product schema). 4. Call to action: open `bookingUrl`. Result: a single-product detail view driven entirely by `productId`. ## Things to get right - **Locate a search by coordinates, IATA code or city name - and the two search endpoints spell them differently.** Top activities takes query parameters `lat`+`lon`, `iataCode` and `cityName`; recommended products takes body fields `geoLocation`, `iataCode` and `city` inside `recommendationFilters`. Top activities ignores unknown query parameters, including the body names, so a call relying on them alone returns 400 `6043`. Coordinates are a complete way to locate the search, not a refinement of a city. When several locators are sent, the API picks by priority without erroring - coordinates, then `iataCode`, then city name. - **Top activities caps `maxRecommendations` at 10** - higher values return `400`, while recommended products accepts up to 1000. A feed that needs more than 10 uses recommended products. - **Use `productId` for product identity; `id` and `productId` are not interchangeable.** Do not read or store `id` unless the app specifically needs to reference an individual search response. For favourites, caches, links and deduplication, use only `productId`; omit products missing it, never fall back to another field. - **Narrow results with `interests`, not `categories`, unless the user wants a strict category.** Many products aren't filed under any `activities-*` category, so `categories` silently drops them; free-form `interests` has no such gap. Keep `interests` to 1-3 focused phrases - recommendation quality degrades as the list grows. - **`title` (similar-products mode) is ignored when `interests` is set**, so send it without `interests`. - **`Accept-Language` selects translated text on all three endpoints.** Without it, text defaults to English; an unavailable translation falls back to English. Translation can be partial, so `displayedLanguage` doesn't guarantee every text field is in that language. - **Product fields are supplier data and can be missing or inconsistent** - e.g. `categories` can say `no_category` while `taxonomies` files the product under Culture. - **New or sparsely described products rank low** - one can sit far beyond the default 10 results, so finding a specific product needs a larger `maxRecommendations` on recommended products. - **Sanitize `description` before it reaches the DOM.** It can contain supplier-authored HTML, so injecting it raw is an XSS vector. - **Images come from `galleryImages[].url`**, sorted by `order`. `thumbnailImage` is a bare UUID, not a URL. - **There is no `shortDescription`** - use a truncated, sanitized `description` for teasers. - **Stop at `bookingUrl` for booking.** Redirect the user there; the booking engine takes over. ## Errors Codes shared by all three endpoints. Codes specific to a search endpoint are listed in its reference. | HTTP | Meaning | | --- | --- | | 400 | Payload or parameter validation failure. | | 401 | Missing, malformed or unrecognized `X-API-Key`. | | 403 | Forbidden. | | 404 | On get product: the `productId` doesn't exist or is no longer available. | | 429 | Rate limit for the API key exceeded. | | 500 | Internal server error. | ## Troubleshooting ### 400 / 404 - code 6025 or 6056, destination not found **Cause:** The destination isn't known (6025) or isn't covered (6056). On top activities, 6025 also means a non-English `cityName` (`Wien`, `München`). **Solution:** Send the English city name. Otherwise it means no activities for that destination, not a failure; a nearby larger city or coordinates may have results. ### 200 with an empty array **Cause:** On recommended products, the destination resolved but the filters matched nothing. Top activities never returns `[]`. **Solution:** Handle `[]` as an empty state, and try a nearby larger city or coordinates with a `radius`. ## Related skills These are part of the same `amadeus-travel-builder` plugin - if one isn't available in your environment, its source lives alongside this one at https://github.com/AmadeusITGroup/amadeus-travel-toolkit/tree/main/plugins/amadeus-travel-builder/skills. - [city-search](../city-search/SKILL.md) - to power a destination picker that feeds this search: it covers airport-less destinations (resort towns, small coastal towns) that a hotel-concierge or "things to do" feature needs just as much as airport-served cities. For such a town, pass its coordinates (`lat`/`lon` or `geoLocation`) with a small `radius` - its name or code returns a wider regional list. - [airport-city-search](../airport-city-search/SKILL.md) - an alternative picker when the app already has one for flight search and you want to reuse it, though it returns almost only airport-served cities.