Hotel API (v2)

Download OpenAPI description
Languages
Servers
Mock server
https://developer.spotnana.com/_mock/openapi/hotelapi/
Staging URL
https://apis.spotnana.com/

Hotel

These endpoints provide comprehensive functionality for managing hotel bookings. They enable users to search for hotels, check room rates and availability, create and modify bookings, and handle cancellations and rebooking.

Operations

Get hotel search results

Request

Get all available hotels for the requested search parameters.

Bodyapplication/jsonrequired
searchParamsobject(HotelSearchParams)required

The parameters required for searching hotels.

searchParams.​occupancyDatesobject(OccupancyDates)required

Occupancy values and dates for the hotel search.

searchParams.​occupancyDates.​occupancyArray of objects(Occupancy)required

List of occupancy details including the number of adults and children.

searchParams.​occupancyDates.​occupancy[].​numAdultsinteger>= 1required

The number of adults staying in the room.

Example: 1
searchParams.​occupancyDates.​occupancy[].​numChildreninteger

The number of children staying in the room.

Example: 0
searchParams.​occupancyDates.​checkInDateobject(DateTimeLocal)required

Local date and time represented in the ISO 8601 standard.

searchParams.​occupancyDates.​checkInDate.​iso8601string^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01...required
Example: "2017-07-21T17:32"
searchParams.​occupancyDates.​checkOutDateobject(DateTimeLocal)required

Local date and time represented in the ISO 8601 standard.

searchParams.​occupancyDates.​checkOutDate.​iso8601string^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01...required
Example: "2017-07-21T17:32"
searchParams.​searchByobjectrequired

Criteria used for searching hotels. The searchType field can contain one criteria per request.

searchParams.​searchBy.​searchTypestringrequired
Example: "AIRPORT"
Discriminator
searchParams.​searchBy.​airportstringrequired

IATA code of the airport. The search result will contain the list of hotels in close proximity to the specified airport.

Example: "LHR"
filtersobject(HotelSearchFilters)

Filters to refine the search result. Based on the user selected filters, the list of matching hotels will be displayed.

sortOptionsArray of objects(Hotel Sort Options)

Sort options for the search results.

userIdHotel User Identifier (object) or Hotel User Identifier (object)(HotelUserId)required
One of:

An identifier for the user involved in the hotel booking or search process.

userId.​userIdTypestringrequired
Example: "USER_ID"
userId.​userIdobject(UserId)required

User identifier

userId.​userId.​idstring(uuid)required
paginationParamsToken Based Pagination Request (object) or Token Based Pagination Request (object)(TokenBasedPaginationRequest)
One of:

The page token.

curl -i -X POST \
  https://developer.spotnana.com/_mock/openapi/hotelapi/v2/hotel/search \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "searchParams": {
      "occupancyDates": {
        "occupancy": [
          {
            "numAdults": 1,
            "numChildren": 0
          }
        ],
        "checkInDate": {
          "iso8601": "2017-07-21T17:32"
        },
        "checkOutDate": {
          "iso8601": "2017-07-21T17:32"
        }
      },
      "searchBy": {
        "searchType": "AIRPORT",
        "airport": "LHR"
      }
    },
    "filters": {
      "prepaidQualifier": "INCLUDE_PREPAID",
      "priceRange": {
        "min": {
          "amount": 510,
          "currencyCode": "GBP"
        },
        "max": {
          "amount": 510,
          "currencyCode": "GBP"
        }
      },
      "amenities": [
        "ECO_FRIENDLY"
      ],
      "chainCodes": [
        "string"
      ],
      "radius": {
        "length": 150,
        "unit": "MILE"
      },
      "starRatings": [
        0
      ],
      "nameQuery": "string",
      "eligibleForLoyalty": false,
      "showUnavailable": false,
      "payByPoints": false,
      "modifiableOnly": false,
      "rateTypes": [
        "PUBLISHED"
      ],
      "propertyTypes": [
        {
          "type": "ALL_SUITE",
          "description": "string"
        }
      ],
      "refundableOnly": false,
      "preferredOnly": false
    },
    "sortOptions": [
      {
        "sortBy": "PRICE",
        "sortOrder": "ASCENDING"
      }
    ],
    "userId": {
      "userIdType": "USER_ID",
      "userId": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      }
    },
    "paginationParams": {
      "requestType": "PAGE_TOKEN",
      "pageToken": "token"
    }
  }'

