TypeScript types — OpenBookings API reference

This page documents the TypeScript types you can use when integrating the OpenBookings API in a TypeScript project. Copy them directly into your codebase or import them from a shared types package. ResolvedRoom is the authoritative shape of every object in the array returned by GET /api/query.

`HotelSearchInput`

The parameter object that maps to the query string of GET /api/query. Use this type to build and validate your search request before sending it to the API.

/** Input parameters for the hotel/room search query */
export interface HotelSearchInput {
  lat: number;
  lon: number;
  checkin: string;   // YYYY-MM-DD
  checkout: string;  // YYYY-MM-DD
  adults: number;
  children: number | null;
  rooms: number;
}

Field	Type	Required	Notes
`lat`	`number`	Yes	Latitude of the search center
`lon`	`number`	Yes	Longitude of the search center
`checkin`	`string`	Yes	Check-in date, `YYYY-MM-DD`
`checkout`	`string`	Yes	Check-out date, `YYYY-MM-DD`
`adults`	`number`	Yes	Number of adult guests
`children`	`number \| null`	No	Number of child guests; `null` treated as `0`
`rooms`	`number`	Yes	Number of rooms

`HotelSearchResult`

A simplified type that represents a basic room result. The live API returns ResolvedRoom objects, not HotelSearchResult objects. This type is retained for reference but you should use ResolvedRoom when typing API responses.

/** Simplified room result — use ResolvedRoom for live API responses */
export interface HotelSearchResult {
  property_id: string;
  property_name: string;
  city: string;
  country: string;
  room_id: string;
  room_name: string;
  room_description: string;
  price_per_night: number;
  total_price: number;
  currency: string;
}

HotelSearchResult is a simplified type. The live GET /api/query endpoint returns ResolvedRoom objects, which include pricing detail, modifier fields, rate plan data, and occupancy constraints not present here.

`ResolvedRoom`

The actual response type returned by GET /api/query. Every element of the response array conforms to this interface.

export interface ResolvedRoom {
  // Hotel
  hotel_id: string;
  hotel_name: string;
  hotel_slug: string;
  city: string;
  country: string;

  // Room
  room_id: string;
  room_name: string;
  room_description: string;
  base_occupancy: number;
  max_adults: number;
  max_children: number;

  // Rate plan
  rate_plan_id: string;
  rate_plan_name: string;
  currency: string;
  is_refundable: boolean;
  cancellation_policy: string;
  min_stay: number;
  max_stay: number | null;

  // Pricing (calculated)
  subtotal: number;           // sum of nightly base prices
  total_price: number;        // after all modifiers applied
  applied_modifiers: ModifierType[];
}

Show Field descriptions

string

Unique identifier for the property.

string

Display name of the hotel.

string

URL-friendly slug for building deep links to the property page.

string

City where the property is located.

string

Country where the property is located.

string

Unique identifier for the room type.

string

Display name of the room (e.g. “Deluxe King”).

string

Full text description of the room.

number

Number of guests covered by the standard nightly rate. Extra guests above this count may trigger the extra_guest modifier.

number

Maximum number of adult guests the room can accommodate.

number

Maximum number of child guests the room can accommodate.

string

Unique identifier for the rate plan.

string

Display name of the rate plan.

string

ISO 4217 currency code for all price fields.

boolean

Whether the rate allows cancellation for a full refund.

string

Human-readable cancellation terms.

number

Minimum number of nights required under this rate plan.

number | null

Maximum number of nights allowed. null means no upper limit.

number

Sum of nightly base prices before stay-level discounts (length_of_stay, early_bird) are applied. Rounded to two decimal places.

number

Final price after all modifiers. This is the amount to display to the guest. Rounded to two decimal places.

ModifierType[]

List of modifier types that changed the price. Empty array means no modifiers fired.

`ModifierType`

A union of the rate modifier categories the pricing engine supports. These strings appear in ResolvedRoom.applied_modifiers.

type ModifierType =
  | 'day_of_week'
  | 'length_of_stay'
  | 'early_bird'
  | 'last_minute'
  | 'extra_guest'

Value	Description
`day_of_week`	Surcharge applied to nights that fall on specific days of the week
`length_of_stay`	Discount for stays that meet a minimum night threshold
`early_bird`	Discount for bookings made a set number of days before arrival
`last_minute`	Adjustment applied when booking close to the arrival date
`extra_guest`	Per-night surcharge for each guest above `base_occupancy`

Only one discount modifier (length_of_stay or early_bird) can fire per room. The eligible modifier with the lowest configured sort_order takes precedence. Surcharge modifiers can all fire simultaneously.

`AdjustmentType`

Specifies whether a modifier’s adjustment_value is a fixed currency amount or a percentage of the subtotal.

type AdjustmentType = 'flat' | 'percent'

Value	Description
`flat`	A fixed currency amount added to or subtracted from the price
`percent`	A percentage of the relevant base or subtotal amount

Overview

Endpoints

Data Types

TypeScript types — OpenBookings API reference

`HotelSearchInput`

`HotelSearchResult`

`ResolvedRoom`

`ModifierType`

`AdjustmentType`

​HotelSearchInput

​HotelSearchResult

​ResolvedRoom

​ModifierType

​AdjustmentType

`HotelSearchInput`

`HotelSearchResult`

`ResolvedRoom`

`ModifierType`

`AdjustmentType`