# Booking Listings

Get Booking.com property listing records — price, guest score, rooms, facilities, photos, location, and operator/trader info — by destination search or hotel URL

**Pricing:** $2 / 1k listings

**Endpoint:** `POST /api/v1/agents/booking/listings/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `location` | string | Yes | By Search: a destination or search keyword (city, region, landmark, or area), e.g. "Paris" or "Bali villas". |
| `checkIn` | string | No | Check-in date (YYYY-MM-DD). Required for price and room availability — omit it and price/room columns come back empty. |
| `checkOut` | string | No | Check-out date (YYYY-MM-DD). Required alongside check-in for pricing. |
| `maxResults` | integer | No | Maximum properties to return per search / per URL. |
| `propertyType` | string | No | Filter to a property type (Hotels, Apartments, Villas, Guest houses, Hostels, B&Bs, Resorts, Homestays). |
| `starsCountFilter` | string | No | Filter to properties with at least this official star class (1–5). |
| `minScore` | number | No | Filter to properties with at least this guest score (0–10, e.g. 8.5). |
| `minMaxPrice` | string | No | Nightly/total price range for the searched dates, as min and max in the chosen currency (e.g. 150 to 400). |
| `sortBy` | string | No | Result sort order (defaults to relevance). |
| `currency` | string | No | Currency for prices (EUR, USD, GBP, JPY, INR, MXN, AUD, CAD, …). |
| `language` | string | No | Language/locale for the property data. |
| `urls` | array | No | By URL: Booking.com hotel URLs or search-page URLs. One per line. Add check-in/check-out dates for price and room availability. |

## Example

```bash
curl -X POST https://api.mindcase.co/api/v1/agents/booking/listings/run \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"location":"..."}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/api/v1/agents/booking/listings/run",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "location": "..."
}},
)
data = resp.json()
```

## Get the results

`run` is async and returns a `job_id`. Poll until `status` is `completed`, then read the rows:

```bash
# 1) check status
curl https://api.mindcase.co/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/api/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display 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 |
| `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 |
| `traderInfo` | Trader Info | object |
| `licenseNumbers` | License Numbers | array |
| `host` | Host | object |
| `mapUrl` | Map URL | text |