Responses

OK

Bodyapplication/json
hotelsArray of objects(Hotel Data)required

List of hotels matching the search criteria.

hotels[].​hotelDetailsKeystringrequired

Unique key for the hotel details.

Example: "Cg5TUE9UTkFOQTozMDc3NhIgCgIIARIMCgoyMDI0LTA="
hotels[].​hotelSpecobject(HotelSpec)required

Includes detailed specifications for a hotel, such as name, star rating, address, coordinates, amenities, and other information.

hotels[].​hotelSpec.​namestringrequired

Name of the hotel.

Example: "London Heathrow Marriott Hotel"
hotels[].​hotelSpec.​addressobject(PostalAddress)required

Postal Address Details

hotels[].​hotelSpec.​address.​addressLinesArray of stringsrequired

Address lines

Example: ["Golden Gate Bridge"]
hotels[].​hotelSpec.​address.​administrativeAreastring

Code of administrative area. For example: DL for Delhi, India. Highest administrative subdivision which is used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community (e.g. "Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. E.g. in Switzerland this should be left unpopulated.

Example: "CA"
hotels[].​hotelSpec.​address.​administrativeAreaNamestring

Name of administrative area. This is full name corresponding to administrativeArea. Like Delhi for DL area code. For some places, code and name maybe same as well like Tokyo.

Example: "California"
hotels[].​hotelSpec.​address.​descriptionstring

Address description

Example: "San Francisco Home"
hotels[].​hotelSpec.​address.​isDefaultboolean

Whether this address is default address in case multiple addresses are specified.

Example: true
hotels[].​hotelSpec.​address.​languageCodestring

BCP-47 language code of the contents of this address (if known). This is often the UI language of the input form or is expected to match one of the languages used in the address' country/region, or their transliterated equivalents. This can affect formatting in certain countries, but is not critical to the correctness of the data and will never affect any validation or other non-formatting related operations. Examples: "zh-Hant", "ja", "ja-Latn", "en".

Example: "en"
hotels[].​hotelSpec.​address.​localitystring

Generally refers to the city/town portion of the address.

Example: "San Francisco"
hotels[].​hotelSpec.​address.​locationCodestring

IATA 3-letter location code. See https://www.iata.org/en/services/codes.

Example: "LAX"
hotels[].​hotelSpec.​address.​organizationstring

The name of the organization at the address.

Example: "Spotnana"
hotels[].​hotelSpec.​address.​postalCodestring

Postal code of the address. This is a required field when setting for a user/legal entity/company etc.

Example: "94130"
hotels[].​hotelSpec.​address.​continentCodestring

2 letter continent code of the continent this address falls in.

Example: "AF"
hotels[].​hotelSpec.​address.​recipientsArray of strings

The recipient at the address.

hotels[].​hotelSpec.​address.​regionCodestringrequired

Region code of the country/region of the address.

Example: "US"
hotels[].​hotelSpec.​address.​regionNamestring

Region name of the country/region of the address.

Example: "America"
hotels[].​hotelSpec.​address.​revisioninteger(int32)
Example: 1
hotels[].​hotelSpec.​address.​sortingCodestring

Additional, country-specific, sorting code. This is not used in most regions. Where it is used, the value is either a string like "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number alone, representing the "sector code" (Jamaica), "delivery area indicator" (Malawi) or "post office indicator" (e.g. Côte d'Ivoire).

Example: "Jamaica"
hotels[].​hotelSpec.​address.​sublocalitystring

Sublocality of the address. This can be neighborhoods, boroughs, districts.

hotels[].​hotelSpec.​address.​timezonestring

Time zone of the address.

Example: "America/Los_Angeles"
hotels[].​hotelSpec.​address.​coordinatesobject(Latlng)

Latitude and Longitude for a Location

hotels[].​hotelSpec.​coordinatesobject(Latlng)required

Latitude and Longitude for a Location

hotels[].​hotelSpec.​coordinates.​latitudenumber(double)required

Latitude of the Location

Example: 77.1025
hotels[].​hotelSpec.​coordinates.​longitudenumber(double)required

Longitude of the Location

Example: 28.7041
hotels[].​hotelSpec.​contactInfoobject(ContactInfo)required

Provides contact information for a hotel.

hotels[].​hotelSpec.​contactInfo.​phoneArray of objects(PhoneNumber)required

List of phone numbers for the hotel.

hotels[].​hotelSpec.​contactInfo.​phone[].​countryCodeinteger(int32)

two digit country code

Example: 91
hotels[].​hotelSpec.​contactInfo.​phone[].​countryCodeSourcestring
Enum"UNSPECIFIED""FROM_NUMBER_WITH_PLUS_SIGN""FROM_NUMBER_WITH_IDD""FROM_NUMBER_WITHOUT_PLUS_SIGN""FROM_DEFAULT_COUNTRY"
Example: "FROM_NUMBER_WITH_PLUS_SIGN"
hotels[].​hotelSpec.​contactInfo.​phone[].​extensionstring

phone number extension

Example: "222"
hotels[].​hotelSpec.​contactInfo.​phone[].​isoCountryCodestring

ISO alpha-2 code

Example: "IN"
hotels[].​hotelSpec.​contactInfo.​phone[].​italianLeadingZeroboolean
Default false
Example: true
hotels[].​hotelSpec.​contactInfo.​phone[].​nationalNumberinteger(int64)
Example: 8150
hotels[].​hotelSpec.​contactInfo.​phone[].​numberOfLeadingZerosinteger(int32)
Default 0
Example: 1
hotels[].​hotelSpec.​contactInfo.​phone[].​preferredDomesticCarrierCodestring
Example: "7"
hotels[].​hotelSpec.​contactInfo.​phone[].​rawInputstring
Example: "77777"
hotels[].​hotelSpec.​contactInfo.​phone[].​typestring
Enum"UNKNOWN_TYPE""MOBILE""LANDLINE"
Example: "MOBILE"
hotels[].​hotelSpec.​contactInfo.​faxArray of strings

List of fax numbers for the hotel.

hotels[].​hotelSpec.​contactInfo.​emailArray of stringsrequired

List of email addresses for the hotel.

hotels[].​hotelSpec.​amenitiesArray of objects(Hotel Amenities)required

List of hotel amenities.

hotels[].​hotelSpec.​amenities[].​hotelAmenityTypestringrequired
Enum"TWENTY_FOUR_HOUR_FRONT_DESK""TWENTY_FOUR_HOUR_ROOM_SERVICE""TWENTY_FOUR_HOUR_SECURITY""ADJOINING_ROOMS""AIR_CONDITIONING""AIRLINE_DESK""ATM_CASH_MACHINE""BABY_SITTING""BBQ_PICNIC_AREA""BILINGUAL_STAFF"
Example: "ECO_FRIENDLY"
hotels[].​hotelSpec.​amenities[].​additionalInfostring

Amenity description

Example: "Complimentary in-room coffee or tea"
hotels[].​hotelSpec.​amenities[].​isComplimentaryboolean

Is Amenity complimentary

Example: true
hotels[].​hotelSpec.​descriptionsArray of objects(HotelDescription)

List of hotel descriptions.

hotels[].​hotelSpec.​imageSetsArray of objects(HotelImageSet)

List of hotel image sets.

hotels[].​hotelSpec.​hotelIdstringrequired

Unique hotel identifier.

Example: "SPOTNANA:1001"
hotels[].​hotelSpec.​brandCodestring

The code of hotel brand.

Example: "MC"
hotels[].​hotelSpec.​brandNamestring

Brand name of the hotel.

Example: "Marriott Hotel Brands"
hotels[].​hotelSpec.​chainCodestring

The code of hotel chain.

Example: "EM"
hotels[].​hotelSpec.​chainNamestring

Name of the hotel chain.

Example: "Marriott Hotels & Resorts"
hotels[].​hotelSpec.​propertyTypesArray of objects(Hotel Property Type)required

List of property types for the hotel.

hotels[].​hotelSpec.​propertyTypes[].​typestring(HotelPropertyEnum)required

Type of the property.

Enum"ALL_SUITE""ALL_INCLUSIVE_RESORT""APARTMENT""BED_AND_BREAKFAST""CABIN_OR_BUNGALOW""CAMPGROUND""CHALET""CONDOMINIUM""CONFERENCE_CENTER""CORPORATE_BUSINESS_TRANSIENT"
hotels[].​hotelSpec.​propertyTypes[].​descriptionstring

Description of the property type.

hotels[].​hotelSpec.​starRatingobject(HotelStarRatingInfo)required

Details about hotel star rating.

hotels[].​hotelSpec.​starRating.​starRatingnumber(float)[ 0 .. 5 ]required

Star rating of the hotel.

Example: 3
hotels[].​hotelSpec.​starRating.​ratingTypestring(Star Rating Type)required

Enum representing the type of star rating.

Enum"OFFICIAL""SELF_RATED"
hotels[].​hotelSpec.​additionalAmenitiesArray of strings

Additional amenities provided by the hotel.

hotels[].​hotelSpec.​checkinTimeobject(TimeLocal)

ISO8601 Local Time

hotels[].​hotelSpec.​checkoutTimeobject(TimeLocal)

ISO8601 Local Time

hotels[].​distanceobject(Length)required

Specifies the length or a distance.

hotels[].​distance.​lengthnumber(double)required

Distance from search point.

Example: 150
hotels[].​distance.​unitstringrequired

Unit of measure being applied.

Enum"UNKNOWN_UNIT""KM""MILE"
Example: "MILE"
hotels[].​policyInfoobject(CommonPolicyInfo)

Includes detailed information about a policy, such as its unique identifier, type, name, rules, version, and approval type.

hotels[].​hasNegotiatedRatesbooleanrequired

Indicates if the hotel has negotiated rates.

Example: false
hotels[].​preferencesArray of objects(Preference)

List of preferences applicable to the hotel.

hotels[].​rateInfoobject(HotelSearchRateInfo)required

Contains detailed rate information for a hotel search.

hotels[].​rateInfo.​averageNightlyRateobject(HotelRoomRate)required

Rate details for hotel room

hotels[].​rateInfo.​averageNightlyRate.​baseobject(Money)required

Money object containing details such as the amount, the currency code, and the converted amount.

hotels[].​rateInfo.​averageNightlyRate.​base.​amountnumber(double)required

The numeric value for the amount of money.

Example: 510
hotels[].​rateInfo.​averageNightlyRate.​base.​currencyCodestringrequired

The 3-letter currency code for the money amount (defined using ISO 4217 standard).

Example: "GBP"
hotels[].​rateInfo.​averageNightlyRate.​base.​convertedAmountnumber(double)

The converted currency and amount that has been converted (if a currency conversion has been requested). For example, if the call requests that money be sent in a specified currency (because the frontend requested the backend to send money in the user's preferred currency).

Example: 715.42
hotels[].​rateInfo.​averageNightlyRate.​base.​convertedCurrencystring

The 3-letter currency code for the converted currency (defined using ISO 4217 standard).

Example: "USD"
hotels[].​rateInfo.​averageNightlyRate.​base.​otherCoinageArray of objects(OtherCoinage)

List of the dollar amount in other coinage systems like reward points, cryptocurrency etc.

hotels[].​rateInfo.​averageNightlyRate.​taxobject(Money)required

Money object containing details such as the amount, the currency code, and the converted amount.

hotels[].​rateInfo.​averageNightlyRate.​tax.​amountnumber(double)required

The numeric value for the amount of money.

Example: 510
hotels[].​rateInfo.​averageNightlyRate.​tax.​currencyCodestringrequired

The 3-letter currency code for the money amount (defined using ISO 4217 standard).

Example: "GBP"
hotels[].​rateInfo.​averageNightlyRate.​tax.​convertedAmountnumber(double)

The converted currency and amount that has been converted (if a currency conversion has been requested). For example, if the call requests that money be sent in a specified currency (because the frontend requested the backend to send money in the user's preferred currency).

Example: 715.42
hotels[].​rateInfo.​averageNightlyRate.​tax.​convertedCurrencystring

The 3-letter currency code for the converted currency (defined using ISO 4217 standard).

Example: "USD"
hotels[].​rateInfo.​averageNightlyRate.​tax.​otherCoinageArray of objects(OtherCoinage)

List of the dollar amount in other coinage systems like reward points, cryptocurrency etc.

hotels[].​rateInfo.​averageNightlyRate.​roomFeesArray of objects(RoomFee)
hotels[].​rateInfo.​averageNightlyRate.​commissionobject(Commission)

Commision on rate

hotels[].​rateInfo.​averageNightlyRate.​taxBreakdownArray of objects(TaxBreakdown)

Tax breakdown

hotels[].​rateInfo.​averageNightlyRate.​includesCommissionboolean

Whether the rate includes commission

Example: false
hotels[].​rateInfo.​totalRateobject(HotelRoomRate)required

Rate details for hotel room

hotels[].​rateInfo.​totalRate.​baseobject(Money)required

Money object containing details such as the amount, the currency code, and the converted amount.

hotels[].​rateInfo.​totalRate.​base.​amountnumber(double)required

The numeric value for the amount of money.

Example: 510
hotels[].​rateInfo.​totalRate.​base.​currencyCodestringrequired

The 3-letter currency code for the money amount (defined using ISO 4217 standard).

Example: "GBP"
hotels[].​rateInfo.​totalRate.​base.​convertedAmountnumber(double)

The converted currency and amount that has been converted (if a currency conversion has been requested). For example, if the call requests that money be sent in a specified currency (because the frontend requested the backend to send money in the user's preferred currency).

Example: 715.42
hotels[].​rateInfo.​totalRate.​base.​convertedCurrencystring

The 3-letter currency code for the converted currency (defined using ISO 4217 standard).

Example: "USD"
hotels[].​rateInfo.​totalRate.​base.​otherCoinageArray of objects(OtherCoinage)

List of the dollar amount in other coinage systems like reward points, cryptocurrency etc.

hotels[].​rateInfo.​totalRate.​taxobject(Money)required

Money object containing details such as the amount, the currency code, and the converted amount.

hotels[].​rateInfo.​totalRate.​tax.​amountnumber(double)required

The numeric value for the amount of money.

Example: 510
hotels[].​rateInfo.​totalRate.​tax.​currencyCodestringrequired

The 3-letter currency code for the money amount (defined using ISO 4217 standard).

Example: "GBP"
hotels[].​rateInfo.​totalRate.​tax.​convertedAmountnumber(double)

The converted currency and amount that has been converted (if a currency conversion has been requested). For example, if the call requests that money be sent in a specified currency (because the frontend requested the backend to send money in the user's preferred currency).

Example: 715.42
hotels[].​rateInfo.​totalRate.​tax.​convertedCurrencystring

The 3-letter currency code for the converted currency (defined using ISO 4217 standard).

Example: "USD"
hotels[].​rateInfo.​totalRate.​tax.​otherCoinageArray of objects(OtherCoinage)

List of the dollar amount in other coinage systems like reward points, cryptocurrency etc.

hotels[].​rateInfo.​totalRate.​roomFeesArray of objects(RoomFee)
hotels[].​rateInfo.​totalRate.​commissionobject(Commission)

Commision on rate

hotels[].​rateInfo.​totalRate.​taxBreakdownArray of objects(TaxBreakdown)

Tax breakdown

hotels[].​rateInfo.​totalRate.​includesCommissionboolean

Whether the rate includes commission

Example: false
hotels[].​rateInfo.​isRefundablebooleanrequired

Set to true if the hotel rate is refundable.

Example: true
hotels[].​rateInfo.​rewardPointsEarnedArray of objects(Reward Points Earned)

Information about reward points earned.

hotels[].​rateInfo.​promotionalOffersArray of objects(Promotional Offer)

List of promotional offers applied to the hotel rate.

hotels[].​hotelCo2EmissionDetailobject(HotelCo2EmissionDetail)

The co2 emission detail for the hotel.

metadataobject(HotelSearchMetadata)required

Includes metadata for a hotel search.

metadata.​availableHotelChainsArray of objects(HotelChain)required

A list of available hotel chains.

metadata.​availableHotelChains[].​chainCodestring

The code of hotel chain.

Example: "EM"
metadata.​availableHotelChains[].​chainNamestring

The name of hotel chain.

Example: "Mariott"
metadata.​rateStatisticsobject(HotelRateStatistics)required

Contains statistical information about hotel search results.

metadata.​rateStatistics.​medianobject(HotelMedianRateInfo)required

Details median rate information for a hotel.

metadata.​rateStatistics.​median.​totalobject(Money)required

Money object containing details such as the amount, the currency code, and the converted amount.

metadata.​rateStatistics.​median.​total.​amountnumber(double)required

The numeric value for the amount of money.

Example: 510
metadata.​rateStatistics.​median.​total.​currencyCodestringrequired

The 3-letter currency code for the money amount (defined using ISO 4217 standard).

Example: "GBP"
metadata.​rateStatistics.​median.​total.​convertedAmountnumber(double)

The converted currency and amount that has been converted (if a currency conversion has been requested). For example, if the call requests that money be sent in a specified currency (because the frontend requested the backend to send money in the user's preferred currency).

Example: 715.42
metadata.​rateStatistics.​median.​total.​convertedCurrencystring

The 3-letter currency code for the converted currency (defined using ISO 4217 standard).

Example: "USD"
metadata.​rateStatistics.​median.​total.​otherCoinageArray of objects(OtherCoinage)

List of the dollar amount in other coinage systems like reward points, cryptocurrency etc.

metadata.​rateStatistics.​median.​baseobject(Money)required

Money object containing details such as the amount, the currency code, and the converted amount.

metadata.​rateStatistics.​median.​base.​amountnumber(double)required

The numeric value for the amount of money.

Example: 510
metadata.​rateStatistics.​median.​base.​currencyCodestringrequired

The 3-letter currency code for the money amount (defined using ISO 4217 standard).

Example: "GBP"
metadata.​rateStatistics.​median.​base.​convertedAmountnumber(double)

The converted currency and amount that has been converted (if a currency conversion has been requested). For example, if the call requests that money be sent in a specified currency (because the frontend requested the backend to send money in the user's preferred currency).

Example: 715.42
metadata.​rateStatistics.​median.​base.​convertedCurrencystring

The 3-letter currency code for the converted currency (defined using ISO 4217 standard).

Example: "USD"
metadata.​rateStatistics.​median.​base.​otherCoinageArray of objects(OtherCoinage)

List of the dollar amount in other coinage systems like reward points, cryptocurrency etc.

metadata.​rateStatistics.​sampleSizeinteger(int32)required

Size of the sample set used to calculate the statistics.

Example: 100
metadata.​rateStatistics.​policyTypestringrequired

Enumeration of policy types for rate statistics.

Enum"DEFAULT""SET_BY_ADMIN"
metadata.​showOnlyBaseFarebooleanrequired

Indicates if only base fare should be shown.

Example: false
metadata.​sessionIdstring

Unique session identifier for the search.

paginationParamsobject(TokenBasedPaginationResponse)required

Pagination response for token based pagination. Contains the next page token(if next page is available) and pagination parameters.

paginationParams.​nextPageTokenstring

The next page token to retrieve the next page of results. If it is empty, it indicates that there are no more pages to retrieve.

paginationParams.​currentPageSizeinteger(int32)required

The number of results in the current page.

Example: 10
Response
application/json
{ "hotels": [ {} ], "metadata": { "availableHotelChains": [], "rateStatistics": {}, "showOnlyBaseFare": false, "sessionId": "string" }, "paginationParams": { "nextPageToken": "string", "currentPageSize": 10 } }

Get hotel details

Request

Get details for a specific hotel.

Bodyapplication/jsonrequired
hotelDetailsKeystringrequired

A unique identifier for the hotel details.

corporateInfoobject(CorporateInfoV2)

Corporate data to be collected during the search request workflow.

occupancyDatesobject(OccupancyDates)

Occupancy values and dates for the hotel details.

filtersobject(HotelDetailsFilters)

Filters for hotel details.