@findhotel/sapi 1.4.8 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +267 -28
  2. package/dist/index.js +1 -1
  3. package/dist/types/packages/core/src/app-config.d.ts +1 -0
  4. package/dist/types/packages/core/src/hotel-availability.d.ts +45 -0
  5. package/dist/types/packages/core/src/hotel-availability.test.d.ts +1 -0
  6. package/dist/types/packages/core/src/offers-client.d.ts +3 -47
  7. package/dist/types/packages/core/src/sapi.d.ts +2 -0
  8. package/dist/types/packages/core/src/types/availability.d.ts +31 -0
  9. package/dist/types/packages/core/src/types/index.d.ts +1 -0
  10. package/dist/types/packages/core/src/types/offers.d.ts +73 -2
  11. package/dist/types/packages/core/src/types/types.d.ts +1 -0
  12. package/package.json +1 -1
package/README.md CHANGED
@@ -20,6 +20,7 @@ hotels, hotels\' offers and rooms.
20
20
  - [Get hotel](#get-hotel)
21
21
  - [Get hotels](#get-hotels)
22
22
  - [Get hotel offers](#get-hotel-offers)
23
+ - [Get hotel(s) availability (aka price calendar)](#get-hotels-availability-aka-price-calendar)
23
24
  - [API Reference](#api-reference)
24
25
  - [SAPI client](#sapi-client)
25
26
  - [Supported options](#supported-options)
@@ -27,6 +28,7 @@ hotels, hotels\' offers and rooms.
27
28
  - [Response](#response)
28
29
  - [`search()` method](#search-method)
29
30
  - [Search parameters](#search-parameters)
31
+ - [Split Booking Configuration](#split-booking-configuration)
30
32
  - [Filters](#filters)
31
33
  - [Facilities](#facilities)
32
34
  - [Property types](#property-types)
@@ -48,6 +50,10 @@ hotels, hotels\' offers and rooms.
48
50
  - [`offers()` method](#offers-method)
49
51
  - [Offers parameters](#offers-parameters)
50
52
  - [Response](#response-6)
53
+ - [`hotelAvailability()` method](#hotelavailability-method)
54
+ - [Hotel(s) availability search parameters](#hotels-availability-search-parameters)
55
+ - [Callbacks](#callbacks-1)
56
+ - [Response](#response-7)
51
57
  - [Rooms configuration](#rooms-configuration)
52
58
  - [Examples](#examples)
53
59
  - [How to generate `searchId`?](#how-to-generate-searchid)
@@ -244,7 +250,6 @@ const hotel = await sapiClient.hotel('1196472')
244
250
  For full documentation, check [hotel method api](#hotel-method).
245
251
 
246
252
  ### Get hotels
247
- <a id="tutorial-get-hotels"></a>
248
253
 
249
254
  Get hotels by ids:
250
255
 
@@ -255,7 +260,6 @@ const hotels = await sapiClient.hotels(['1714808','1380416','1710829'])
255
260
  For full documentation, check [hotels method api](#hotels-method).
256
261
 
257
262
  ### Get hotel offers
258
- <a id="tutorial-get-offers"></a>
259
263
 
260
264
  Get offers for a single hotel:
261
265
 
@@ -281,6 +285,36 @@ const offers = await sapiClient.offers(parameters, callbacks)
281
285
 
282
286
  For full documentation, check [offers method api](#offers-method).
283
287
 
288
+ ### Get hotel(s) availability (aka price calendar)
289
+
290
+ Get hotel(s) availability:
291
+
292
+ ```js
293
+ const parameters = {
294
+ hotelIds: ['1380416','1359951'],
295
+ startDate: '2023-08-05',
296
+ endDate: '2023-08-12',
297
+ nights: 2,
298
+ rooms: '2',
299
+ }
300
+
301
+ const callbacks = {
302
+ onStart: (response) => {
303
+ log('Availability request started', response)
304
+ },
305
+ onAvailabilityReceived: (response) => {
306
+ log('Availability received', response)
307
+ },
308
+ onComplete: (response) => {
309
+ log('Availability completed', response)
310
+ }
311
+ }
312
+
313
+ const response = await sapiClient.hotelAvailability(parameters, callbacks)
314
+ ```
315
+
316
+ For full documentation, check [availability method api](#hotel-availability-method).
317
+
284
318
  # API Reference
285
319
 
286
320
  ## SAPI client
@@ -391,31 +425,58 @@ const search = await sapiClient.search(searchParameters, callbacks)
391
425
 
392
426
  All parameters are optional.
393
427
 
394
- | name | type | description | example |
395
- | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
396
- | `hotelId` | `string` | Hotel Id for hotel search | `1371626` |
397
- | `placeId` | `string` | Place Id for place search | `47319` |
398
- | `geolocation` | `{lat: number, lon: number, precision: string}` | Geolocation query | `{lat: 36.114303, lon: -115.178312}` |
399
- | `address` | `string` | Address search string | `Nieuwe Looiersdwarsstraat 17,` |
400
- | `boundingBox` | `[p1Lat, p1Lng, p2Lat, p2Lng]` | `topLeft` and `bottomRight` coordinates of bounding box to perform search inside it | `[46.650828100116044, 7.123046875, 45.17210966999772, 1.009765625]` |
401
- | `checkIn` | `string` | Check in date (`YYYY-MM-DD`) | `2021-10-10` |
402
- | `checkOut` | `string` | Check out date (`YYYY-MM-DD`) | `2021-10-11` |
403
- | `rooms` | `string` | [Rooms configuration](#rooms-configuration) | `2` |
404
- | `dayDistance` | `number` | Amount of full days from now to desired check in date (works in combination with `nights` parameter) | `15` |
405
- | `nights` | `number` | Number of nights of stay | `3` |
406
- | `sortField` | `string` | Defines the sort by criteria | `popularity, price` |
407
- | `sortOrder` | `string` | Defines the sort order | `ascending, descending` |
408
- | `filters` | `Object` | Object with [filters](#search-filters) | `{starRatings: 5}` |
409
- | `cugDeals` | `string[]` | Codes of closed user group deals to retrieve offers | `['signed_in', 'offline']` |
410
- | `tier` | `string` | User tier | `member` |
411
- | `originId` | `string` | Identifier of origin where the request was originated | `c3po6twr70` |
412
- | `preferredRate` | `number` | Offer\'s price user saw on a CA (meta) platform | `196` |
413
- | `label` | `string` | Opaque value that will be passed to tracking systems | `gha-vr` |
414
- | `userId` | `string` | An authenticated user ID, e.g. the Google ID of a user. Used by ACL | `c34b0018-d434-4fad-8de6-9d8e8e18cb35` |
415
- | `emailDomain` | `string` | Email domain for authenticated user, Used by ACL | `@manatuscostarica.com` |
416
- | `screenshots` | `number` | Number of of screenshot taken by the user and detected by website, Used by ACL | `2` |
417
- | `metadata` | `Record<string, string>` | Additional metadata to be passed to the search | `{esd: 'abcds', epv: 'qwert'}` |
418
- | `offerSort` | `string` | If present, sorts offers by price (see [explanation](#sort-offers)) | |
428
+ | name | type | description | example |
429
+ | --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
430
+ | `hotelId` | `string` | Hotel Id for hotel search | `1371626` |
431
+ | `placeId` | `string` | Place Id for place search | `47319` |
432
+ | `geolocation` | `{lat: number, lon: number, precision: string}` | Geolocation query | `{lat: 36.114303, lon: -115.178312}` |
433
+ | `address` | `string` | Address search string | `Nieuwe Looiersdwarsstraat 17,` |
434
+ | `boundingBox` | `[p1Lat, p1Lng, p2Lat, p2Lng]` | `topLeft` and `bottomRight` coordinates of bounding box to perform search inside it | `[46.650828100116044, 7.123046875, 45.17210966999772, 1.009765625]` |
435
+ | `checkIn` | `string` | Check in date (`YYYY-MM-DD`) | `2021-10-10` |
436
+ | `checkOut` | `string` | Check out date (`YYYY-MM-DD`) | `2021-10-11` |
437
+ | `rooms` | `string` | [Rooms configuration](#rooms-configuration) | `2` |
438
+ | `dayDistance` | `number` | Amount of full days from now to desired check in date (works in combination with `nights` parameter) | `15` |
439
+ | `nights` | `number` | Number of nights of stay | `3` |
440
+ | `sortField` | `string` | Defines the sort by criteria | `popularity, price` |
441
+ | `sortOrder` | `string` | Defines the sort order | `ascending, descending` |
442
+ | `filters` | `Object` | Object with [filters](#search-filters) | `{starRatings: 5}` |
443
+ | `cugDeals` | `string[]` | Codes of closed user group deals to retrieve offers | `['signed_in', 'offline']` |
444
+ | `tier` | `string` | User tier | `member` |
445
+ | `originId` | `string` | Identifier of origin where the request was originated | `c3po6twr70` |
446
+ | `preferredRate` | `number` | Offer\'s price user saw on a CA (meta) platform | `196` |
447
+ | `label` | `string` | Opaque value that will be passed to tracking systems | `gha-vr` |
448
+ | `userId` | `string` | An authenticated user ID, e.g. the Google ID of a user. Used by ACL | `c34b0018-d434-4fad-8de6-9d8e8e18cb35` |
449
+ | `emailDomain` | `string` | Email domain for authenticated user, Used by ACL | `@manatuscostarica.com` |
450
+ | `screenshots` | `number` | Number of of screenshot taken by the user and detected by website, Used by ACL | `2` |
451
+ | `metadata` | `Record<string, string>` | Additional metadata to be passed to the search | `{esd: 'abcds', epv: 'qwert'}` |
452
+ | `offerSort` | `string` | If present, sorts offers by price (see [explanation](#sort-offers)) | |
453
+ | `sbc` | `string` | [Split Booking Configuration](#splitbookingconfiguration). If present, searches for split booking offers | `sbc: '2~3'` |
454
+
455
+ #### Split Booking Configuration
456
+ <a id="splitbookingconfiguration"></a>
457
+ The format for the split booking configuration is as follows:
458
+
459
+ `LOS1~LOS2`
460
+
461
+ where:
462
+ `LOS1` and `LOS2` are integers representing the length of stay for the first and second part of the split booking respectively.
463
+
464
+ for example if we have these parameters:
465
+
466
+ `checkIn:'2023-08-10'`
467
+
468
+ `checkOut:'2023-08-15'`
469
+
470
+ `sbc:2~3`
471
+
472
+ The first part of the split booking will be 2 nights and the second part will be 3 nights.
473
+ So, SAPI searches for two stays:
474
+
475
+ split1: `checkIn: '2023-08-10'` `checkOut: '2023-08-12'`
476
+
477
+ split2: `checkIn: '2023-08-12'` `checkOut: '2023-08-15'`
478
+
479
+
419
480
 
420
481
  #### Filters
421
482
  <a id="search-filters"></a>
@@ -1071,7 +1132,7 @@ const offers = await sapiClient.offers(parameters, callbacks)
1071
1132
  ```
1072
1133
 
1073
1134
  ### Offers parameters
1074
- <a id="hotel-parameters"></a>
1135
+ <a id="offers-parameters"></a>
1075
1136
 
1076
1137
  | name | type | description | required | example |
1077
1138
  | ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
@@ -1092,6 +1153,7 @@ const offers = await sapiClient.offers(parameters, callbacks)
1092
1153
  | `offersSort` | `string` | If present, sorts offers by price (see [explanation](#sort-offers)) | no | |
1093
1154
  | `getAllOffers` | `boolean` | If `true` SAPI returns all (up to 23) offers for the hotel (by default or if it's `false` SAPI returns only up to 3 top offers) | no | |
1094
1155
  | `optimizeRooms` | `boolean` | If `true` then rooms optimization logic is enabled. Rooms optimization tries to find best offer across possible rooms configurations for a given occupancy | no | |
1156
+ | `sbc` | `string` | [Split Booking Configuration](#splitbookingconfiguration). If present, searches for split booking offers | no | `sbc: '2~3'` |
1095
1157
 
1096
1158
  <a id="sort-offers"></a>
1097
1159
  Offer sorting by one parameter for now. It is `price`, but there are different variants of sorting by price.:
@@ -1150,6 +1212,183 @@ const parameters = {
1150
1212
 
1151
1213
  The response with the detailed description can be found in the [Offers Response](./docs/offers.md)
1152
1214
 
1215
+
1216
+ ## `hotelAvailability()` method
1217
+ <a id="hotel-availability-method"></a>
1218
+
1219
+ Returns availability of the provided hotels for different dates (aka price calendar)
1220
+
1221
+ ```js
1222
+ const parameters = {
1223
+ hotelIds: ['1380416','1359951'],
1224
+ startDate: '2023-08-05',
1225
+ endDate: '2023-08-12',
1226
+ nights: 2,
1227
+ rooms: '2',
1228
+ }
1229
+
1230
+ const callbacks = {
1231
+ onStart: (response) => {
1232
+ log('Availability request started', response)
1233
+ },
1234
+ onAvailabilityReceived: (response) => {
1235
+ log('Availability received', response)
1236
+ },
1237
+ onComplete: (response) => {
1238
+ log('Availability completed', response)
1239
+ }
1240
+ }
1241
+
1242
+ const response = await sapiClient.hotelAvailability(parameters, callbacks)
1243
+ ```
1244
+
1245
+ ### Hotel(s) availability search parameters
1246
+ <a id="availability-search-parameters"></a>
1247
+
1248
+ | name | type | description | required | example |
1249
+ | ----------- | ------------------ | -------------------------------------------------------------------------------------------- | -------- | -------------------------- |
1250
+ | `hotelIds` | `string, string[]` | Hotel id(s) to retrieve offers for | yes | `['1380416','1359951']` |
1251
+ | `startDate` | `string` | Date of first check in (YYYY-MM-DD) | yes | `'2023-10-10'` |
1252
+ | `endDate` | `string` | Date of last check in (including). Can't be further than 61 days from StartDate (YYYY-MM-DD) | yes | `'2023-10-11'` |
1253
+ | `nights` | `number` | Nights is length of stay | yes | `3` |
1254
+ | `rooms` | `string` | [Rooms configuration](#rooms-configuration) | yes | `'2'` |
1255
+ | `cugDeals` | `string[]` | Codes of closed user group deals to retrieve offers | no | `['signed_in', 'offline']` |
1256
+ | `tier` | `string` | User tier | no | `'member'` |
1257
+ | `originId` | `string` | Identifier of origin where the request was originated | no | `'c3po6twr70'` |
1258
+
1259
+ ### Callbacks
1260
+ <a id="availability-callbacks"></a>
1261
+
1262
+ Object with callbacks:
1263
+
1264
+ ```js
1265
+ const callbacks = {
1266
+ onStart: (response) => {
1267
+ log('Availability request started', response)
1268
+ },
1269
+ onAvailabilityReceived: (response) => {
1270
+ log('Availability received', response)
1271
+ },
1272
+ onComplete: (response) => {
1273
+ log('Availability completed', response)
1274
+ }
1275
+ }
1276
+ ```
1277
+
1278
+ 1. ### onStart()
1279
+
1280
+ Runs at the beginning of each new availability request.\
1281
+ Returns adjusted and validated availability search parameters.
1282
+
1283
+ 2. ### onAvailabilityReceived()
1284
+
1285
+ Runs on every received batch of availability.\
1286
+ Returns availability with offers (incomplete response).
1287
+
1288
+ 3. ### onComplete()
1289
+
1290
+ Runs after availability request is completed.\
1291
+ Returns availability with offers (complete response).
1292
+
1293
+ ### Response
1294
+ <a id="availability-response"></a>
1295
+
1296
+ An example of the response:
1297
+
1298
+ ```json
1299
+ {
1300
+ "1380416": {
1301
+ "2023-08-05": {
1302
+ "hotelID": "1380416",
1303
+ "cheapestRate": {
1304
+ "base": 531.9901869159,
1305
+ "taxes": 34.7298130841,
1306
+ "hotelFees": 0
1307
+ },
1308
+ "offers": [
1309
+ {
1310
+ "id": "oEfGbUTje2BE",
1311
+ "currency": "EUR",
1312
+ "availableRooms": null,
1313
+ "url": "https://r.vio.com?lbl=providerRateType%3Dmember&ofd=...",
1314
+ "rate": {
1315
+ "base": 531.9901869159,
1316
+ "taxes": 34.7298130841,
1317
+ "hotelFees": 0
1318
+ },
1319
+ "accessTier": "sensitive",
1320
+ "providerCode": "WTM",
1321
+ "intermediaryProvider": "FHT",
1322
+ "package": {
1323
+ "amenities": [
1324
+ "breakfast"
1325
+ ],
1326
+ "canPayLater": false
1327
+ },
1328
+ "cancellationPenalties": [
1329
+ {
1330
+ "start": "2023-07-30T10:00:00Z",
1331
+ "end": "2023-08-02T09:59:00Z",
1332
+ "amount": 0,
1333
+ "currency": "EUR"
1334
+ }
1335
+ ],
1336
+ "tags": [
1337
+ "top_offer",
1338
+ "exclusive_cheapest_offer"
1339
+ ],
1340
+ "metadata": {
1341
+ "providerRateType": "member",
1342
+ "feedID": ""
1343
+ },
1344
+ "roomName": "STANDARD DOUBLE/TWIN"
1345
+ },
1346
+ ]
1347
+ },
1348
+ "2023-08-06": {
1349
+ "hotelID": "1380416",
1350
+ "cheapestRate": {
1351
+ "base": 493.9438317757,
1352
+ "taxes": 32.2961682243,
1353
+ "hotelFees": 0
1354
+ },
1355
+ "offers": [
1356
+ {
1357
+ "id": "omVVqhCXEbIw",
1358
+ "currency": "EUR",
1359
+ "availableRooms": null,
1360
+ "url": "https://r.vio.com?lbl=providerRateType%3Dmember&ofd=book_uri...",
1361
+ "rate": {
1362
+ "base": 493.9438317757,
1363
+ "taxes": 32.2961682243,
1364
+ "hotelFees": 0
1365
+ },
1366
+ "accessTier": "sensitive",
1367
+ "providerCode": "WTM",
1368
+ "intermediaryProvider": "FHT",
1369
+ "package": {
1370
+ "amenities": [
1371
+ "breakfast"
1372
+ ],
1373
+ "canPayLater": false
1374
+ },
1375
+ "cancellationPenalties": [],
1376
+ "tags": [
1377
+ "top_offer",
1378
+ "exclusive_cheapest_offer"
1379
+ ],
1380
+ "metadata": {
1381
+ "providerRateType": "member",
1382
+ "feedID": ""
1383
+ },
1384
+ "roomName": "STANDARD DOUBLE/TWIN"
1385
+ }
1386
+ ]
1387
+ }
1388
+ }
1389
+ }
1390
+ ```
1391
+
1153
1392
  ## Rooms configuration
1154
1393
  <a id="rooms-configuration"></a>
1155
1394
  `rooms` is a string that encodes the configuration of rooms requested by the user and follows the next rules: