Availability

The availability endpoint is the starting point for booking hotels through the TripEdge API. It allows you to search for available hotels based on location, dates, and room configuration.

The availability request model

The availability request contains all the parameters needed to search for hotels. You must provide exactly one location parameter along with dates and room configuration.

Properties

Name
destination_id
Type
string
Description
Internal destination identifier. Mutually exclusive with other location params.
Name
place_id
Type
string
Description
Google Places ID for the destination. Mutually exclusive with other location params.
Name
coordinates
Type
object
Description
Latitude and longitude coordinates. Contains lat and lng properties.
Name
radius
Type
integer
Description
Search radius in meters when using coordinates. Default: 10000, Max: 50000.
Name
hotel_ids
Type
array of integers
Description
Array of specific hotel IDs to search. Maximum 2000 hotels.
Name
check_in
Type
string
Description
Check-in date in YYYY-MM-DD format. Required.
Name
check_out
Type
string
Description
Check-out date in YYYY-MM-DD format. Required.
Name
rooms
Type
array of Room
Description
Array of room configurations. Maximum 8 rooms per search. Required.
Name
filters
Type
AvailabilityFilter
Description
Optional filters for price range, star rating, amenities, etc.

Room object

Name
adults
Type
integer
Description
Number of adults per room. Range: 1-14. Required.
Name
children
Type
integer
Description
Number of children per room. Range: 0-6. Required.
Name
children_ages
Type
array of integers
Description
Array of child ages (0-17 for each child). Required.

AvailabilityFilter object

Name
price_range
Type
array
Description
Tuple of [min, max] price values.
Name
star_rating
Type
array of numbers
Description
Array of star ratings to filter by (e.g., [4.0, 5.0]).
Name
property_types
Type
array of strings
Description
Property types to include (e.g., ["hotel", "resort"]).
Name
amenities
Type
array of strings
Description
Required amenities (e.g., ["pool", "wifi"]).
Name
room_type
Type
string
Description
Specific room type filter.
Name
sort_by
Type
string
Description
Sort field for results.

The availability response model

AvailabilitySearchResponse

Name
session_id
Type
string
Description
Unique session identifier (UUID). Use this for subsequent hotel and booking calls.
Name
search_completed
Type
boolean
Description
Whether the search has completed across all vendors.
Name
search
Type
AvailabilityRequest
Description
The original search request parameters.
Name
metadata
Type
SearchMetadata
Description
Aggregated metadata about search results.
Name
results
Type
array of HotelResult
Description
Array of hotels with their available rates.
Name
expires_at
Type
string
Description
ISO 8601 timestamp when this session expires.

SearchMetadata object

Name
total_hotels
Type
integer
Description
Total number of hotels returned.
Name
total_pages
Type
integer
Description
Total number of pages available.
Name
max_price_per_night_avg
Type
number
Description
Highest average price per night across all results.
Name
max_price_inclusive
Type
number
Description
Highest total inclusive price across all results.
Name
nights
Type
integer
Description
Number of nights for the stay.
Name
rooms
Type
integer
Description
Number of rooms requested.
Name
center_coordinates
Type
Coordinates
Description
Center point coordinates of the search area.

HotelResult object

Name
hotel
Type
HotelDetails
Description
Hotel information including name, location, amenities.
Name
rates
Type
array of HotelRate
Description
Available rates for this hotel. May be null if no rates available.

HotelDetails object

Name
id
Type
integer
Description
Unique hotel identifier.
Name
name
Type
string
Description
Hotel name.
Name
stars
Type
number
Description
Star rating (1.0-5.0).
Name
rating
Type
number
Description
Guest rating score.
Name
review_count
Type
integer
Description
Number of guest reviews.
Name
lowest_rate
Type
HotelRate
Description
The lowest priced rate for quick display.
Name
lowest_brand_loyalty_rate
Type
HotelRate
Description
Lowest rate eligible for loyalty points.
Name
minimum_age
Type
integer
Description
Minimum guest age requirement.
Name
amenities
Type
array of HotelAmenity
Description
List of hotel amenities. See HotelAmenity enum below.
Name
check_in_begin_time
Type
string
Description
Earliest check-in time (HH:MM format).
Name
check_in_end_time
Type
string
Description
Latest check-in time (HH:MM format).
Name
check_out_before_time
Type
string
Description
Check-out deadline (HH:MM format).
Name
description
Type
string
Description
Hotel description text.
Name
images
Type
array of strings
Description
Array of image URLs.
Name
coordinates
Type
Coordinates
Description
Geographic coordinates with lat and lng.
Name
address
Type
HotelAddress
Description
Hotel address details.
Name
type
Type
string
Description
Property type (e.g., "hotel", "resort").
Name
exclusive
Type
boolean
Description
Whether this is an exclusive/premium property.

