> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapping.travel/llms.txt
> Use this file to discover all available pages before exploring further.

# 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   |

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

***

## GET /api/v1/reference/search

Search the reference hotel inventory.

```bash theme={null} theme={null}
GET https://api.mapping.travel/api/v1/reference/search
```

### Query parameters

<ParamField query="q" type="string">
  Fuzzy search query for hotel name. When present, name search mode is used and geographic/filter parameters are ignored.
</ParamField>

<ParamField query="lat" type="number">
  Latitude for geographic search. Must be combined with `lon` and `radius`.
</ParamField>

<ParamField query="lon" type="number">
  Longitude for geographic search. Must be combined with `lat` and `radius`.
</ParamField>

<ParamField query="radius" type="number">
  Search radius in kilometers. Must be greater than 0.
</ParamField>

<ParamField query="country" type="string">
  Filter results by country name. Case-insensitive. Can be combined with any search mode.
</ParamField>

<ParamField query="region" type="string">
  Filter results by region. Applicable in name and filter-based modes.
</ParamField>

<ParamField query="city" type="string">
  Filter results by city name.
</ParamField>

<ParamField query="rating" type="number">
  Minimum star rating (e.g. `3`, `4.5`). Applied in filter-based mode.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of results to return. Clamped to the range 1–100.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination.
</ParamField>

### Response

<ResponseField name="results" type="object[]">
  Array of matching reference hotel objects.

  <Expandable title="hotel properties">
    <ResponseField name="id" type="string">
      Unique UUID for the reference hotel.
    </ResponseField>

    <ResponseField name="name" type="string">
      Hotel display name.
    </ResponseField>

    <ResponseField name="country" type="string">
      Country name.
    </ResponseField>

    <ResponseField name="city" type="string">
      City name.
    </ResponseField>

    <ResponseField name="region" type="string">
      Region or state.
    </ResponseField>

    <ResponseField name="rating" type="number">
      Star rating.
    </ResponseField>

    <ResponseField name="lat" type="number">
      Latitude coordinate, if available.
    </ResponseField>

    <ResponseField name="lon" type="number">
      Longitude coordinate, if available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of results matching the query before pagination.
</ResponseField>

### Examples

<CodeGroup>
  ```bash Name search theme={null} theme={null}
  curl -G https://api.mapping.travel/api/v1/reference/search \
    -d "q=Hilton+Paris" \
    -d "limit=10"
  ```

  ```bash Geographic search theme={null} theme={null}
  curl -G https://api.mapping.travel/api/v1/reference/search \
    -d "lat=48.8566" \
    -d "lon=2.3522" \
    -d "radius=5" \
    -d "limit=20"
  ```

  ```bash Filter-based search theme={null} theme={null}
  curl -G https://api.mapping.travel/api/v1/reference/search \
    -d "country=France" \
    -d "city=Paris" \
    -d "rating=4" \
    -d "limit=50" \
    -d "offset=0"
  ```
</CodeGroup>

***

## GET /api/v1/reference/search/advanced

Advanced search with additional filters and sorting options.

```bash theme={null} theme={null}
GET https://api.mapping.travel/api/v1/reference/search/advanced
```

### Query parameters

<ParamField query="name" type="string">
  Hotel name query string.
</ParamField>

<ParamField query="country" type="string">
  Filter by country name.
</ParamField>

<ParamField query="city" type="string">
  Filter by city name.
</ParamField>

<ParamField query="rating" type="number">
  Minimum star rating.
</ParamField>

<ParamField query="hasCoordinates" type="boolean">
  When `true`, only return hotels that have latitude and longitude values.
</ParamField>

<ParamField query="sortBy" type="string" default="name">
  Field to sort by. Accepted values: `name`, `rating`, `created`.
</ParamField>

<ParamField query="sortDir" type="string" default="asc">
  Sort direction. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of results. Clamped to 1–100.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

### Example

```bash theme={null} theme={null}
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"
```