BookRetreats APIbookretreats.com ↗
Access BookRetreats.com data via API: search retreats by location, category, price, and duration. Get full listing details, reviews, offers, and host info.
What is the BookRetreats API?
The BookRetreats API exposes 4 endpoints covering retreat search, detailed listing data, location references, and category taxonomy from BookRetreats.com. The search_retreats endpoint returns paginated results with pricing, ratings, duration, and session metadata, while get_retreat_details delivers per-listing data including host info, offer pricing, program descriptions, and individual guest reviews.
curl -X GET 'https://api.parse.bot/scraper/e25017fd-fef6-467c-a2f4-26d70a700097/search_retreats?page=1&sort=Recommended&category=yoga-retreats&location=United+States&price_max=5000&price_min=100&duration_max=14&duration_min=3' \ -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 bookretreats-com-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.
"""BookRetreats SDK — search retreats, get details, explore categories and locations."""
from parse_apis.bookretreats_api import BookRetreats, Sort, Location, Category, RetreatNotFound
client = BookRetreats()
# Browse available retreat types (categories)
for rt in client.retreattypes.list(limit=5):
print(rt.name, rt.alias)
# Search yoga retreats in Mexico, sorted by rating, capped at 5 results
for retreat in client.retreats.search(location=Location.MEXICO, category=Category.YOGA_RETREATS, sort=Sort.RATING, limit=5):
print(retreat.title, retreat.price.from_price, retreat.rating.score)
# Drill into the first Thailand retreat's detail page
retreat = client.retreats.search(location=Location.THAILAND, limit=1).first()
if retreat and retreat.details_url:
detail = client.retreatdetails.get(url=retreat.details_url)
print(detail.title, detail.host)
for offer in detail.offers[:3]:
print(offer.name, offer.price, offer.price_currency)
# Handle a missing retreat gracefully
try:
client.retreatdetails.get(url="https://bookretreats.com/r/nonexistent-retreat-xyz")
except RetreatNotFound as exc:
print(f"Retreat gone: {exc}")
print("exercised: retreattypes.list / retreats.search / retreatdetails.get / RetreatNotFound")
Search for retreats based on location, category, and other filters. Returns a paginated list of retreat cards with pricing, ratings, duration, availability, and links to detail pages. Pagination is page-based (30 results per page). When no filters are applied, returns all retreats sorted by recommendation. Each item includes a cta_urls.details_url suitable for passing to get_retreat_details.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| sort | string | Sort order for results. |
| category | string | Retreat category filter (e.g. 'yoga-retreats', 'wellness-retreats', 'ttc'). Values correspond to alias field from get_categories endpoint. |
| location | string | Location filter (e.g. 'Mexico', 'Thailand', 'Costa Rica'). Values available from get_default_locations endpoint. |
| price_max | integer | Maximum price filter in USD. |
| price_min | integer | Minimum price filter in USD. |
| duration_max | integer | Maximum duration in days. |
| duration_min | integer | Minimum duration in days. |
{
"type": "object",
"fields": {
"page": "current page number",
"items": "array of retreat card objects with id, title, location, sessions, duration, price, rating, and cta_urls",
"per_page": "number of results per page (always 30)",
"total_count": "total number of matching retreats",
"total_pages": "total number of pages available"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"id": "67224",
"tags": [],
"price": {
"currency": "USD",
"from_price": 900,
"original_price": null
},
"title": "6 Day Yoga, Healing & Sacred Mayan Journey: Quintana Roo, Mexico",
"rating": {
"score": 5,
"reviews_count": 5
},
"source": {
"rank": 1,
"page_url": "https://bookretreats.com/search?scopes%5Blocation%5D=Mexico&pageNumber=1&sort=Recommended"
},
"cta_urls": {
"details_url": "https://bookretreats.com/r/6-day-yoga-healing-sacred-mayan-journey-quintana-roo-mexico",
"book_now_url": null
},
"duration": {
"max": 6,
"min": 6
},
"location": {
"city": "Cozumel",
"country": "Mexico",
"state_or_region": "Quintana Roo"
},
"sessions": [
{
"label": "Jun 14 - 19 | Jun 24 - 29, 2026"
}
],
"sold_out": false,
"host_badges": [],
"cancellation": {
"policy": "FREE Cancellation",
"free_cancellation": true
},
"eco_friendly": false,
"interest_count": 43,
"raw_dates_text": "Jun 14 - 19 | Jun 24 - 29, 2026",
"availability_note": ""
}
],
"per_page": 30,
"total_count": 289,
"total_pages": 10
},
"status": "success"
}
}About the BookRetreats API
Search and Filter Retreats
The search_retreats endpoint accepts filters for location (e.g. Mexico, Thailand), category (e.g. yoga-retreats, wellness-retreats), price_min/price_max in USD, and duration_min/duration_max in days. Results are paginated and each item in the items array includes an id, title, location data, sessions, duration, price, rating, and a cta_urls.details_url field you pass directly into get_retreat_details.
Retreat Detail Data
get_retreat_details takes a full retreat URL and returns a structured object with fields covering description, program, food, included, summary, host, and an offers array. Each offer has a price, currency, name, and availability status. The reviews array contains individual entries with author, date, rating, and review body. The rating field holds aggregated data conforming to a schema including reviewCount and ratingValue.
Reference Data Endpoints
get_categories returns a typed category taxonomy: each entry in the types array has an id, alias, name, and nested categories and styles arrays. Use the alias values as inputs to the category param in search_retreats. get_default_locations returns a flat array of location name strings — the same values accepted by the location filter. Both endpoints require no inputs and are useful for building filter UIs or iterating over the full site taxonomy.
The BookRetreats API is a managed, monitored endpoint for bookretreats.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when bookretreats.com 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 bookretreats.com 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?+
- Build a retreat comparison tool using price, duration, and rating fields from search_retreats results
- Aggregate guest reviews from get_retreat_details to analyze sentiment across retreat hosts
- Map retreat availability by location using get_default_locations and search_retreats filters
- Surface retreats by category type using get_categories alias values as search filters
- Track pricing trends across yoga or wellness retreats by category and location over time
- Populate a travel app's retreat section with offer prices, inclusions, and program details from get_retreat_details
- Identify top-rated retreat hosts by combining rating.ratingValue and rating.reviewCount fields across listings
| 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 BookRetreats have an official developer API?+
What does the get_retreat_details endpoint return beyond what search results show?+
Are photos or images for retreat listings included in API responses?+
Can I filter search results by specific amenities or accommodation type?+
How does pagination work in search_retreats?+
page field for the current page, per_page for results per page, total_count for total matching retreats, and total_pages for the number of available pages. Pass the page integer parameter to iterate through results.