Skip to main content
The hotel search endpoint returns available rooms near a geographic point for a given set of dates and guests. It searches within a 250 km radius, applies all active rate modifiers, and returns the cheapest eligible room for each hotel, sorted by total price ascending. No authentication is required.

​
Endpoint

GET https://openbookings.co/api/query

​
Request parameters

All parameters are passed as URL query string values.
​
lat
number
required
Latitude of the search center point, in decimal degrees. Combined with lon to define the search origin.
​
lon
number
required
Longitude of the search center point, in decimal degrees. Combined with lat to define the search origin.
​
checkin
string
required
Check-in date in YYYY-MM-DD format (e.g. 2026-07-14). Must be before checkout.
​
checkout
string
required
Check-out date in YYYY-MM-DD format (e.g. 2026-07-21). Must be after checkin.
​
adults
number
required
Number of adult guests. Only rooms whose max_adults is greater than or equal to this value are returned.
​
children
number
Number of child guests. Defaults to 0 when omitted. Only rooms whose max_children is greater than or equal to this value are returned.
​
rooms
number
required
Number of rooms requested. Passed through to the search context but pricing is calculated per room.

​
Search behaviour

  • Results are filtered to properties within 250 km of the supplied coordinates.
  • Only rooms where is_active = true and the matching rate plan is active are considered.
  • Guest count is enforced: adults ≤ max_adults and children ≤ max_children.
  • One room per hotel is returned — the room with the lowest total_price after modifiers.
  • Results are sorted by total_price ascending.

​
Pricing

Each room has a subtotal (sum of nightly base prices before stay-level adjustments) and a total_price (after all applicable modifiers fire). The applied_modifiers array tells you which modifier types contributed to the final price. Modifier types that can appear in applied_modifiers:
TypeDescription
day_of_weekSurcharge applied to specific days of the week
length_of_stayDiscount for stays meeting a minimum night threshold
early_birdDiscount for bookings made sufficiently far in advance
last_minuteSurcharge applied when booking close to the arrival date
extra_guestPer-night surcharge for guests above base occupancy
Only one discount modifier (length_of_stay or early_bird) can fire per room — whichever is eligible and has the lowest sort_order wins. Surcharge modifiers (day_of_week, last_minute, extra_guest) can all fire independently.

​
Response

A successful response is an array of ResolvedRoom objects.
​
hotel_id
string
Unique identifier for the property.
​
hotel_name
string
Display name of the hotel.
​
hotel_slug
string
URL-friendly slug for the hotel, suitable for building deep-link URLs.
​
city
string
City where the property is located.
​
country
string
Country where the property is located.
​
room_id
string
Unique identifier for the room.
​
room_name
string
Display name of the room type (e.g. “Deluxe King”).
​
room_description
string
Full description of the room.
​
base_occupancy
number
Number of guests the room accommodates at the standard rate. Guests above this count may trigger the extra_guest modifier.
​
max_adults
number
Maximum number of adult guests the room can accommodate.
​
max_children
number
Maximum number of child guests the room can accommodate.
​
rate_plan_id
string
Unique identifier for the rate plan applied to this result.
​
rate_plan_name
string
Display name of the rate plan (e.g. “Best Available Rate”).
​
currency
string
ISO 4217 currency code for all price fields (e.g. "USD", "EUR").
​
is_refundable
boolean
Whether this rate plan allows a full refund under its cancellation policy.
​
cancellation_policy
string
Human-readable description of the cancellation terms.
​
min_stay
number
Minimum number of nights required to book this room under this rate plan.
​
max_stay
number | null
Maximum number of nights allowed. null means no upper limit.
​
subtotal
number
Sum of nightly base prices for the stay, before stay-level modifiers (e.g. length_of_stay, early_bird) are applied. Rounded to two decimal places.
​
total_price
number
Final price after all applicable modifiers have been applied. This is the amount to display to the guest. Rounded to two decimal places.
​
applied_modifiers
string[]
List of modifier type strings that fired during price calculation. Possible values: "day_of_week", "length_of_stay", "early_bird", "last_minute", "extra_guest". An empty array means no modifiers changed the base price.

​
Error responses

400 — validation error Returned when one or more required parameters are missing or cannot be parsed as the expected type. 
{
  "errors": [
    "lat is required",
    "checkout is required"
  ]
}
500 — server error Returned when an unexpected internal error occurs (e.g. a database failure). 
{
  "error": "Database error"
}

​
Code examples

curl --request GET \
  "https://openbookings.co/api/query?lat=48.8566&lon=2.3522&checkin=2026-07-14&checkout=2026-07-21&adults=2&children=0&rooms=1"
Example response 
[
  {
    "hotel_id": "prop_abc123",
    "hotel_name": "Hôtel du Marais",
    "hotel_slug": "hotel-du-marais",
    "city": "Paris",
    "country": "France",
    "room_id": "room_xyz789",
    "room_name": "Classic Double",
    "room_description": "A comfortable double room with city views.",
    "base_occupancy": 2,
    "max_adults": 2,
    "max_children": 1,
    "rate_plan_id": "rp_001",
    "rate_plan_name": "Best Available Rate",
    "currency": "EUR",
    "is_refundable": true,
    "cancellation_policy": "Free cancellation up to 48 hours before check-in.",
    "min_stay": 1,
    "max_stay": null,
    "subtotal": 840.00,
    "total_price": 756.00,
    "applied_modifiers": ["early_bird"]
  }
]