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

# Get a reference hotel or download the inventory

> Retrieve a single reference hotel by UUID, or get a presigned URL to download the full reference inventory file for bulk processing.

Two endpoints let you fetch reference hotel data directly. Use the single-hotel endpoint when you need to look up a known hotel by its UUID. Use the presigned URL endpoint to download the complete inventory file — useful for bulk ingestion, offline processing, or building your own index.

***

## GET /api/v1/reference/{id}

Retrieve full detail for a single reference hotel by its UUID.

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

### Path parameters

<ParamField path="id" type="string" required>
  The UUID of the reference hotel.
</ParamField>

### Response

<ResponseField name="id" type="string" required>
  Hotel UUID.
</ResponseField>

<ResponseField name="name" type="string" required>
  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>

<ResponseField name="metadata" type="object">
  Additional hotel metadata and embeddings.
</ResponseField>

### Errors

| Status          | Description                        |
| --------------- | ---------------------------------- |
| `404 Not Found` | No hotel found for the given UUID. |

### Example

```bash theme={null} theme={null}
curl https://api.mapping.travel/api/v1/reference/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <token>"
```

***

## GET /api/v1/reference

Get a presigned URL to download the latest reference hotel inventory file.

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

<Warning>
  This endpoint requires authentication. Requests without a valid `Authorization` header return `401 Unauthorized`.
</Warning>

The presigned URL grants temporary access to the full reference inventory. You can use it to download the file directly with any HTTP client without additional authentication. The URL expires after the number of minutes you specify.

### Query parameters

<ParamField query="expirationMinutes" type="number" default="60">
  How many minutes the presigned URL remains valid. Defaults to 60.
</ParamField>

### Response

<ResponseField name="s3Url" type="string" required>
  Presigned URL for downloading the reference inventory file directly. Valid for `expirationMinutes` minutes. No additional `Authorization` header is needed when fetching this URL.
</ResponseField>

### Errors

| Status             | Description                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid bearer token.                                                            |
| `404 Not Found`    | No reference inventory has been generated yet. Check back after the first export completes. |

### Example

```bash theme={null} theme={null}
curl "https://api.mapping.travel/api/v1/reference?expirationMinutes=120" \
  -H "Authorization: Bearer <token>"
```

```json theme={null} theme={null}
{
  "s3Url": "https://presigned-url.example.com/reference-inventory-2026-04-25.json?expires=1745600000&sig=..."
}
```

<Tip>
  Download the inventory file in the background and cache it locally. Re-request a new presigned URL only when your cached copy is stale rather than on every lookup.
</Tip>