Skip to main content
This page covers the most common problems you might encounter when using OpenBookings as an end-user or when calling the API as a developer. Work through the relevant section below to diagnose and resolve your issue.

​
API issues

The search endpoint requires all of the following query parameters. If any are absent or empty, the API returns a 400 response with an errors array listing every missing field.
ParameterTypeFormatRequired
latnumberDecimal degrees (e.g. 48.8566)Yes
lonnumberDecimal degrees (e.g. 2.3522)Yes
checkinstringYYYY-MM-DDYes
checkoutstringYYYY-MM-DDYes
adultsnumberInteger ≥ 1Yes
roomsnumberInteger ≥ 1Yes
childrennumberInteger ≥ 0No
A complete request looks like this:
GET /api/query?lat=48.8566&lon=2.3522&checkin=2026-08-01&checkout=2026-08-05&adults=2&rooms=1
1

Check the error response

Read the errors array in the response body. It lists every missing or invalid field by name, so you can fix all issues in one pass.
{ "errors": ["lat is required", "checkin is required"] }
2

Add the missing parameters

Include every required parameter in your query string before retrying.
3

Verify the request is a GET

The endpoint only accepts GET requests. Body parameters are not read — all values must be in the URL query string.
Each numeric parameter (lat, lon, adults, rooms, children) must parse as a valid JavaScript number. If a value is present but not numeric, the API returns a 400 with a message like lat must be a number.Common causes:
  • Passing a city name instead of coordinates (e.g. lat=Paris instead of lat=48.8566).
  • Including extra characters such as degree symbols (48°) or whitespace.
  • Passing an empty string for an optional parameter — omit children entirely rather than sending children=.
1

Confirm lat and lon are decimal numbers

Use a geocoding service or your destination search to obtain the numeric latitude and longitude before calling the search endpoint.
2

Remove any non-numeric characters

Values must be plain numbers: 48.8566, not "48.8566 N" or 48,8566.
3

Omit optional parameters when not needed

If you don’t have a value for children, leave the parameter out of the query string entirely rather than passing an empty string.
A 500 response indicates that the API was unable to complete the database query. The response body contains an error field with a message.
{ "error": "Database error" }
1

Wait and retry

Transient connectivity issues resolve on their own. Wait a few seconds and send the same request again.
2

Check your parameters

Malformed date strings (e.g. checkin=not-a-date) can cause unexpected database errors even after passing client-side validation. Ensure checkin and checkout are valid YYYY-MM-DD dates and that checkout is later than checkin.
3

Try a different search

If the error persists only for specific coordinates or dates, try a slightly different input to rule out an edge case in the data.
4

Report the issue

If you consistently receive 500 errors, open an issue on the OpenBookings GitHub repository and include your request parameters (without personal data) and the error message from the response body.

​
Rate limiting

OpenBookings enforces rate limits to ensure fair access for all users. When you exceed the allowed number of requests in a given time window, the API rejects further requests until the window resets.
Best practices for developers:
  • Cache results on your side. If you’re building a frontend, store search results locally and avoid re-fetching the same query within a short period.
  • Debounce user input. Don’t send a new API request on every keystroke. Wait until the user stops typing before triggering a search.
  • Respect the reset time. When a rate-limited response is returned, wait until the window resets before retrying rather than polling repeatedly.
  • Avoid parallel duplicate requests. If multiple parts of your application might trigger the same search, deduplicate requests before they are sent.
If your use case requires higher request volumes, consider running your own instance of OpenBookings so you can configure limits appropriate for your workload.

​
Search issues

If your search completes successfully but returns an empty list, work through the following checks:
1

Check the destination coordinates

Results are filtered to properties within 250 km of the coordinates you searched. If the city resolved to unexpected coordinates, try searching for a different nearby city.
2

Reduce the guest count

Every room must accommodate your selected number of adults and children. If your guest count is high, try reducing it to see whether more rooms appear.
3

Adjust your dates

A room must be available for every night of your stay. If most rooms in the area are fully booked, try different dates. Searching too far into the future may also return fewer results if properties haven’t opened availability that far out yet.
4

Try a nearby larger city

If your destination is remote or rural, there may be no registered properties within range. Searching for the nearest major city will cast a wider net across the surrounding region.
The home page displays a destination background image that is cached in your browser’s Cache API for fast repeat loads.
1

Wait a moment

On your first visit, the image downloads in the background. It appears once the download is complete — a plain dark background is shown in the meantime.
2

Check your browser's private browsing mode

Some browsers restrict the Cache API in private or incognito windows. In this mode, the image is loaded directly from the source URL each time, which may be slower or fail if the network request is blocked. Switching to a regular browser window resolves this.
3

Clear the site cache

If the image appears broken (not just slow), your cached version may be stale. Clear the site data for OpenBookings in your browser settings and reload the page to fetch a fresh copy.

​
Authentication issues