Airbnb APIairbnb.es ↗
Search Airbnb Spain vacation rentals by location and price, then fetch host info, house rules, and descriptions for any listing ID.
What is the Airbnb API?
The Airbnb Spain API covers 2 endpoints for discovering and inspecting vacation rental listings on airbnb.es. Use search_listings to query any Spanish city or region with optional price filters and pagination, then pass a listing_id to get_listing_details to retrieve host details, superhost status, house rules, and a full HTML description. Each search result returns fields including nightly_price, total_price, rating, and GPS coordinates.
curl -X GET 'https://api.parse.bot/scraper/484854e0-e09f-48af-b6f9-f14d9074e8af/search_listings?limit=5&query=Madrid&max_price=300&min_price=50' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace airbnb-es-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: AirbnbES SDK — search listings and drill into details."""
from parse_apis.airbnb_es_api import AirbnbES, ListingNotFound
client = AirbnbES()
# Search for listings in Madrid with a price cap, bounded iteration.
for summary in client.listingsummaries.search(query="Madrid", max_price=150, limit=5):
print(summary.name, summary.nightly_price, summary.rating)
# Drill into the first result for full details.
first = client.listingsummaries.search(query="Valencia", limit=1).first()
if first:
detail = first.details()
print(detail.host_name, detail.is_superhost, detail.location_description)
for rule in (detail.house_rules or [])[:3]:
print(rule)
# Fetch a listing directly by ID.
try:
listing = client.listings.get(listing_id="19155752")
print(listing.host_name, listing.description[:80] if listing.description else "")
except ListingNotFound as exc:
print(f"Listing not found: {exc}")
print("exercised: listingsummaries.search / summary.details / listings.get / ListingNotFound")
Search for vacation rental listings by location with optional price filtering. Returns paginated listing summaries including name, rating, nightly price, total price, and coordinates. Pagination uses an opaque cursor; results default to Airbnb's relevance ordering. Price filters are in EUR.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of listings to return per page |
| queryrequired | string | Location to search for listings (city name or region, e.g. 'Madrid', 'Valencia', 'Paris') |
| cursor | string | Opaque pagination cursor from a previous response's next_cursor field |
| max_price | integer | Maximum nightly price in EUR |
| min_price | integer | Minimum nightly price in EUR |
{
"type": "object",
"fields": {
"listings": "array of listing summary objects with listing_id, name, rating, nightly_price, total_price, location, subtitle, and host_name",
"next_cursor": "string or null, opaque pagination cursor for next page"
},
"sample": {
"data": {
"listings": [
{
"name": "GuestReady - Moderno piso 5 minutos de la playa",
"rating": "Nuevo",
"location": {
"latitude": 39.47878,
"longitude": -0.32831
},
"subtitle": "GuestReady - Moderno piso 5 minutos de la playa",
"host_name": null,
"listing_id": "1701509192252372163",
"total_price": "649 €",
"nightly_price": "129.80"
}
],
"next_cursor": null
},
"status": "success"
}
}About the Airbnb API
Search Listings
The search_listings endpoint accepts a query string (city name or region such as Madrid, Barcelona, or Valencia) and returns a paginated array of listing summaries. Each object in the listings array includes listing_id, name, rating, nightly_price, total_price, location, subtitle, and host_name. Results default to Airbnb's internal relevance ordering. You can narrow results with min_price and max_price (both in EUR). Pagination is cursor-based: pass the next_cursor value from one response as the cursor parameter of the next call. A null value for next_cursor means you have reached the last page.
Listing Details
The get_listing_details endpoint takes a single listing_id (obtained from search_listings) and returns a richer profile of that property. Response fields include title, description (HTML-formatted), host_name, is_superhost, host_response_time, location_description, and an array of house_rules strings. The superhost flag and response time fields are useful for filtering properties by host quality without requiring a separate request.
Coverage and Scope
The API is scoped to airbnb.es and returns pricing in EUR. Queries can reference locations outside Spain (the query field is a free-text location string), but the data reflects listings surfaced by the Spanish Airbnb domain. Fields not returned include calendar availability, per-date pricing, reviews text, or photo URLs — only the fields documented in the response shapes above are guaranteed.
The Airbnb API is a managed, monitored endpoint for airbnb.es — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when airbnb.es changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official airbnb.es API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate nightly prices across Madrid neighborhoods to build a short-term rental price index.
- Filter Barcelona listings by
min_price/max_priceandratingto power a curated travel recommendation widget. - Identify superhost properties in a target city using the
is_superhostflag fromget_listing_details. - Collect
locationand coordinate data from search results to plot rental density on a map. - Monitor listing availability and pricing changes over time by periodically polling
search_listingsfor a fixed query. - Extract
house_rulesarrays to compare policy strictness (pet policies, check-in windows) across properties. - Feed
host_response_timedata into a host-quality scoring model for a vacation rental comparison tool.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Airbnb offer an official developer API?+
What does `get_listing_details` return beyond what `search_listings` already provides?+
search_listings returns summary fields: name, rating, nightly_price, total_price, location, subtitle, and host_name. get_listing_details adds the HTML description, the house_rules array, is_superhost, host_response_time, and a location_description prose summary. You need the listing_id from a search result to call the detail endpoint.How does pagination work in `search_listings`?+
next_cursor field. Pass its value as the cursor parameter in your next request to retrieve the following page of results. When next_cursor is null, there are no further pages. The cursor is opaque — do not attempt to construct or decode it.Does the API return calendar availability or per-date pricing?+
nightly_price and total_price from search results, but does not expose calendar availability, blocked dates, or dynamic per-date pricing. You can fork this API on Parse and revise it to add an availability endpoint if that data is part of your use case.Are guest reviews or review counts returned by either endpoint?+
rating field is returned per listing in search_listings, but individual review text and review counts are not returned by either endpoint. You can fork this API on Parse and revise it to add a reviews endpoint that exposes per-review content.