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

StatusDescription
404 Not FoundNo 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

StatusDescription
401 UnauthorizedMissing or invalid bearer token.
404 Not FoundNo 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.