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/

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

GET https://api.mapping.travel/api/v1/reference/{id}

Path parameters

id · string · required

The UUID of the reference hotel.

Response

id · string · required

Hotel UUID.

name · string · required

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.

metadata · object

Additional hotel metadata and embeddings.

Errors

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

Example

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.

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

This endpoint requires authentication. Requests without a valid Authorization header return 401 Unauthorized.

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

expirationMinutes · number · default: "60"

How many minutes the presigned URL remains valid. Defaults to 60.

Response

s3Url · 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.

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

curl "https://api.mapping.travel/api/v1/reference?expirationMinutes=120" \
  -H "Authorization: Bearer <token>"

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

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.