> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Booking Listings API

> Booking.com property listings: price, guest score, rooms, facilities, photos, location and operator info. By destination search or hotel URL.

`POST /v1/data/booking/listings/run`

**Pricing:** $0.002 per listing ($2.00 per 1,000).

## Ways to call it

* **Search**: set `location` (optional: `checkIn`, `checkOut`, `maxResults`, `currency`, `language`, `propertyType`, `starsCountFilter`, `minScore`, ...)
* **URL**: set `urls` (optional: `checkIn`, `checkOut`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**location** `string`

By Search: a destination or search keyword (city, region, landmark, or area), e.g. "Paris" or "Bali villas".

**checkIn** `date`

Check-in date (YYYY-MM-DD). Required for price and room availability; omit it and price/room columns come back empty.

Use together with `checkout`.

**checkOut** `date`

Check-out date (YYYY-MM-DD). Required alongside check-in for pricing.

Use together with `checkin`.

**maxResults** `integer`

Maximum number of listings to return. Use 0 for all.

**propertyType** `string`

Filter to a property type (Hotels, Apartments, Villas, Guest houses, Hostels, B\&Bs, Resorts, Homestays).

**starsCountFilter** `string`

Filter to properties with at least this official star class (1-5).

**minScore** `number`

Filter to properties with at least this guest score (0-10, e.g. 8.5).

**minMaxPrice** `string`

Nightly/total price range for the searched dates, as min and max in the chosen currency (e.g. 150 to 400).

**sortBy** `string`

Result sort order (defaults to relevance).

**currency** `string` (default: USD)

Currency for prices (EUR, USD, GBP, JPY, INR, MXN, AUD, CAD, …).

**language** `string` (default: en-gb)

Language/locale for the property data.

**urls** `string[]`

By URL: Booking.com hotel URLs or search-page URLs. Add check-in/check-out dates for price and room availability.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/booking/listings/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "location": "Paris",
    "checkIn": "2026-12-17",
    "checkOut": "2026-12-19",
    "maxResults": 12,
    "currency": "EUR"
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/booking/listings/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "location": "Paris",
    "checkIn": "2026-12-17",
    "checkOut": "2026-12-19",
    "maxResults": 12,
    "currency": "EUR"
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/booking/listings/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "location": "Paris",
  "checkIn": "2026-12-17",
  "checkOut": "2026-12-19",
  "maxResults": 12,
  "currency": "EUR"
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one listing, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `propertyName` | Property Name | text |
| `propertyUrl` | Property URL | text |
| `propertyId` | Property ID | text |
| `propertyType` | Property Type | text |
| `starRating` | Star Rating | number |
| `city` | City | text |
| `country` | Country | text |
| `fullAddress` | Full Address | text |
| `latitude` | Latitude | number |
| `longitude` | Longitude | number |
| `guestScore` | Guest Score | number |
| `scoreLabel` | Score Label | text |
| `reviewCount` | Review Count | number |
| `categoryScores` | Category Scores | object\_array |
| `priceFrom` | Price From | number |
| `currency` | Currency | text |
| `rooms` | Rooms | object\_array |
| `roomTypes` | Room Types | object\_array |
| `mainImage` | Main Image | text |
| `images` | Images | array |
| `facilities` | Facilities | object\_array |
| `description` | Description | text |
| `highlights` | Highlights | object\_array |
| `checkInTime` | Check-in Time | text |
| `checkOutTime` | Check-out Time | text |
| `policies` | Policies | object\_array |
| `finePrint` | Fine Print | text |
| `surroundings` | Surroundings | object |
| `traderInfo` | Trader Info | object |
| `licenseNumbers` | License Numbers | array |
| `host` | Host | object |
| `mapUrl` | Map URL | text |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "booking/listings",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "propertyId": 12860775,
      "starRating": 4,
      "city": "Paris",
      "images": [
        "https://cf.bstatic.com/xdata/images/hotel/max1024x768/643994365.jpg?k=f8bbf62acd47a298194f6eec4eba3984bda9d28a997d59db5006738ff15c7b05&o=&hp=1",
        "https://cf.bstatic.com/xdata/images/hotel/max1024x768/807118342.jpg?k=a799076578867a6b1c2834cbcfa937c8ef96ff1118eb87fc5735333eba830c46&o=&hp=1"
      ],
      "reviewCount": 617,
      "guestScore": 9.4,
      "surroundings": {
        "transport": [
          {
            "name": "Division Leclerc - Wallon",
            "category": "Bus Stations",
            "distance": "7 mi",
            "driveTime": "20 min"
          },
          {
            "name": "Cosmonautes",
            "category": "Bus Stations",
            "distance": "7 mi",
            "driveTime": "20 min"
          },
          {
            "name": "Auber RER Station",
            "category": "Rail Stations",
            "distance": "2,600 ft",
            "driveTime": "3 min"
          }
        ],
        "airports": [
          {
            "name": "Paris - Orly Airport",
            "category": "Airports",
            "distance": "8 mi",
            "driveTime": "26 min"
          },
          {
            "name": "Paris - Charles de Gaulle Airport",
            "category": "Airports",
            "distance": "11 mi",
            "driveTime": "25 min"
          },
          {
            "name": "Beauvais–Tillé Airport",
            "category": "Airports",
            "distance": "40 mi",
            "driveTime": "57 min"
          }
        ],
        "dining": [
          {
            "name": "Heretea",
            "category": "Cafes, Coffee and Tea Houses",
            "distance": "450 ft",
            "driveTime": "1 min"
          },
          {
            "name": "Starbucks",
            "category": "Cafes, Coffee and Tea Houses",
            "distance": "700 ft",
            "driveTime": "1 min"
          },
          {
            "name": "Bondi",
            "category": "Bars",
            "distance": "850 ft",
            "driveTime": "1 min"
          }
        ],
        "landmarks": [
          {
            "name": "Synagogue De La Rue Buffault",
            "category": "Historic and Protected Sites",
            "distance": "900 ft",
            "driveTime": "2 min"
          },
          {
            "name": "Église Notre-dame De Lorette",
            "category": "Historic and Protected Sites",
            "distance": "750 ft",
            "driveTime": "1 min"
          },
          {
            "name": "Grévin Museum",
            "category": "Museums",
            "distance": "850 ft",
            "driveTime": "1 min"
          }
        ]
      },
      "checkOutTime": "Until 12:00",
      "licenseNumbers": null,
      "propertyUrl": "https://www.booking.com/hotel/fr/madame-drouot-amp-spa-opera.html",
      "rooms": [
        {
          "id": 1286077501,
          "roomType": "Standard Double Room",
          "persons": 2,
          "available": true,
          "roomsLeft": 7,
          "beds": "1 large double bed",
          "priceFrom": 809.44,
          "currency": "EUR",
          "freeCancellation": true,
          "facilities": [
            "City view",
            "Air conditioning",
            "Ensuite bathroom"
          ]
        },
        {
          "id": 1286077507,
          "roomType": "Superior Double Room",
          "persons": 2,
          "available": true,
          "roomsLeft": 2,
          "beds": "1 large double bed",
          "priceFrom": 862.45,
          "currency": "EUR",
          "freeCancellation": true,
          "facilities": [
            "172 feet²",
            "City view",
            "Air conditioning"
          ]
        }
      ],
      "finePrint": "This property will not accommodate hen, stag or similar parties.A damage deposit of € 200 is required on arrival. This will be collected by credit card. You ...",
      "mapUrl": "https://www.google.com/maps?q=48.873954,2.3405447",
      "mainImage": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/643994365.jpg?k=f8bbf62acd47a298194f6eec4eba3984bda9d28a997d59db5006738ff15c7b05&o=",
      "propertyName": "Madame Drouot & Spa - Opera",
      "country": "France",
      "checkInTime": "15:00–23:00",
      "traderInfo": {
        "companyName": "SEEK PROPERTIES",
        "email": "bonjour@hotelmadamedrouot.com",
        "phone": "+33621961211",
        "registrationNumber": "389693508",
        "tradeRegisterName": "RCS PARIS",
        "street": "86 rue d'Assas",
        "city": "Paris",
        "postalCode": "75006",
        "countryCode": "FR",
        "state": "FRANCE"
      },
      "description": "You might be eligible for a Genius discount at Madame Drouot & Spa - Opera. To check if a Genius discount is available for your selected dates sign in.\n\n\nGen...",
      "longitude": 2.3405447,
      "facilities": [
        {
          "group": "Great for your stay",
          "items": null
        },
        {
          "group": "Bathroom",
          "items": [
            "Toilet paper",
            "Towels",
            "Towels/sheets (extra fee)"
          ]
        }
      ],
      "priceFrom": 809.44,
      "policies": [
        {
          "title": "Check-in",
          "content": "From 15:00 to 23:00"
        },
        {
          "title": "Check-out",
          "content": "Until 12:00"
        }
      ],
      "propertyType": "Hotel",
      "highlights": [
        {
          "header": "Perfect for a 2-night stay!",
          "text": "Situated in the best rated area in Paris, this hotel has an excellent location score of 9.6"
        },
        {
          "header": "Breakfast info",
          "text": "Continental, Vegetarian, Gluten-free, American"
        }
      ]
    }
  ]
}
```

## Related APIs

For review text use [`booking/reviews`](https://docs.mindcase.co/apis/booking/reviews); for prices across booking sites use [`google-hotels/hotels`](https://docs.mindcase.co/apis/google-hotels/hotels).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.