API Reference

Hotel

Hotel API (v2)

Download OpenAPI description

HotelApi.json

HotelApi.yaml

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

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)

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)

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)

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)

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)

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.

Hotel API (v2)

Hotel

Get hotel search results

RequestExpand all

Responses

Get hotel details

RequestExpand all

Request

Request