> ## Documentation Index > Fetch the complete documentation index at: https://docs.selfbook.com/llms.txt > Use this file to discover all available pages before exploring further. # Hotel Search > Returns hotel search results ## OpenAPI ````yaml post /rest/v1/hotel/search openapi: 3.0.4 info: title: Selfbook Travel API version: '1.0' description: | This is the OpenAPI specification for `Selfbook Travel API`. servers: - url: https://sandbox.travel.selfbook.com description: Sandbox server - url: https://travel.selfbook.com description: Production security: [] paths: /rest/v1/hotel/search: post: description: | Returns hotel search results operationId: GetAvailability requestBody: required: true content: application/json: schema: type: object properties: stay_info: description: Parameters related to stay duration and guest count type: object properties: check_in_date: description: A date in 'YYYY-MM-DD' format example: '2024-11-20' type: string check_out_date: description: A date in 'YYYY-MM-DD' format example: '2024-11-21' type: string guests: type: object properties: adults: description: Number of adults type: integer example: 1 children: description: Number of children type: integer example: 1 filter: description: >- Parameters related to filtering by location or hotel information type: object properties: location: description: Location filtering parameters type: object properties: type: description: >- Location filter type. Either 'iata_code' or 'coordinates' type: string enum: - iata_code - coordinates example: iata_code details: description: Detail parameters related to location filter type type: object properties: iata_code: description: >- City or airport iata code for location based search. Note - only used when location type is set to iata_code. type: string example: ORD latitude: description: >- Latitude value used for gps point of location based search. Note - only used when location type is set to coordinates. type: string example: 40.7580033 longitude: description: >- Longitude value used for gps point of location based search. Note - only used when location type is set to coordinates. type: string example: -73.9868562 radius: description: Search radius parameters type: object properties: value: description: Numerical value used for location radius type: integer example: 5 minimum: 1 maximum: 35 type: description: >- Unit type for distance calculation. Note either mi for miles or km for kilometers. type: string example: km hotel: oneOf: - title: Single-property search description: >- Search by a specific hotel chain and property code. A name can be included for additional filtering. type: object properties: name: description: >- Hotel name filter. Can be a partial string. Minimum three characters for filtering to work. type: string example: Holiday Inn chain_code: description: Hotel chain code example: HI type: string property_code: description: Hotel property code example: E8597 type: string - title: Multiple-property search description: >- Provide an array of hotel chain and property codes. Additional filtering unsupported. type: array items: type: object properties: chain_code: description: Hotel chain code example: HI type: string property_code: description: Hotel property code example: E8597 type: string ignore_availability: type: boolean description: >- Return hotel data even if there is no availability. NOTE - no rates will be returned if this is true. example: false tripadvisor_ids: type: array items: type: string description: A TripAdvisor ID string example: - '248749' pagination: type: object properties: pagination_token: type: string description: >- Token used to retrieve paginated search results. It's a UUID, so it's unique to each query. example: 103f701e-39ad-4453-a375-2a9510b4d1c3 page_number: type: number description: Current page number example: 1 examples: Search for hotels near Chicago O'Hare airport: value: stay_info: check_in_date: '2024-11-20' check_out_date: '2024-11-21' guests: adults: 1 filter: location: type: iata_code details: iata_code: ORD radius: value: 5 type: mi Search for hotels near Times Square by lat/long: value: stay_info: check_in_date: '2024-11-20' check_out_date: '2024-11-21' guests: adults: 1 filter: location: type: coordinates details: latitude: 40.7580033 longitude: -73.9868562 radius: value: 5 type: mi Search for Holiday Inn locations near Times Square by lat/long and name: value: stay_info: check_in_date: '2024-11-20' check_out_date: '2024-11-21' guests: adults: 1 filter: location: type: coordinates details: latitude: 40.7580033 longitude: -73.9868562 radius: value: 5 type: mi hotel: name: holiday inn Search for Holiday Inn locations in Des Moines by name: value: stay_info: check_in_date: '2024-11-20' check_out_date: '2024-11-21' guests: adults: 1 filter: location: type: iata_code details: iata_code: DSM radius: value: 5 type: mi hotel: name: holiday inn Look up the Holiday Inn Express Downtown Omaha by hotel code: value: stay_info: check_in_date: '2024-11-20' check_out_date: '2024-11-21' guests: adults: 1 filter: hotel: chain_code: HI property_code: E8597 Search for availability at multiple, specific properties: value: stay_info: check_in_date: '2024-11-20' check_out_date: '2024-11-21' guests: adults: 1 filter: hotel: - chain_code: HI property_code: E8597 - chain_code: WA property_code: '51768' responses: '200': description: OK content: application/json: schema: type: object properties: pagination: type: object properties: page_number: type: number description: Current page number example: 1 page_size: type: number description: Number of items per page example: 25 total_pages: type: number description: Total number of pages returned for search query example: 3 total_items: type: number description: Total number of items available for search query example: 63 pagination_token: type: string description: >- Token used to retrieve paginated search results. It's a UUID, so it's unique to each query. example: 103f701e-39ad-4453-a375-2a9510b4d1c3 currency_exchange_rates: type: array items: type: object properties: conversion_factor: description: >- Conversion rate used to calculate conversion to USD. Conversions should always be treated as estimates. example: 1.1037528 type: number source_currency: description: >- ISO 4217 currency code of source rates. Source rates are those returned in the search results, e.g. the rate in the hotel's local currency. example: EUR type: string target_currency: description: ISO 4217 currency code of target rate. Always USD. example: USD type: string results: type: array items: $ref: '#/components/schemas/HotelSearchResult' missing_tripadvisor_ids: type: array items: type: string description: >- TripAdvisor ids that were not able to be mapped to known hotel chain and property codes. Only shows if tripadvisor_ids are included in the request. example: 555doesnotexist '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/REST-401' '403': $ref: '#/components/responses/REST-403' security: - BasicAuthentication: [] components: schemas: HotelSearchResult: type: object properties: chain_code: description: Hotel chain code identifier type: string example: HI property_code: description: Hotel property code identifier type: string example: E8597 name: description: Hotel name type: string example: HOLIDAY INN EXP STES DTWN OLD MARKE address: description: Property address object type: object properties: street: description: Street address type: string example: 2431 FARNAM STREET city: description: City type: string example: OMAHA state_providence: description: State or Province type: string example: NE country_code: description: Country code type: string example: US postal_code: description: Postal code type: string example: '68131' geolocation: description: Property geolocation information type: object properties: latitude: description: Property latitude value type: number example: 41.2573 longitude: description: Property longitude value type: number example: -95.9484 availability: description: Does the hotel have availability based on the search query? type: boolean example: true email: description: Property email. This may or may not be returned. type: string example: admin@hoteldomain.com phone: description: Property phone number type: string example: '14025093451' fax: description: Property fax number type: string example: '14025093461' ada_compliant: description: Is this property ADA compliant? type: boolean example: true check_in_time_local: description: Local check in time (24h format) type: string example: '15:00' check_out_time_local: description: Local check out time (24h format) type: string example: '11:00' lowest_rate: description: Lowest available rate based on the search query type: object properties: total_price: description: Total price type: number example: 122.89 base_price: description: Base price type: number example: 104 total_taxes: description: Total taxes type: number example: 18.89 taxes_and_fees_included: description: Signify whether a `total_price` includes the taxes and fees. example: false type: boolean currency_code: description: Currency code type: string example: USD rating: description: Hotel rating type: object properties: value: description: Hotel rating value type: number example: 2 provider: description: Hotel rating provider type: string example: NTM michelin_keys_rating: description: Michelin Keys rating value type: string forbes_travel_guide_rating: description: Forbes Travel Guide rating value type: string hotel_network_affiliation: description: Hotel network affiliation value type: string images: description: Hotel images data type: array items: description: Hotel image item type: object properties: url: description: Image URL type: string example: >- https://travelport.leonardocontentcloud.com/imageRepo/7/0/127/847/591/OMAOM_6502858112_E.jpg caption: description: Image caption type: string example: Hotel Exterior size: description: >- Image size. Valid values include: ExtraLarge, Large, Medium, Small type: string example: ExtraLarge category: description: Image category identifier type: number example: 1 amenities: description: Hotel amenities data type: array items: description: Hotel amenity item type: object properties: description: description: Amenity description type: string example: Ice machine code: description: Amenity code type: number example: 52 category: description: Amenity category name type: string example: Bar / Lounge rooms: description: Hotel rooms data. type: array items: description: Hotel room information. type: object properties: room_name: description: Room name without bed information type: string example: Standard Room Garden Views with Balcony room_name_with_beds: description: Room name including bed information type: string example: >- Standard Room Garden Views with Balcony, One Double Bed, Two Single Beds room_type_ota_code: description: Room type OTA code type: number example: 82 bed_types: description: Bed types for room type: array items: description: Bed type information type: object properties: bed_type: description: Bed type type: string example: Queen Bed(s) quantity: description: Bed type quantity type: number example: 2 size: description: Bed size type: string example: 160 cm X 200 cm room_amenities: description: Hotel room amenities type: array items: description: Room amenity information type: object properties: description: description: Room amenity description type: string example: Non-smoking code: description: Room amenity code type: number example: 74 max_occupancy: description: Maximum room occupancy type: number example: 5 room_characteristics: description: Hotel room characteristics type: object properties: category: description: Hotel room category characteristic type: object properties: description: description: Category description type: string example: Room code: description: Category code type: number example: 42 class: description: Hotel room class characteristic type: object properties: description: description: Class description type: string example: Standard code: description: Class code type: number example: 82 view: description: Hotel room view characteristic type: object properties: description: description: View description type: string example: City views code: description: View code type: number example: 3 other_features: description: Hotel room other features characteristic type: array items: description: Other features items type: string example: Walk In Shower room_images: description: Hotel room images data type: array items: description: Hotel room image item type: object properties: url: description: Image URL type: string example: >- https://travelport.leonardocontentcloud.com/imageRepo/7/0/127/847/591/OMAOM_6502858112_E.jpg caption: description: Image caption. Can be null if no caption is available. type: string nullable: true example: Hotel Exterior size: description: >- Image size. Valid values include: ExtraLarge, Large, Medium, Small type: string example: ExtraLarge category: description: Image category. Can be null if no category is available. type: string nullable: true example: Room rates: description: Hotel room rate data type: array items: description: >- Room rate information. You should pass this entire object to Selfbook to create a reservation. type: object properties: booking_code: description: Booking code for room rate type: string example: 2QN57JU channel_code: description: Channel code for room rate type: string example: SBT1 rate_type: description: >- Rate type identifier. Currently can be flexible_rate, lowest_rate, or private_access_rate type: string example: flexible_rate pcc: description: Internal rate identifier type: string example: KR5 rate_name: description: >- Rate name. Currently can be Flexible Rate, Lowest Rate, or Private Access Rate type: string example: Flexible Rate room_name: description: Room name without bed information type: string example: Standard Room Garden Views with Balcony room_name_with_beds: description: Room name including bed information type: string example: >- Standard Room Garden Views with Balcony, One Double Bed, Two Single Beds price: description: Price information for room rate type: object properties: total_price: description: Total price type: number example: 164.24 base_price: description: Base price type: number example: 139 total_taxes: description: Total taxes type: number example: 25.24 additional_fees: description: Additional fees type: number example: 0 taxes_and_fees_included: description: >- Signify whether a `total_price` includes the taxes and fees. example: false type: boolean currency_code: description: Currency code type: string example: USD nightly_breakdown: description: Array of the rate's nightly breakdowns type: array items: type: object properties: date: description: The date the nightly breakdown applies to type: string example: '2024-09-12' total_price: description: The total for the night. type: string example: 1501.25 currency_code: description: Currency code type: string example: USD terms: description: Rate and payment terms type: object properties: rate_payment_info: description: Type of rate payment (usually PrePay or PostPay) type: string example: PrePay guarantee_type: description: Type of guarantee required example: DepositRequired type: string refundable: description: Is the rate refundable? type: boolean cancel_note: description: Note left if cancel penalties are unavailable type: string example: '' cancel_penalties: description: Penalties for cancellation type: array items: type: object properties: deadline_local: description: >- Local date time deadline for when the cancellation fee will be enforced type: string example: '2024-09-17T00:00:00-05:00' cancel_short_description: description: >- Short description of the cancellation policy and penalties type: string example: >- An estimated cancellation fee of 177.44 USD applies starting from 2024-09-17T00:00-05:00[America/Chicago]. penalty: description: Object describing the penalty amount. type: object properties: estimated_amount: description: Is the penalty amount estimated? type: boolean example: true currency_amount: description: Amount of currency for the penalty type: object properties: amount: description: Amount type: number example: 177.44 currency: description: Currency code type: string example: USD original_penalty_info: description: Original penalty information type: string example: 100% included_perks: description: Included perks for room rate type: object additionalProperties: type: string example: Complimentary Wi-Fi: Complimentary Wi-Fi Complimentary breakfast: Daily breakfast included expiration: description: ISO 8601. type: string example: '2024-05-20T00:00:00Z' Error: type: object properties: code: type: integer description: Numeric error code. example: 2001 details: type: array description: One or more additional details about error condtion. items: type: object properties: message: description: A more detailed error message. type: string example: check_out_date is missing field: description: >- Included for validation errors. Indicating the path to the problem field. type: array items: type: string example: check_out_date message: type: string description: A summary of the error. example: >- Unable to process your request. Missing or invalid request parameters. type: type: string enum: - APPLICATION_ERROR - BOOKING_CANCELLATION_ERROR - BOOKING_CREATION_ERROR - BOOKING_ERROR - PAYMENT_PROCESSING_ERROR - VALIDATION example: VALIDATION responses: REST-401: description: | Unauthorized the API key token is missing, invalid, or expired REST-403: description: | Forbidden the API key token cannot access the specified resource securitySchemes: BasicAuthentication: type: http description: | Basic authentication where: - user-id is a partner account ID - user-password is an API key token associated with the partner account scheme: basic ````