Search reference hotels by name or location

Find hotels in the Mapping.Travel reference inventory using fuzzy name search, geographic radius search, or filter-based lookup with country, city, and rating.

The reference hotel search endpoints let you query the Mapping.Travel canonical hotel inventory. Depending on the parameters you provide, the API routes your request to one of three search modes: fuzzy name search, geographic radius search, or filter-based lookup. A separate advanced search endpoint gives you additional sorting and filtering controls.

Search modes

Mode	Trigger	Description
Fuzzy name	q is present	Full-text search against hotel names
Geographic	lat, lon, and radius all present	Returns hotels within the given radius
Filter-based	None of the above	Filters by country, city, and rating

limit is clamped to a maximum of 100. offset must be zero or greater. Both are applied after the search mode is resolved.

---

GET /api/v1/reference/search

Search the reference hotel inventory.

GET https://api.mapping.travel/api/v1/reference/search

Query parameters

q · string

Fuzzy search query for hotel name. When present, name search mode is used and geographic/filter parameters are ignored.

lat · number

Latitude for geographic search. Must be combined with lon and radius.

lon · number

Longitude for geographic search. Must be combined with lat and radius.

radius · number

Search radius in kilometers. Must be greater than 0.

country · string

Filter results by country name. Case-insensitive. Can be combined with any search mode.

region · string

Filter results by region. Applicable in name and filter-based modes.

city · string

Filter results by city name.

rating · number

Minimum star rating (e.g. 3, 4.5). Applied in filter-based mode.

limit · number · default: "20"

Maximum number of results to return. Clamped to the range 1–100.

offset · number · default: "0"

Number of results to skip for pagination.

Response

results · object[]

Array of matching reference hotel objects.

Show hotel properties

id · string

Unique UUID for the reference hotel.

name · string

Hotel display name.

country · string

Country name.

city · string

City name.

region · string

Region or state.

rating · number

Star rating.

lat · number

Latitude coordinate, if available.

lon · number

Longitude coordinate, if available.

total · number

Total number of results matching the query before pagination.

Examples

Name search

curl -G https://api.mapping.travel/api/v1/reference/search \
  -d "q=Hilton+Paris" \
  -d "limit=10"

---

GET /api/v1/reference/search/advanced

Advanced search with additional filters and sorting options.

GET https://api.mapping.travel/api/v1/reference/search/advanced

Query parameters

name · string

Hotel name query string.

country · string

Filter by country name.

city · string

Filter by city name.

rating · number

Minimum star rating.

hasCoordinates · boolean

When true, only return hotels that have latitude and longitude values.

sortBy · string · default: "name"

Field to sort by. Accepted values: name, rating, created.

sortDir · string · default: "asc"

Sort direction. Accepted values: asc, desc.

limit · number · default: "20"

Maximum number of results. Clamped to 1–100.

offset · number · default: "0"

Pagination offset.

Example

curl -G https://api.mapping.travel/api/v1/reference/search/advanced \
  -d "country=Spain" \
  -d "rating=5" \
  -d "hasCoordinates=true" \
  -d "sortBy=rating" \
  -d "sortDir=desc" \
  -d "limit=25"