Deals API Supported Currencies and Localization

The Deals API is designed for international use. You can request deal pricing in a wide range of currencies, localize response content by language, and provide timezone context for time-sensitive deal information. This article covers how each of these localization features works.

Currency Support

The currency Parameter

The currency query parameter accepts an ISO 4217 three-letter currency code. All prices in the response — including deal prices, original prices, and savings amounts — are returned in the specified currency.

GET /hotels/api/v2/deals?lat=48.8566&long=2.3522&currency=EUR

Commonly Used Currencies

How Currency Conversion Works

Hotel deals are sourced from multiple suppliers, each of which may price their inventory in different base currencies. When you specify a currency in your request, the API performs the conversion server-side using current exchange rates before returning results.

Key points to understand:

• Real-time rates — Exchange rates are updated regularly to reflect current market conditions.
• Consistent pricing — All deals in a single response use the same currency and the same exchange rate snapshot, so prices are directly comparable.
• No client-side conversion needed — You can display the returned prices as-is without additional conversion logic.
• Rounding — Converted amounts are rounded appropriately for the target currency (e.g., to two decimal places for USD, to whole numbers for JPY).

Formatting Prices for Display

When displaying deal prices, use the browser's Intl.NumberFormat to format values correctly for the user's locale:

function formatPrice(amount, currencyCode, locale = 'en-US') {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: currencyCode,
    minimumFractionDigits: currencyCode === 'JPY' ? 0 : 2,
    maximumFractionDigits: currencyCode === 'JPY' ? 0 : 2
  }).format(amount);
}
// Examples:
formatPrice(199.00, 'USD');         // "$199.00"
formatPrice(175.50, 'EUR', 'de-DE'); // "175,50 €"
formatPrice(15000, 'JPY', 'ja-JP');  // "￥15,000"

Language Localization

The accept-language Header

The accept-language header controls the language of localized text in the API response. This may affect property descriptions, deal labels, and other human-readable fields.

accept-language: es

Supported Language Codes

The API supports standard BCP 47 language tags. Common values include:

Localization Behavior

• Fallback — If the requested language is not available for a particular piece of content, the API falls back to English.
• Partial localization — Some fields like property names may remain in their original language (the name the hotel uses) regardless of the language header.
• Consistent within response — All localizable fields in a single response use the same language.

Detecting the User's Language

You can detect the user's preferred language from the browser:

const userLanguage = navigator.language || navigator.userLanguage || 'en';
// e.g., "es-MX", "fr", "en-US"

Timezone Handling

The timezone Header

The timezone header accepts an IANA timezone identifier and helps the API return time-relevant information adjusted to the user's local time.

timezone: America/Los_Angeles

Why Timezone Matters

• Deal expiry — If a deal has a booking deadline, the API can express it relative to the user's timezone.
• Check-in date relevance — Time-sensitive deals for "tonight" or "this weekend" depend on what "today" means in the user's timezone.
• Consistency — Ensures that timestamps in the response align with what the user expects.

Detecting the User's Timezone

const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// e.g., "America/New_York", "Europe/Berlin", "Asia/Tokyo"

Common IANA Timezone Values

Putting It Together

A fully localized request for a Spanish-speaking user in Mexico City:

curl -X GET "https://travelapi.ai/hotels/api/v2/deals?lat=19.4326&long=-99.1332&currency=MXN" \
  -H "accept: application/json" \
  -H "accept-language: es" \
  -H "timezone: America/Mexico_City" \
  -H "x-correlation-id: c3d4e5f6-a1b2-7890-cdef-123456789abc" \
  -H "x-session-id: 12345678-abcd-ef01-2345-abcdef012345"

This request returns hotel deals near Mexico City with prices in Mexican Pesos and Spanish-language content where available.