HotelAddress object

Name
address
Type
string
Description
Street address.
Name
city
Type
string
Description
City name.
Name
country
Type
string
Description
Country code or name.
Name
postal_code
Type
string
Description
Postal/ZIP code.
Name
region
Type
string
Description
State/province/region.

HotelRate object

Name
id
Type
string
Description
Unique rate identifier (UUID).
Name
hotel_id
Type
integer
Description
Associated hotel ID.
Name
rooms
Type
array of HotelRateRoom
Description
Room details for this rate.
Name
price_per_night_avg
Type
number
Description
Average price per night.
Name
price_per_night
Type
array of numbers
Description
Price for each night of the stay.
Name
price_chargeable
Type
number
Description
Total amount to charge the customer.
Name
price_per_room
Type
array of numbers
Description
Total price per room.
Name
price_per_night_per_room
Type
array of array of numbers
Description
Price breakdown per night per room.
Name
price_before_fees
Type
number
Description
Price before taxes and fees.
Name
price_fees
Type
number
Description
Taxes and fees amount.
Name
price_due_at_hotel
Type
number
Description
Amount payable at hotel (e.g., resort fees).
Name
price_inclusive
Type
number
Description
Total inclusive price.
Name
price_currency
Type
string
Description
Currency code (e.g., "USD").
Name
price_retail
Type
number
Description
Retail/comparison price if available.
Name
cancellation_policy
Type
string
Description
Either "Refundable" or "NonRefundable".
Name
cancellation_policy_datetime
Type
string
Description
Free cancellation deadline (ISO 8601).
Name
cancellation_policy_data
Type
array of CancellationPolicyData
Description
Detailed cancellation penalty schedule.
Name
brand_loyalty_eligible
Type
boolean
Description
Whether loyalty points can be earned.
Name
brand_loyalty_required
Type
boolean
Description
Whether loyalty number is required to book.
Name
brand_loyalty_name
Type
string
Description
Loyalty program name (e.g., "Marriott Bonvoy").
Name
elite
Type
HotelRateElite
Description
Elite/premium rate benefits if applicable.
Name
price_commission
Type
number
Description
Commission amount.
Name
price_commission_currency
Type
string
Description
Commission currency code.
Name
payment_type
Type
string
Description
Payment type ("account" or "credit_card").

HotelRateRoom object

Name
name
Type
string
Description
Room name/type.
Name
board
Type
string
Description
Board type: RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).
Name
room_data
Type
HotelRateRoomData
Description
Detailed room information.
Name
price_per_night_avg
Type
number
Description
Average price per night for this room.
Name
price_per_night
Type
array of numbers
Description
Price for each night.
Name
price_chargeable
Type
number
Description
Total chargeable amount for this room.
Name
price_per_room
Type
number
Description
Total price for this room.
Name
price_before_fees
Type
number
Description
Price before fees.
Name
price_fees
Type
number
Description
Fees amount.
Name
price_due_at_hotel
Type
number
Description
Amount due at hotel.
Name
price_inclusive
Type
number
Description
Inclusive price.
Name
price_currency
Type
string
Description
Currency code.
Name
fees
Type
array of HotelRateFee
Description
Itemized fees.
Name
deposit_per_accomodation_per_night
Type
number
Description
Deposit amount per accommodation per night.
Name
deposit_currency
Type
string
Description
Deposit currency.
Name
adults
Type
integer
Description
Number of adults this room accommodates.
Name
children
Type
integer
Description
Number of children this room accommodates.
Name
children_ages
Type
array of integers
Description
Ages of children.

HotelRateRoomData object

Name
images
Type
array of strings
Description
Room image URLs.
Name
size_sqft
Type
integer
Description
Room size in square feet.
Name
size_sqm
Type
integer
Description
Room size in square meters.
Name
max_occupancy
Type
integer
Description
Maximum total occupancy.
Name
max_adults
Type
integer
Description
Maximum adults allowed.
Name
max_children
Type
integer
Description
Maximum children allowed.
Name
beds
Type
array of HotelRateRoomBedType
Description
Bed configuration.
Name
amenities
Type
array of strings
Description
Room amenities.
Name
room_id
Type
integer
Description
Internal room type identifier.

HotelRateRoomBedType object

Name
name
Type
string
Description
Bed type name (e.g., "King", "Queen", "Twin").
Name
size
Type
string
Description
Bed size description.
Name
quantity
Type
integer
Description
Number of beds of this type.

