Skip to main content
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

ModeTriggerDescription
Fuzzy nameq is presentFull-text search against hotel names
Geographiclat, lon, and radius all presentReturns hotels within the given radius
Filter-basedNone of the aboveFilters 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.
​
total
number
Total number of results matching the query before pagination.

​
Examples

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"