Connectors and developers
Public hotel API
Endpoints, filters, examples, response fields, errors, and anonymous limits.
Anonymous hotel discovery
The public JSON API exposes the same class of hotel information visible on Room Saint. It requires no login or API key and cannot modify hotels, trips, accounts, or bookings.
| GET endpoint | Required input |
|---|---|
/api/v1/hotels/search | None; browse or filter |
/api/v1/hotels/{id} | Numeric hotel ID in the path |
/api/v1/hotels/nearby | latitude and longitude |
/api/v1/hotels/near-landmark | landmark |
Search parameters
| Parameter | Meaning and bounds |
|---|---|
q | Hotel, brand, destination, or descriptive text; up to 500 characters |
city, country | City text up to 120 characters; two-letter country code such as IT |
latitude, longitude | Provide both; −90 to 90 and −180 to 180 |
radius_km | 1 to 100 km; default 10; requires coordinates except for landmark lookup |
min_review_score | 0–5 website community score; missing and zero scores are excluded when filtering |
min_star_rating, max_star_rating | Integer 1–5; minimum must not exceed maximum |
amenities[] | Up to 10 catalog identifiers of up to 60 characters; all must match, for example wifi and parking |
limit, offset | 1–20 results; default 20. Offset starts at 0; offset + limit must not exceed 200. |
Nearby accepts these filters. Landmark lookup accepts them except q and coordinates, plus a landmark name up to 200 characters. It returns the resolved location; if the place cannot be resolved reliably, use coordinates. Hotel lookup accepts only the hotel ID. Omit unused fields. Unknown parameters and arbitrary query objects are rejected.
Example requests
curl 'https://www.roomsaint.com/api/v1/hotels/search?q=Rome&country=IT&limit=5'
curl 'https://www.roomsaint.com/api/v1/hotels/nearby?latitude=41.89&longitude=12.49&radius_km=5'Responses
Search responses contain results, total, limit, and offset. Lookup returns a data object. Hotel objects include the available ID, name, address, city, country, coordinates, score, star class, amenities, canonical_url, and expedia_url. Missing facts are omitted. The score is not a separate verified guest-review average.
Use canonical_url to link readers to the Room Saint hotel page. Preserve the supplied affiliate attribution when presenting expedia_url as a booking link. Do not present catalog prices or metadata as guaranteed live availability.
Limits and errors
REST permits 30 requests per minute per IP. REST and public MCP share 500 requests per rolling 24 hours per IP. Repeated, cached, and invalid requests count. Narrow a search rather than attempting a catalog export.
{"error":{"code":"INVALID_PAGINATION","message":"Narrow your search or reduce the result count."}}Invalid input returns 422; missing hotels 404; oversized requests 413; rate limits 429; unavailable search or landmark lookup 503. On 429, honor Retry-After. On 503, retry with backoff. X-Request-ID identifies a request when reporting a problem. Full error messages vary with the invalid field.
Successful searches use a short application cache. These endpoints are for discovery, not bulk export. See the MCP reference for structured tool access.