HotelRateFee object

Name
name
Type
string
Description
Fee name/description.
Name
price
Type
number
Description
Fee amount.
Name
due_at_hotel
Type
boolean
Description
Whether this fee is paid at the hotel.
Name
price_currency
Type
string
Description
Fee currency.

CancellationPolicyData object

Name
from_datetime
Type
string
Description
Start datetime for this penalty period (ISO 8601).
Name
price_cancellation_penalty
Type
number
Description
Penalty amount if cancelled during this period.
Name
price_currency
Type
string
Description
Penalty currency.

HotelRateElite object

Name
room_upgrade_guaranteed
Type
boolean
Description
Guaranteed room upgrade.
Name
room_upgrade_subject_availability
Type
boolean
Description
Room upgrade subject to availability.
Name
late_checkout_guaranteed
Type
boolean
Description
Guaranteed late checkout.
Name
late_checkout_subject_availability
Type
boolean
Description
Late checkout subject to availability.
Name
welcome_amenity
Type
boolean
Description
Welcome amenity included.
Name
description
Type
array of strings
Description
Elite benefit descriptions.
Name
price_property_credit
Type
number
Description
Property credit amount.
Name
price_property_credit_currency
Type
string
Description
Property credit currency.
Name
property_credit_description
Type
string
Description
Property credit description.
Name
breakfast_included
Type
boolean
Description
Breakfast included.
Name
breakfast_description
Type
string
Description
Breakfast details.
Name
breakfast_pax
Type
integer
Description
Number of guests breakfast covers.
Name
travel_agent
Type
boolean
Description
Travel agent rate.

Coordinates object

Name
lat
Type
number
Description
Latitude.
Name
lng
Type
number
Description
Longitude.

Enums

HotelAmenity enum

Hotel-level amenities. Possible values:

accessibility-mobility - Accessibility features for mobility
adult-only - Adults only property
business-centre - Business center available
cash-machine - ATM/cash machine on-site
childcare-service - Childcare services available
concierge - Concierge services
gym - Fitness center/gym
laundry - Laundry services
lounge - Lounge area
parking - Parking available
pets-allowed - Pets allowed
pool - Swimming pool
restaurant - Restaurant on-site
room-service - Room service available
spa - Spa facilities
24-hour-front-desk - 24-hour front desk
wifi - WiFi available

RoomAmenity enum

Room-level amenities. Possible values include:

Internet & Entertainment:

internet_facilities, wireless_internet, tv, flat_screen_tv, satellite_channels, cable_channels, pay_per_view_channels, radio, dvd_player, cd_player, video, video_games, blu_ray_player, ipod_dock, streaming_service_like_netflix

Climate Control:

air_conditioning, heating, fan, air_conditioning_standalone_unit, single_room_ac_for_guest_accommodation

Bathroom:

private_bathroom, shared_bathroom, guest_bathroom, additional_bathroom, shower, bathtub, bathtub_or_shower, walk_in_shower, roll_in_shower, hairdryer, free_toiletries, towels, toilet, shared_toilet, bidet, toilet_paper, toothbrush, shampoo, conditioner, body_soap, shower_cap

Kitchen:

kitchen, kitchenette, refrigerator, microwave, coffee_machine, tea_coffee_maker, electric_kettle, minibar, dining_area, dining_table, dishwasher, oven, stovetop, toaster, kitchenware, high_chair

Furniture & Storage:

desk, wardrobe_or_closet, walk_in_closet, safe, laptop_safe, sofa, sofa_bed, sitting_area, clothes_rack, fold_up_bed, drying_rack_for_clothing, lockers

Bedding:

linens, towels_sheets_extra_fee, ironing_facilities, iron, extra_long_beds, feather_pillow, non_feather_pillow, hypoallergenic_pillow, electric_blankets, hypoallergenic

Views & Outdoor:

balcony, terrace, patio, sea_view, city_view, mountain_view, garden_view, lake_view, pool_view, river_view, landmark_view, view, inner_courtyard_view, quiet_street_view, outdoor_furniture, outdoor_dining_area

Accessibility:

accessible_by_elevator, upper_floors_accessible_by_elevator, upper_floors_accessible_by_stairs_only, entire_unit_wheelchair_accessible, entire_unit_located_on_ground_floor, toilet_with_grab_rails, adapted_bath, raised_toilet, lower_sink, emergency_cord_in_bathroom, shower_chair, visual_aids, auditory_guidance, hearing_accessible, accessible_room, transfer_shower

