How to Fetch Hotel Deals by Location
The Deals API has a single endpoint that returns hotel deals near a geographic location. This article walks through how to construct the request, what each parameter does, and what to expect in the response.
Endpoint
GET https://travelapi.ai/hotels/api/v2/deals
Required Parameters
The endpoint requires three query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
lat | float | Yes | Latitude of the target location (e.g., 34.0522) |
long | float | Yes | Longitude of the target location (e.g., -118.2437) |
currency | string | Yes | ISO 4217 currency code (e.g., USD, EUR, GBP) |
Optional Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
top_destination | boolean | No | When true, returns deals for popular travel destinations rather than strictly proximity-based results. |
Required Headers
| Header | Value | Description |
|---|---|---|
accept | application/json | Specifies the response format. |
accept-language | en | Language for localized content in the response. |
timezone | IANA timezone string | The user's timezone (e.g., America/Los_Angeles). |
x-correlation-id | UUID | A unique identifier to trace the request across systems. |
x-session-id | UUID | A session identifier to group related requests from the same user. |
Complete cURL Example
This example fetches hotel deals near downtown Miami, priced in US dollars:
curl -X GET "https://travelapi.ai/hotels/api/v2/deals?lat=25.7617&long=-80.1918¤cy=USD" \
-H "accept: application/json" \
-H "accept-language: en" \
-H "origin: https://yourdomain.com" \
-H "referer: https://yourdomain.com/deals" \
-H "timezone: America/New_York" \
-H "x-correlation-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "x-session-id: 98765432-abcd-ef01-2345-678901234567"
Example with Top Destinations
To retrieve deals for popular destinations near a location rather than just nearby hotels:
curl -X GET "https://travelapi.ai/hotels/api/v2/deals?lat=25.7617&long=-80.1918¤cy=USD&top_destination=true" \
-H "accept: application/json" \
-H "accept-language: en" \
-H "timezone: America/New_York" \
-H "x-correlation-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "x-session-id: 98765432-abcd-ef01-2345-678901234567"
Expected Response Structure
The API returns a JSON response containing an array of hotel deal objects. Each deal typically includes:
- Property information — Hotel name, star rating, address, and location coordinates.
- Pricing — The deal price in your requested currency, along with the original or reference price so you can display the discount.
- Discount details — The percentage or absolute discount compared to the standard rate.
- Images — One or more property images suitable for display in a deal card.
- Availability window — When the deal is valid, which may include check-in date ranges or booking deadlines.
A typical response structure looks like this:
{
"deals": [
{
"property_id": "h12345",
"property_name": "Ocean View Resort & Spa",
"star_rating": 4,
"address": "123 Beachfront Ave, Miami Beach, FL",
"latitude": 25.7906,
"longitude": -80.13,
"image_url": "https://images.example.com/property/h12345/main.jpg",
"original_price": 289,
"deal_price": 199,
"currency": "USD",
"discount_percentage": 31,
"dealtype": "limitedtime",
"checkinfrom": "2026-03-10",
"checkinto": "2026-03-20"
}
]
}> Note: The exact response schema may vary. Refer to the latest API documentation or inspect a live response to confirm the current field names and structure.
JavaScript Example
Here is how you might call the Deals API from a JavaScript application:
async function fetchDeals(latitude, longitude, currency = 'USD') {
const params = new URLSearchParams({
lat: latitude.toString(),
long: longitude.toString(),
currency: currency
});
const response = await fetch(
https://travelapi.ai/hotels/api/v2/deals?${params},
{
method: 'GET',
headers: {
'accept': 'application/json',
'accept-language': 'en',
'timezone': Intl.DateTimeFormat().resolvedOptions().timeZone,
'x-correlation-id': crypto.randomUUID(),
'x-session-id': sessionStorage.getItem('sessionId') || crypto.randomUUID()
}
}
);
if (!response.ok) {
throw new Error(Deals API returned ${response.status});
}
return response.json();
}
// Fetch deals near Miami
const deals = await fetchDeals(25.7617, -80.1918, 'USD');
Handling Coordinates
If you do not have the user's coordinates readily available, you can obtain them using:
- Browser Geolocation API —
navigator.geolocation.getCurrentPosition()provides the device's GPS coordinates. - IP-based geolocation — Services like MaxMind or ipinfo.io can estimate a user's location from their IP address.
- Geocoding services — Convert a city name or address to coordinates using Google Maps Geocoding, Mapbox, or similar APIs.
See How to Display Deals in Your Application for more on geocoding and presenting deal results.