Attractions quick guide 3.2 Beta

Enable travellers to find, compare, and view attractions with key details such as name, description, and pricing..

This quick guide shows the minimum steps needed to integrate the Demand API attractions endpoints.

Before you start

Before testing the endpoints, make sure you have been granted access to this Beta-pilot programme (Contact your Account Manager)

You’ll need:

✓ A valid API key token.
✓ Your X-Affiliate-Id
✓ Open the try out console.

Steps

1. Search for attractions

→ Use the attractions/search endpoint to attractions available in your selected area and dates.

Use case: A traveller searches for popular attractions in Amsterdam between 18–20 December 2025.

Example request per country:

{
  "currency": "EUR", // This is mandatory
  "cities": [2140479],
  "countries": ["nl"],
  "dates": {
    "start_date": "2025-12-18",
    "end_date": "2025-12-20"
  },
  "filters": {
    "rating": {
      "minimum_review_score": 4.2,
      "minimum_review_count": 100
    },
  },
  "rows": 20,
  "sort": {
    "by": "most_popular"
  }
}

Example response:

{
  "data": [
    {
      "id": "PRahAzWtTraa",
      "free_cancellation": true,
      "price": {
        "currency": "EUR",
        "total": 20
      },
      "url": {
        "web": "https://www.booking.com/attractions/nl/prahazwttraa-heineken-experience-amsterdam.en-gb.html"
      }
    },
    {
      "id": "PRAmdacCwQLH",
      "free_cancellation": false,
      "price": {
        "currency": "EUR",
        "total": 15.5
      },
      "url": {
        "web": "https://www.booking.com/attractions/nl/pramdaccwqlh-madame-tussauds-ticket.en-gb.html"
      }
    }
  ],
  "metadata": {
    "total_results": 128
  },
  "request_id": "01fr9ez700exycb98w90w5r9sh"
}

The response includes:

• A list of atractions.
• Whether free cancellation is available.
• Pricing information (in the requested currency)
• A URL to the Booking.com attractions page.

→ Try it yourself

2. Retrieve attraction details

→ Use the /attractions/details endpoint to get static details about specific attractions (in this case, PRahAzWtTraa) — including name, description, location, categories, photos, and ratings.

Example request:

{
  "attractions": ["PRahAzWtTraa"],
  "languages": ["en-gb"]
}

→ Try it yourself

Example response:

The response contains all the information about the selected attraction including contact information, name, score/reviews, etc.

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": "PRahAzWtTraa",
      "name": "Heineken Experience Amsterdam",
      "categories": ["food_drinks"],
      "duration": "PT2H",
      "badges": ["best_seller"],
      "photos": [
        {
          "url": "https://cf.bstatic.com/xdata/images/xphoto/500x375/170335205.jpg"
        }
      ],
      "locations": [
        {
          "address": "Stadhouderskade 78",
          "city": 2140479,
          "country": "nl",
          "coordinates": {
            "latitude": 52.360043,
            "longitude": 4.885177
          },
          "type": "attraction"
        }
      ],
      "long_description": "Discover the history of Heineken and enjoy a behind-the-scenes interactive experience in Amsterdam’s original brewery.",
      "ratings": {
        "number_of_reviews": 3250,
        "score": 4.8
      },
      "supported_languages": ["en-gb", "nl"],
      "url": {
        "web": "https://www.booking.com/attractions/nl/prahazwttraa-heineken-experience-amsterdam.en-gb.html"
      }
    }
  ]
}

The response provides static content such as:

• Attraction name and description.
• Duration and categories.
• Location details (address, coordinates, city).
• Photos and supported languages.
• Rating data.

3. Redirect to Booking.com

Each attraction response includes a direct url (web and app) that you can use to redirect travellers to Booking.com to complete their booking.

Example:

"url": {
  "app": "booking://attractions/product?slug=prahazwttraa-heineken-experience-amsterdam&aid=956509",
  "web": "https://www.booking.com/attractions/nl/prahazwttraa-heineken-experience-amsterdam.en-gb.html?selected_currency=EUR&aid=956509"
}

4. Retrieve next page results

If your initial /attractions/search response includes a metadata.next_page token, use it to fetch the next set of results.

{
  "next_page": "eyJwYWdlIjoyfQ=="
}

Each subsequent call returns:

• The next rows of results.
• An updated next_page token (if more results are available)
• Repeat until the next_page field is no longer returned.

Summary

Best practices

• Always include your API key token and X-Affiliate-Id in every request.
• Use the correct data conventions in your requests to avoid errors.
• Store static location data (cities, countries, etc) to reduce API calls.

Troubleshooting

Here are some common issues you might encounter when testing the Attractions endpoints.

Missing or invalid required fields

If a required field such as currency or cities is missing or invalid, the API returns a 400 Bad Request error.

Example response:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The 'currency' field is required."
  },
  "request_id": "01hrp9d99wz7dwh1z7nv67j5c9"
}

✅ Fix: Include the missing parameter.

Invalid pagination token

If you send an expired or malformed next_page value, the API returns a 400 Bad Request error.

Example response:

{
  "error": {
    "code": "INVALID_NEXT_PAGE",
    "message": "The provided next_page token is invalid or expired."
  },
  "request_id": "01hrp9db6bn49sp8stnt8kr09q"
}

✅ Fix: Restart the search without a next_page token to generate a fresh pagination sequence.

No results found

If your filters are too restrictive or the location has no matching attractions, you’ll receive an empty data array.

Example response:

{
  "data": [],
  "metadata": {
    "total_results": 0
  },
  "request_id": "01hrp9f89gzfwdw5bt4x40wrta"
}

✅ Fix: Broaden your filters (for example, reduce minimum_review_score or remove supported_languages).

Still not working?

If the issue persists:

• Check your X-Affiliate-Id and authentication header.
• Review the Client error codes and examples.
• Ensure your request body is valid JSON and uses UTF-8 encoding.
• Use the Try-out console to test your payload interactively.

Next steps

Congratulations, by now you know the basics of how to use the key attractions endpoints for the Search and look flow!