Pool & Spa:

private_pool, rooftop_pool, infinity_pool, pool_with_a_view, heated_pool, saltwater_pool, plunge_pool, hot_tub, spa_tub, sauna, open_air_bath, pool_towels

Services:

fireplace, wake_up_service, wake_up_service_alarm_clock, alarm_clock, concierge_services, executive_lounge_access, free_spa_access, free_gym_access, free_laundry_services, washing_machine, dryer, telephone, fax

Technology:

computer, laptop, ipad, smartphone, mobile_hotspot_device, game_console, game_console_xbox_360, game_console_ps2, game_console_ps3, game_console_nintendo_wii, game_console_xbox_one, game_console_wii_u, game_console_ps4

Room Features:

soundproof, carpeted, tile_marble_floor, hardwood_or_parquet_floors, tatami_traditional_japanese_flooring, private_entrance, interconnecting_rooms_available, window, socket_near_the_bed, adapter, reading_light, bathrobe, slippers, pajamas, yukata, suit_press, detached, semi_detached, private_apartment_in_building

Child & Safety:

childrens_cribs, child_safety_socket_covers, board_games_puzzles, books_dvds_or_music_for_children, baby_safety_gates, smoke_alarm, fire_extinguisher, carbon_monoxide_detector, carbon_monoxide_sources, key_access, key_card_access, privacy_curtain, earplugs

Complimentary Items:

wine_champagne, bottle_of_water, fruit, chocolate_cookies, wine_glasses, cleaning_products, hand_sanitizer, trash_cans, air_purifiers, barbecue, mosquito_net, pool_cover, shallow_end

Executive Lounge:

complimentary_breakfast_in_executive_lounge, complimentary_snacks_and_drinks_executive_lounge_all_day, complimentary_afternoon_snacks_and_drinks_executive_lounge, complimentary_evening_snacks_and_drinks_executive_lounge, complimentary_access_to_conference_room_business_areas, access_to_private_pool, access_to_private_beach, private_check_in_out_in_executive_lounge, free_newspapers_and_magazines_in_executive_lounge

HotelRateBoardType enum

Board/meal plan types:

RO - Room Only (no meals)
BB - Bed & Breakfast
HB - Half Board (breakfast + dinner)
FB - Full Board (all meals)
AI - All Inclusive (meals + drinks)

HotelRateCancellationPolicy enum

Cancellation policy types:

Refundable - Can be cancelled with full or partial refund before deadline
NonRefundable - No refund if cancelled

POST/v1/availability

Search availability

This endpoint allows you to search for available hotels based on location, dates, and room configuration. Returns a session ID that can be used to retrieve hotel details and proceed with booking.

Required attributes

Name
check_in
Type
string
Description
Check-in date in YYYY-MM-DD format.
Name
check_out
Type
string
Description
Check-out date in YYYY-MM-DD format.
Name
rooms
Type
array
Description
Array of room configurations with adults, children, and children_ages.

Location (exactly one required)

Name
destination_id
Type
string
Description
Internal destination identifier.
Name
place_id
Type
string
Description
Google Places ID.
Name
coordinates
Type
object
Description
Object with lat and lng properties.
Name
hotel_ids
Type
array
Description
Array of hotel IDs (max 2000).

Request

POST

/v1/availability

curl -X POST https://api.tripedge.com/v1/availability \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "place_id": "ChIJOwg_06VPwokRYv534QaPC8g",
    "check_in": "2024-03-15",
    "check_out": "2024-03-18",
    "rooms": [
      {
        "adults": 2,
        "children": 1,
        "children_ages": [5]
      }
    ]
  }'

