edit

Check Hotels

Introduction

You can check for hotels available for any provided date range and pax information by specifying either a destination code or a list of hotel codes.

This resource is the first and the only required step before performing any booking but it is not the preferable way of doing because of higher probability of availability errors at the booking step.

Beware of Availability Errors

We strongly recommend using Check Hotel and Check Rate resources for retrieving the most recent availability and price information for hotels to prevent availability failures at the time of booking.

Because of higher amount of traffic populated on this step, most suppliers and Ratemarkt itself by nature serves the most of the availability information from cache storages. Serving from cache storages may cause outdated data being served and can be misleading for clients at the time of booking.

So it is highly recommended using further availability resources such as Check Hotel and Check Rate before proceeding to booking step in order to prevent booking failures caused by availability errors.

Definition

1
POST https://api.ratemarkt.com/v1/checkhotels

Query Object

Argument Type Required Description
destinationCode string optional* Destination code. Please note that destination based querying is prohibited and can only be enabled in case of special support inquiries because of the inefficient nature of this kind of queries. Please use hotel code based querying instead.
hotelCodes list[string] optional* List of hotel codes. Up to max. 500 hotel codes per query is permitted.
checkin string yes YYYY-MM-DD (ISO 8601) formatted date string. Eg. 2017-11-12
checkout string yes YYYY-MM-DD (ISO 8601) formatted date string. Eg. 2017-11-15
paxes list[Pax] yes List of pax objects. Each pax object corresponds to a room. Multi room queries need more than one pax object.
Pax.numberOfAdults integer yes Number of adults requested.
Pax.childrenAges list[integer] yes List of children requested specified by their ages.
currency string yes Three letter currency code (ISO-4217). **Please read the regarding note below.**
nationality string yes Two letter country code (ISO 3166-1 alpha-2) for occupants passport nationality.

About Optional* Arguments

You should provide either destinationCode or hotelCodes argument to get your availability query work.

Please note the use of currency parameter

Note that the currency parameter DOES NOT GUARANTEE the currency of rates returned by this resource. It only should be used to tell Ratemarkt to avoid unnecessary currency changes in the backyard and do its best to return in desired currency if available.

Please check each rate's individual currency in any case before proceeding to next steps.

Beware of Destination Based Queries

Some popular travel destinations contain huge amount of hotels thus your queries may take much longer time then expected.

We strongly recommend hotel list based queries so that you can perform your queries for only the hotels you interested in and get back corresponding results in much shorter times rather than retrieving a bulk.

Example Query Object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "hotelCodes": [
    "d31d12",
    "69af45",
    "984767"
  ],
  "checkin": "2017-07-22",
  "checkout": "2017-07-25",
  "paxes": [
    {
      "childrenAges": [],
      "numberOfAdults": 2
    }
  ],
  "currency": "USD",
  "nationality": "US"
}

Result Object

Argument Type Nullable Description
hotels list[Hotel] no List of available hotels
Hotel.hotelCode string no Unique hotel identifier
Hotel.hotelName string no Hotel name
Hotel.destinationCode string no Unique destination identifier
Hotel.destinationName string no Destination name
Hotel.countryCode string no Two letter country code (ISO 3166-1 alpha-2)
Hotel.rates list[Rate] no List of Rate objects. Each rate corresponds to a hotel room combined with a service level which means a bookable product with a price for each hotel.
Rate.rateType string no Type of the rate. There are three types:
  • NET: This type of rate can be selled by applying any margin on top of it.
  • SALE: Commissionable rate which should be selled exactly at the given rate.
  • DIRECT: Commissionable rate which the amount is payed directly to the hotelier by the occupants at the time of arrival.
For commissionable rates, the amount of commission for the merchant is denoted at Rate.commission field.
Rate.rateKey string no Unique identifier for each rate.
Rate.nonrefundable boolean yes Flag denoting whether the rate is refundable or not. It means that if any nonrefundable rate is booked, cancellation of that booking won't be refunded in any cases.

Value can be null in some cases so please refer to the corresponding Rate.cancellation_policies field for that rate for money refunding policy at the time of cancellation.
Rate.boardType string no Board type code of the rate. Possible value are
  • RO: Room Only
  • BB: Bed And Breakfast
  • HB: Half Board
  • FB: Full Board
  • AI: All Inclusive
Rate.boardName string no Board type name of the rate. See Rate.boardType field for possible values.
Rate.rate decimal no Total amount of the rate at given currency specified in Rate.currency field.
Rate.currency string no Three letter currency code (ISO-4217) of the total amount for the rate specified in Rate.rate field
Rate.rooms list[Room] no List of Room objects.
Room.numberOfAdults integer no Maximum number of adults can fit into this room
Room.childrenAges list[integer] no Children with specified ages can be accepted for this room.
Room.roomDescription string no Any arbitrary description for this room which the hotelier specified.
Room.sequence integer no Room sequence identifier which is useful at the time of booking in order to specify which occupant set will be matched with which room.
Rate.cancellationPolicies list[CancellationPolicy] yes List of CancellationPolicy objects.

