Data conventions

To ensure seamless integration and consistent data handling, the Demand API adheres to a defined set of formatting, validation, and input standards. This page outlines the conventions for timestamps, country and currency codes, supported language formats, and input constraints.

Dates and times

The Demand API uses ISO 8601 and specifically, the RFC 3339 convention for all timestamps and date formats.

These internationally recognised standards avoid ambiguity across time zones and locales.

Supported formats

Timezones

All timestamps returned by the Demand API are in UTC (Coordinated Universal Time) by default, regardless of the local timezone of the accommodation.

• This ensures consistency across partners operating in different regions.
• Timezone offsets (e.g. +01:00, -05:00) may be present but always represent the same UTC time regardless of source.

If you need to display local times to users, convert timestamps to local time using appropriate libraries (e.g. moment-timezone, luxon, or native Intl.DateTimeFormat).

Best practice: Avoid hardcoded timezone offsets. Always convert from UTC dynamically based on user or property location.

Date constraints

Some endpoints accept date ranges. The following constraints apply to ensure data quality and API performance:

Orders/details (created, start or updated)

• Range: Must be within 1 year from the current date.
• Interval: Maximum 7-day range between (from and to).

Checkin/checkout dates

• checkin- Must be within 500 days from today.
• checkout - Must be:
  • After the checkin date.
  • Between 1 and 90 days after checkin.
  • Also fall within the 500 days future window.

Instalment dates

In some examples you will find:

• !TODAY! - The date of the API call / booking.
• !START_DATE! - The property’s checkin date.
• !END_DATE! - The checkout date.

Replace these values with your actual checkin or checkout dates when making the calls.

Durations

Some fields, such as cancellation windows in car rental policies, use the ISO-8601 duration format to represent time intervals.

This format starts with P (period) and may include:

• Days: P7D = 7 days.
• Hours: PT48H = 48 hours.
• Weeks: P1W = 1 week.

Examples in car rental policies object:

{
  "request_id": "01k0byb51sdq8fezk7xpthd9qx",
  "data": [
    {
      "car": 284602,
      "deal": null,
      "policies": {
        "cancellation": {
          "type": "free_cancellation",
          "details": {
            "context": "before_pickup",
            "duration": "PT48H"
          }
        },

The table below shows how to interpret duration + context combinations:

See schema definitions for valid patterns.

Code standards

Country codes

All country-related fields in the Demand API follow the ISO 3166-1 alpha-2 standard (two-letter country codes) always in lowercase.

This ensures consistency across regions and simplifies localisation.

Always pass the correct country code for the booker’s origin to comply with regional legal and pricing requirements.

Currency codes

Currency codes follow the ISO 4217 standard (3-letter uppercase format).

Example: "booker_currency": "GBP" indicates that the booker is using British Pounds.

• Format: Three-letter ISO 4217 currency code.
• Pattern: ^[A-Z]{3}$
• Case: Uppercase.
• Usage: Applies to all pricing-related fields.

Never assume a fixed list of currencies. Always use the API-provided list to handle regional pricing and preferences.

Language codes

Language codes follow the IETF BCP 47 format.

• Format: IETF language tag.
• Pattern: ^[a-z]{2}(-[a-z]{2})?$ (e.g. en, en-us, zh-cn)
• Case: Always lowercase.

Use full language codes (e.g. en-gb, not just en) for accurate localisation. If no exact match is available, a fallback will be used automatically.

Enum values

Some fields accept specific string values and are case-sensitive.

Input validation and case sensitivity

Developer tips

• Store and transmit all dates in UTC. Convert to local time only for display.

• Use server-side UTC handling to avoid drift across time zones.

• Always retrieve valid country_code, currency, and language values from the respective endpoints to ensure alignment with Booking.com’s supported list.

  • Countries
  • Currencies
  • Languages

• When testing, simulate edge cases:

  • Near-500-day checkin windows.
  • Maximum 7-day date range for order queries.
  • Invalid enums or missing language codes.

• When testing, ensure your integration can correctly interpret ISO-8601 durations returned in responses (e.g. PT1H, P2D, P1DT12H). Use parsing libraries that support this standard and handle edge cases like zero-duration (PT0S) or uncommon formats.

Proactively validate all inputs in sandbox environment if possible before sending requests to minimise integration errors and reduce load on the API.