Response

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "search_completed": true,
    "search": {
      "place_id": "ChIJOwg_06VPwokRYv534QaPC8g",
      "check_in": "2024-03-15",
      "check_out": "2024-03-18",
      "rooms": [
        {
          "adults": 2,
          "children": 1,
          "children_ages": [5]
        }
      ]
    },
    "metadata": {
      "total_hotels": 150,
      "total_pages": 3,
      "max_price_per_night_avg": 450.00,
      "max_price_inclusive": 1350.00,
      "nights": 3,
      "rooms": 1,
      "center_coordinates": {
        "lat": 40.7128,
        "lng": -74.0060
      }
    },
    "results": [
      {
        "hotel": {
          "id": 1234,
          "name": "Grand Hotel New York",
          "stars": 5.0,
          "rating": 4.5,
          "review_count": 1200,
          "lowest_rate": {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "price_chargeable": 750.00,
            "price_currency": "USD",
            "cancellation_policy": "Refundable"
          },
          "minimum_age": 18,
          "amenities": ["pool", "spa", "wifi", "gym", "restaurant"],
          "check_in_begin_time": "15:00",
          "check_in_end_time": "23:00",
          "check_out_before_time": "11:00",
          "description": "Luxury hotel in the heart of Manhattan...",
          "images": [
            "https://images.tripedge.com/hotels/1234/main.jpg",
            "https://images.tripedge.com/hotels/1234/lobby.jpg"
          ],
          "coordinates": {
            "lat": 40.7128,
            "lng": -74.0060
          },
          "address": {
            "address": "123 Main Street",
            "city": "New York",
            "country": "US",
            "postal_code": "10001",
            "region": "NY"
          },
          "type": "hotel",
          "exclusive": false
        },
        "rates": [
          {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "hotel_id": 1234,
            "rooms": [
              {
                "name": "Deluxe King Room",
                "board": "BB",
                "room_data": {
                  "images": ["https://images.tripedge.com/rooms/deluxe-king.jpg"],
                  "size_sqft": 450,
                  "size_sqm": 42,
                  "max_occupancy": 3,
                  "max_adults": 2,
                  "max_children": 1,
                  "beds": [
                    {
                      "name": "King",
                      "size": "king",
                      "quantity": 1
                    }
                  ],
                  "amenities": ["minibar", "safe", "balcony", "coffee-maker"],
                  "room_id": 101
                },
                "price_per_night_avg": 250.00,
                "price_per_night": [250.00, 250.00, 250.00],
                "price_chargeable": 750.00,
                "price_per_room": 750.00,
                "price_before_fees": 700.00,
                "price_fees": 50.00,
                "price_due_at_hotel": 0.00,
                "price_inclusive": 750.00,
                "price_currency": "USD",
                "fees": [
                  {
                    "name": "City Tax",
                    "price": 30.00,
                    "due_at_hotel": false,
                    "price_currency": "USD"
                  },
                  {
                    "name": "Service Fee",
                    "price": 20.00,
                    "due_at_hotel": false,
                    "price_currency": "USD"
                  }
                ],
                "adults": 2,
                "children": 1,
                "children_ages": [5]
              }
            ],
            "price_per_night_avg": 250.00,
            "price_per_night": [250.00, 250.00, 250.00],
            "price_chargeable": 750.00,
            "price_per_room": [750.00],
            "price_per_night_per_room": [[250.00, 250.00, 250.00]],
            "price_before_fees": 700.00,
            "price_fees": 50.00,
            "price_due_at_hotel": 0.00,
            "price_inclusive": 750.00,
            "price_currency": "USD",
            "price_retail": 850.00,
            "cancellation_policy": "Refundable",
            "cancellation_policy_datetime": "2024-03-14T23:59:00Z",
            "cancellation_policy_data": [
              {
                "from_datetime": "2024-03-14T23:59:00Z",
                "price_cancellation_penalty": 250.00,
                "price_currency": "USD"
              }
            ],
            "brand_loyalty_eligible": true,
            "brand_loyalty_required": false,
            "brand_loyalty_name": "Marriott Bonvoy",
            "elite": null,
            "price_commission": 75.00,
            "price_commission_currency": "USD",
            "payment_type": "account"
          }
        ]
      }
    ],
    "expires_at": "2024-03-15T12:00:00Z"
  },
  "success": true,
  "message": null
}

GET/v1/availability/debug/:session_id

Get availability by session

This endpoint allows you to retrieve availability search results by session ID. Useful for polling or retrieving cached results.

Path parameters

Name
session_id
Type
uuid
Description
The session ID from a previous availability search.

Request

GET

/v1/availability/debug/550e8400-e29b-41d4-a716-446655440000

curl https://api.tripedge.com/v1/availability/debug/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "search_completed": true,
  "search": {
    "place_id": "ChIJOwg_06VPwokRYv534QaPC8g",
    "check_in": "2024-03-15",
    "check_out": "2024-03-18",
    "rooms": [{ "adults": 2, "children": 1, "children_ages": [5] }]
  },
  "metadata": {
    "total_hotels": 150,
    "total_pages": 3,
    "max_price_per_night_avg": 450.00,
    "max_price_inclusive": 1350.00,
    "nights": 3,
    "rooms": 1,
    "center_coordinates": { "lat": 40.7128, "lng": -74.0060 }
  },
  "results": [
    {
      "hotel": { /* full hotel details */ },
      "rates": [ /* full rate details */ ]
    }
  ],
  "expires_at": "2024-03-15T12:00:00Z"
}