Cancellation policies indicates the amount of penalty charged and deducted from the total refund amount of the booking at the time of cancellation performed after the specified date and time.

Please note that, the value can be null since not all the suppliers provide this data on Check Hotels step. In these cases, you should use Check Rate end point accordingly to able to retrieve cancellation policies.
CancellationPolicy.amount decimal no Penalty amount in rate's currency specified in Rate.currency field
CancellationPolicy.fromDate string no Offset date time string in YYYY-MM-DDThh:mmTZD (ISO 8601) format indicating from when the polciy applied.
Rate.remarks string yes Any comments, warnings or policies applied by the hotel displayed here if available.
Rate.commission decimal yes Amount of comission specified for commissionable rates.
Rate.hotelRate decimal yes Total amount of rate in hotelier's currency specified in hotelCurrency field which will be payed to the hotelier by the occupants at the time of arrival. This field should not be null when the Rate.rateType is DIRECT
Rate.hotelCurrency string yes Three letter currency code (ISO-4217) of the total amount for the hotel rate specified in Rate.hotelRate field

Example Result Object

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
{
  "hotels": [
    {
      "hotelCode": "69af45",
      "hotelName": "The Marmara Pera",
      "destinationCode": "c36ca9",
      "destinationName": "istanbul",
      "countryCode": "TR",
      "rates": [
        {
          "rateType": "NET",
          "rateKey": "[Q9k|3|USD|US|[[2|[]]]]_[APS74Q|aa9F|NET|0|NWv9zw|[BugWBw|2|0]]",
          "nonrefundable": true,
          "boardType": "RO",
          "boardName": "Room Only",
          "rate": 165.83,
          "currency": "USD",
          "rooms": [
            {
              "numberOfAdults": 2,
              "childrenAges": [],
              "roomDescription": "Superior",
              "sequence": 1
            }
          ],
          "cancellationPolicies": [],
          "remarks": null,
          "commission": null,
          "hotelCurrency": null,
          "hotelRate": null
        },
        {
          "rateType": "NET",
          "rateKey": "[Q9k|3|USD|US|[[2|[]]]]_[APS74Q|aa9F|NET|0|NWv9zw|[F108yA|2|0]]",
          "nonrefundable": false,
          "boardType": "BB",
          "boardName": "Bed And Breakfast",
          "rate": 189.52,
          "currency": "USD",
          "rooms": [
            {
              "numberOfAdults": 2,
              "childrenAges": [],
              "roomDescription": "Leisure Superior",
              "sequence": 1
            }
          ],
          "cancellationPolicies": [],
          "remarks": null,
          "commission": null,
          "hotelCurrency": null,
          "hotelRate": null
        }
      ]
    },
    {
      "hotelCode": "d31d12",
      "hotelName": "The Marmara Taksim",
      "destinationCode": "c36ca9",
      "destinationName": "istanbul",
      "countryCode": "TR",
      "rates": [
        {
          "rateType": "NET",
          "rateKey": "[Q9k|3|USD|US|[[2|[]]]]_[AJ62Fw|ANMdEg|NET|0|5pyO3Q|[jVOYrg|2|0]]",
          "nonrefundable": false,
          "boardType": "BB",
          "boardName": "Bed And Breakfast",
          "rate": 689.24,
          "currency": "EUR",
          "rooms": [
            {
              "numberOfAdults": 2,
              "childrenAges": [],
              "roomDescription": "DOUBLE DELUXE CITY VIEW",
              "sequence": 1
            }
          ],
          "cancellationPolicies": [
            {
              "amount": 205.13,
              "fromDate": "2017-07-19T23:59:00+03:00"
            }
          ],
          "remarks": null,
          "commission": null,
          "hotelCurrency": null,
          "hotelRate": null
        },
        {
          "rateType": "NET",
          "rateKey": "[Q9k|3|USD|US|[[2|[]]]]_[AJ62Fw|ANMdEg|NET|0|Prabrg|[Jn1lQw|2|0]]",
          "nonrefundable": false,
          "boardType": "HB",
          "boardName": "Half Board",
          "rate": 676.97,
          "currency": "EUR",
          "rooms": [
            {
              "numberOfAdults": 2,
              "childrenAges": [],
              "roomDescription": "DOUBLE DELUXE SEA VIEW",
              "sequence": 1
            }
          ],
          "cancellationPolicies": [
            {
              "amount": 201.48,
              "fromDate": "2017-07-19T23:59:00+03:00"
            }
          ],
          "remarks": null,
          "commission": null,
          "hotelCurrency": null,
          "hotelRate": null
        }
      ]
    }
  ]
}