Hotel search endpoint — GET /api/query

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.

number

required

Latitude of the search center point, in decimal degrees. Combined with lon to define the search origin.

number

required

Longitude of the search center point, in decimal degrees. Combined with lat to define the search origin.

string

required

Check-in date in YYYY-MM-DD format (e.g. 2026-07-14). Must be before checkout.

string

required

Check-out date in YYYY-MM-DD format (e.g. 2026-07-21). Must be after checkin.

number

required

Number of adult guests. Only rooms whose max_adults is greater than or equal to this value are returned.

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.

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:

Type	Description
`day_of_week`	Surcharge applied to specific days of the week
`length_of_stay`	Discount for stays meeting a minimum night threshold
`early_bird`	Discount for bookings made sufficiently far in advance
`last_minute`	Surcharge applied when booking close to the arrival date
`extra_guest`	Per-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.

string

Unique identifier for the property.

string

Display name of the hotel.

string

URL-friendly slug for the hotel, suitable for building deep-link URLs.

string

City where the property is located.

string

Country where the property is located.

string

Unique identifier for the room.

string

Display name of the room type (e.g. “Deluxe King”).

string

Full description of the room.

number

Number of guests the room accommodates at the standard rate. Guests above this count may trigger the extra_guest modifier.

number

Maximum number of adult guests the room can accommodate.

number

Maximum number of child guests the room can accommodate.

string

Unique identifier for the rate plan applied to this result.

string

Display name of the rate plan (e.g. “Best Available Rate”).

string

ISO 4217 currency code for all price fields (e.g. "USD", "EUR").

boolean

Whether this rate plan allows a full refund under its cancellation policy.

string

Human-readable description of the cancellation terms.

number

Minimum number of nights required to book this room under this rate plan.

number | null

Maximum number of nights allowed. null means no upper limit.

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.

number

Final price after all applicable modifiers have been applied. This is the amount to display to the guest. Rounded to two decimal places.

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"

const params = new URLSearchParams({
  lat: "48.8566",
  lon: "2.3522",
  checkin: "2026-07-14",
  checkout: "2026-07-21",
  adults: "2",
  children: "0",
  rooms: "1",
});

const response = await fetch(
  `https://openbookings.co/api/query?${params}`
);

if (!response.ok) {
  const err = await response.json();
  // err.errors — array of validation messages
  // err.error  — single server error message
  throw new Error(JSON.stringify(err));
}

const rooms = await response.json();
// rooms is ResolvedRoom[]
console.log(rooms[0].hotel_name, rooms[0].total_price);

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"]
  }
]

Overview

Endpoints

Data Types

Hotel search endpoint — GET /api/query

Endpoint

Request parameters

Search behaviour

Pricing

Response

Error responses

Code examples

​Endpoint

​Request parameters

​Search behaviour

​Pricing

​Response

​Error responses

​Code examples

Endpoint

Request parameters

Search behaviour

Pricing

Response

Error responses

Code examples