SDK provides a high level TypeScript/JavaScript API for searching hotels, hotels' offers and rooms.
- SAPI SDK
- Table of contents
- Release process
- Tutorials
- API Reference
There is no continuous integration/delivery in SAP SDK. Merging a PR into main branch doesn't automatically trigger the release process. For releases SAPI SDK uses Ship.js tool. It gives more control over the process. Ship.js automatically creates a PR before publishing every release, so this allows:
- Confirm the next version is correct.
- Confirm which commits are going to be released and discuss them with colleagues.
- Edit the automatically generated changelog for clarity & readability.
NPM account is required for pre-release (beta) process:
- Go to NPM sign up
- Create an account and ask SAPI to give you access to organization
- Activate your Two Factor Authentication using Authenticator/1Password
GitHub token is required for the release process:
- Go to your GitHub account
- Check "repo(Full control of private repositories)"
- Generate/copy the token
- Add it in your command line like:
GITHUB_TOKEN=xxx
To create and deploy a new release of SAPI SDK please follow the next steps:
- Merge your changes. There can be multiple changes in one release
- Checkout the latest version of the
main
branch - In the root directory run
make release
command - this will start the release process - Review and confirm (or change) the new release version number
- After installing dependencies and running deployment scripts a new pull request will be automatically created
- Review/update
CHANGELOG.md
in the root directory. Write down changes with descriptions using keep a changelog guiding principles and commit your changes to the newly created release PR - Review the PR/ask SAPI engineer(s) for approval
-
Squash and merge
the PR. This will trigger automated release process using GitHub actions and after some time the new release will be published to NMP - Check if the new version has been published to NPM
Sometimes You might want to test your changes on the website for example on the local or custom/test environment before merging your branch to main and before making a new SAPI SDK release. To do so You can create and publish a pre-release.
Pre-release publishes a new version to NPM with a tag other than latest
(the default tag).
To publish a pre-release please follow the next steps:
-
build SAPI SDK from the root of the project:
make core-build
-
create a new version
npm version prepatch (preminor, premajor) --preid=beta (alpha, beta, etc...)
:npm version prepatch --preid=beta
this would result in something like this
1.4.1-beta.0
-
If you’ve already released a pre-release and want to increment the pre-release part of the version only, run:
npm version prerelease
this would result in something like this
1.4.1-beta.1
-
-
publish your changes with a tag other than
latest
:npm publish --tag=next
During the publish you'll asked to login/enter your OTP (Two Factor Auth Code) which you can access it using Authenticator/1Password app (for more information read here)
-
after the new version is published to npm, install it to your local environment specifying the new version:
npm install @findhotel/sapi@1.4.1-beta.0
First, install SAPI SDK via the npm package manager:
npm install @findhotel/sapi
Then, import SAPI into your project:
import sapi from "@findhotel/sapi";
Create SAPI client:
const profileKey = "profile-key";
const sapiClient = await sapi(profileKey, {
anonymousId: "fd9dbb5f-b337-4dd7-b640-1f177d1d3caa",
language: "en",
currency: "USD",
countryCode: "US",
});
Now SAPI client is ready to be used in your application.
For full documentation and supported options check client api.
Sapi SDK uses uuid
for generation of random strings.
uuid
uses a global crypto
object which is not
available in React Native environment.
To add support, crypto
polyfill should be installed on the
consumer side. We recommend installing just
crypto.getRandomValues
polyfill if you don't use other
crypto
methods. More information about polyfill can be
found here
Playground is a local environment for checking your changes and test if the implementations were correct you can access this environment locally (http://localhost:3000) by opening two terminals and running these commands in order
# watch your changes to core and create a new bundle
make core-dev
# runs the playground on http://localhost:3000
make playground-run
Search for the hotels and hotels' offers:
const searchParameters = {
placeId: "47319",
checkIn: "2021-10-10",
checkOut: "2021-10-11",
rooms: "2",
};
const callbacks = {
onStart: (response) => {
log("Search started", response);
},
onAnchorReceived: (response) => {
log("Anchor received", response);
},
onHotelsReceived: (response) => {
log("Hotels received", response);
},
onOffersReceived: (response) => {
log("Offers received", response);
},
onComplete: (response) => {
log("Search completed", response);
},
};
const search = await sapiClient.search(searchParameters, callbacks);
For full documentation, check search method api.
Get rooms data and rooms' offers:
const rooms = await sapiClient.rooms({
hotelId: "47319",
checkIn: "2021-10-10",
checkOut: "2021-10-11",
rooms: "2",
});
For full documentation, check rooms method api.
Get hotel by id:
const hotel = await sapiClient.hotel("1196472");
For full documentation, check hotel method api.
Get hotels by ids:
const hotels = await sapiClient.hotels(["1714808", "1380416", "1710829"]);
For full documentation, check hotels method api.
Get offers for a single hotel:
const parameters = {
hotelId: "1196472",
};
const callbacks = {
onStart: (response) => {
log("Offers started", response);
},
onOffersReceived: (response) => {
log("Offers received", response);
},
onComplete: (response) => {
log("Offers completed", response);
},
};
const offers = await sapiClient.offers(parameters, callbacks);
For full documentation, check offers method api.
Get hotel(s) availability:
const parameters = {
hotelIds: ["1380416", "1359951"],
startDate: "2023-08-05",
endDate: "2023-08-12",
nights: 2,
rooms: "2",
};
const callbacks = {
onStart: (response) => {
log("Availability request started", response);
},
onAvailabilityReceived: (response) => {
log("Availability received", response);
},
onComplete: (response) => {
log("Availability completed", response);
},
};
const response = await sapiClient.hotelAvailability(parameters, callbacks);
For full documentation, check availability method api.
Create SAPI client:
const profileKey = "profile-key";
const sapiClient = await sapi(profileKey, {
anonymousId: "fd9dbb5f-b337-4dd7-b640-1f177d1d3caa",
language: "en",
currency: "USD",
countryCode: "US",
deviceType: "mobile",
pageSize: 20,
initWithAppConfig: {},
algoliaClientOptions: {
timeouts: {
connect: 1, // Connection timeout in seconds
read: 2, // Read timeout in seconds
write: 30, // Write timeout in seconds
},
},
callbacks: {
onConfigReceived: (config) => {
log("Config received", config);
},
},
getTotalRate: (rate) => {
let totalRate = rate.base;
if (includeTaxes) totalRate += rate.taxes;
if (includeHotelFees) totalRate += rate.hotelFees;
return totalRate;
},
});
name | required | type | default | description | example |
---|---|---|---|---|---|
anonymousId |
yes | string |
Unique ID identifying users | 2d360284-577b-4a53-8b91-68f72b9227fa |
|
language |
no | string |
en |
2-char language code | en |
currency |
no | string |
USD |
3-char uppercased ISO currency code | USD |
countryCode |
no | string |
US |
2-char uppercased ISO country code | US |
deviceType |
yes | string |
desktop , mobile , tablet
|
desktop |
|
pageSize |
no | number |
20 |
Displayed page size | 20 |
initWithAppConfig |
no | AppConfig |
External app config to override internal one | ||
algoliaClientOptions |
no | AlgoliaSearchOptions |
Algolia client options used for debugging and setting additional options like timeouts etc. | ||
variations |
no | Record<string, string> |
A/B test variations | {'pp000004-tags2': 'b', 'pp000004-tags3': '1'} |
|
callbacks |
no | Record<string, fnc> |
Client callbacks | ||
getTotalRate |
no | function |
Total rate including taxes and fees | Function to calculate total display rate based on tax display logic. Used for price filter and sort by price functionalities. |
-
onConfigReceived(configs)
Returns configuration settings that are used by sapiClient.
{
"exchangeRates": {
"EUR": 0.982994
},
"lov": [
{
"id": 9,
"categoryID": 19,
"objectID": "Facility:9",
"value": {
"en": "Airport shuttle"
}
},
{
"categoryID": 2,
"id": 7,
"objectID": "Facility:7",
"value": {
"en": "Swimming pool"
}
}
]
}
Search is a method of sapiClient for searching hotels and offers for
provided searchParameters
:
const search = await sapiClient.search(searchParameters, callbacks);
All parameters are optional.
name | type | description | example |
---|---|---|---|
hotelId |
string |
Hotel Id for hotel search | 1371626 |
placeId |
string |
Place Id for place search | 47319 |
geolocation |
{lat: number, lon: number, precision: string} |
Geolocation query | {lat: 36.114303, lon: -115.178312} |
address |
string |
Address search string | Nieuwe Looiersdwarsstraat 17, |
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] |
checkIn |
string |
Check in date (YYYY-MM-DD ) |
2021-10-10 |
checkOut |
string |
Check out date (YYYY-MM-DD ) |
2021-10-11 |
rooms |
string |
Rooms configuration | 2 |
dayDistance |
number |
Amount of full days from now to desired check in date (works in combination with nights parameter) |
15 |
nights |
number |
Number of nights of stay | 3 |
sortField |
string |
Defines the sort by criteria | popularity, price |
sortOrder |
string |
Defines the sort order | ascending, descending |
filters |
Object |
Object with filters | {starRatings: 5} |
cugDeals |
string[] |
Codes of closed user group deals to retrieve offers | ['signed_in', 'offline'] |
tier |
string |
User tier | member |
originId |
string |
Identifier of origin where the request was originated | c3po6twr70 |
preferredRate |
number |
Offer's price user saw on a CA (meta) platform | 196 |
label |
string |
Opaque value that will be passed to tracking systems | gha-vr |
userId |
string |
An authenticated user ID, e.g. the Google ID of a user. Used by ACL | c34b0018-d434-4fad-8de6-9d8e8e18cb35 |
emailDomain |
string |
Email domain for authenticated user, Used by ACL | @manatuscostarica.com |
deviceId |
string |
Device ID, Used by ACL (the IDFV of an iOS device or the GAID of an Android device) | |
screenshots |
number |
Number of of screenshot taken by the user and detected by website, Used by ACL | 2 |
metadata |
Record<string, string> |
Additional metadata to be passed to the search | {esd: 'abcds', epv: 'qwert'} |
offerSort |
string |
If present, sorts offers by price (see explanation) | |
optimizeRooms |
boolean |
If true then rooms optimization logic is enabled for non anchor hotels. Rooms optimization tries to find best offer across possible rooms configurations for a given occupancy |
true |
optimizeAnchorRooms |
boolean |
If true then rooms optimization logic is enabled for an anchor hotel. Rooms optimization tries to find best offer across possible rooms configurations for a given occupancy |
false |
sbc |
string |
Split Booking Configuration. If present, searches for split booking offers | sbc: '2~3' |
skipOffers |
boolean |
Skip offers search and return only static results | true |
searchId |
string |
ID of search session, should only be specified when re-running the search to be tracked as the same session | true |
useLiveOfferDataHSO |
boolean |
Hints the back-end when to use or not live offer data for refined hotel sorting | true |
The format for the split booking configuration is as follows:
LOS1~LOS2
where:
LOS1
and LOS2
are integers representing the length of stay for the first and second part of the split booking respectively.
for example if we have these parameters:
checkIn:'2023-08-10'
checkOut:'2023-08-15'
sbc:2~3
The first part of the split booking will be 2 nights and the second part will be 3 nights. So, SAPI searches for two stays:
split1: checkIn: '2023-08-10'
checkOut: '2023-08-12'
split2: checkIn: '2023-08-12'
checkOut: '2023-08-15'
name | type | description | example | filter scope |
---|---|---|---|---|
themeIds |
number[] |
Facet filtering by theme ids | [1, 2, 3] |
Hotel |
chainIds |
number[] |
Hotels' chain ids | [4, 5] |
Hotel |
facilities |
string[] |
Facility ids used for facet filtering | [299,7,6,21] |
Hotel |
starRatings |
number[] |
Hotels' star rating | [3, 4] |
Hotel |
propertyTypeId |
number[] |
Property type id | [1, 0] |
Hotel |
guestRating |
number |
Minimum overall guest rating | 5 |
Hotel |
noHostels |
boolean |
If true, hostels will be excluded from results | true |
Hotel |
priceMin |
number |
Minimum price per night | 100 |
Hotel/Offer |
priceMax |
number |
Maximum price per night | 200 |
Hotel/Offer |
hotelName |
string |
Filters the result based on the Hotel name | Hilton Amsterdam |
Hotel |
freeCancellation |
boolean |
If true, only offers with free cancellation will be returned | true |
Offer |
payLater |
boolean |
If true, only offers with pay later option will be returned | true |
Offer |
mealIncluded |
boolean |
If true, only offers with meal included option will be returned | true |
Offer |
amenities |
string[] |
Meal types | ["breakfast","allInclusive"] |
|
isVr |
boolean |
If true, then only vacation rentals are returned. If false, then vacation rentals are filtered out | true |
Hotel |
Some of the favourite facilities used for filtering:
name | id |
---|---|
free_wifi |
299 |
swimming_pool |
7 |
restaurant |
5 |
parking |
6 |
pet_friendly |
8 |
kitchen |
50 |
hot_tub |
61 |
spa |
193 |
air_conditioned |
21 |
Some of the property types used for filtering:
name | id |
---|---|
hotel |
0 |
apartment |
9 |
hostel |
5 |
motel |
1 |
name | description |
---|---|
breakfast |
|
lunch |
|
dinner |
|
halfBoard |
"breakfast && dinner", or the hotel’s explicit use of the term "half-board" |
fullBoard |
"breakfast && lunch && dinner", or the hotel’s explicit use of the term "full-board" |
allInclusive |
"all meals && all drinks" or the hotel’s explicit use of the term "all-inclusive" |
Search method receives callbacks object as the second argument:
const callbacks = {
onStart: (response) => {
log("Search started", response);
},
onAnchorReceived: (response) => {
log("Anchor received", response);
},
onHotelsReceived: (response) => {
log("Hotels received", response);
},
onOffersReceived: (response) => {
log("Offers received", response);
},
onComplete: (response) => {
log("Search completed", response);
},
};
Each callback returns the full search state available inside SAPI at the time of callbacks executions. This means that each subsequent callback incrementally adds new properties and returns updated state. The data in the state can be repeated between different callbacks.
-
Runs at the beginning of each new search.
The callback is supplied with generated
searchId
and actual search parameters that are used for the search, like dates, currency, language used if invoker didn't provide those.Another purpose of this callback is that invoker can track that hotels search has started, in Search SPA the event is HotelsSearched.
-
Runs when SAPI receives anchor and(?) anchor hotel (in case of hotel search)
Returns static data about anchorresponse.anchor
and(?) anchor hotel insideresponse.hotelEntities
object (in case of hotel search). -
Runs when SAPI receives static search results
Returns static data about hotels insideresponse.hotelEntities
object as well as appropriate hotel sort order inresponse.hotelIds
array (sorted according to HSO). -
Runs when SAPI receives a bunch of offers
Returns hotel's offers (incomplete response) inresponse.hotelOfferEntities
object as well as updated hotel sort order inresponse.hotelIds
array (sorted according to HSO and taking into account the real offers data)
The offers response with the detailed description can be found in the Offers Response -
Runs when current search is complete and all offers are retrieved
Return complete SAPI search response.
The offers response with the detailed description can be found in the Offers Response
The complete SAPI search response is too big to be displayed on the page so there is a simplified example:
{
"anchor": {
"_geoloc": {
"lat": -6.28067,
"lon": 39.53601,
"precision": 5000,
"radius": 20000
},
"objectID": "hotel:9660485",
"objectType": "hotel",
"pageSize": 25,
"priceBucketWidth": 16,
"admDivisionLevel1": "Tanzania",
"navPath": [
"3429",
"300878",
"235186"
],
"navPathNames": {
"country": "Tanzania"
},
"navPathInfo": {
"adminDivision": {
"id": "12598",
"name": "Hokkaido Prefecture"
},
"city": {
"id": "43727",
"name": "Otaru"
},
"country": {
"id": "125948",
"name": "Japan"
}
},
"hotelName": "Zanzibar White Sand Luxury Villas & Spa - Relais & Chateaux",
"placeDisplayName": "Zanzibar"
},
"anchorType": "hotel",
"anchorHotelId": "9660485",
"hotelEntities": {
"9660485": {
"_geoloc": {
"lat": -6.28067,
"lon": 39.53601
},
"checkInTime": "14:00",
"checkOutTime": "11:00",
"country": "TZ",
"facilities": [
2, 5, 6, 7, 9, 11, 13, 20, 21, 22, 23, 28, 29, 31, 34, 35, 66, 84, 85, 86, 98, 99, 100, 103, 104, 122, 127, 189, 191, 193, 195, 202, 222, 235, 238, 243, 244, 253, 255, 266, 270, 292, 299
],
"guestRating": {
"cleanliness": 9.66,
"dining": 9.42,
"facilities": 9.9,
"location": 9.8,
"overall": 9.55,
"rooms": 9.72
},
"guestType": {
"business": 6,
"couples": 235,
"families": 110,
"groups": 68,
"solo": 13
},
"imageURIs": [
"https://img.fih.io/image/raw/regular/provider_partition=eps/3xWl0k2P0Ofb7vxD4dr1NhFjOtdQaHXLe2p1tYLaOmw=.webp"
],
"navPath": [
"3429",
"300878",
"235186"
],
"navPathInfo": {
"adminDivision": {
"id": "12598",
"name": "Hokkaido Prefecture"
},
"city": {
"id": "43727",
"name": "Otaru"
},
"country": {
"id": "125948",
"name": "Japan"
}
}
}
}
}
this structure holds all information about the hotel location(starting from country -> region -> city -> village)
"navPathInfo": {
"adminDivision": {
"id": "12598",
"name": "Hokkaido Prefecture"
},
"city": {
"id": "43727",
"name": "Otaru"
},
"country": {
"id": "125948",
"name": "Japan"
}
}
After the search is complete:
const search = await sapiClient.search(searchParameters, callbacks);
it resolves in the search
object which has 2 methods:
-
search.loadMore()
- SDK will return the next set of results ("next" page) for the given search. The same callbacks from original search will be used. -
search.loadOffers(hotelId, {filters, offersSort})
- will load all offers (up to 23) for the providedhotelId
. You can also override offers' scope filters and offers' sort order.
Suggest provides autosuggestions for a given query
const suggestions = await sapiClient.suggest("London", 6);
name | type | description | required | example |
---|---|---|---|---|
query |
string |
Query string | yes | London |
suggestsCount |
number |
Desired number of suggestions (default 6) | no | 10 |
const suggestions = await sapiClient.suggest("London", 2);
[
{
"highlightValue": "<em>London</em>",
"objectID": "158584",
"objectType": "place",
"placeDisplayName": "United Kingdom",
"placeTypeName": "city",
"value": "London"
},
{
"highlightValue": "<em>London</em> Heathrow Airport",
"objectID": "167733",
"objectType": "place",
"placeDisplayName": "London, United Kingdom",
"placeTypeName": "airport",
"value": "London Heathrow Airport"
}
]
const suggestions = await sapiClient.suggest("London hotel", 2);
[
{
"highlightValue": "Park Plaza Westminster Bridge <em>London</em>",
"objectID": "1546646",
"objectType": "hotel",
"placeDisplayName": "London, United Kingdom",
"placeTypeName": "property",
"value": "Park Plaza Westminster Bridge London"
},
{
"highlightValue": "Hampton by Hilton <em>London</em> Stansted Airport",
"objectID": "3333916",
"objectType": "hotel",
"placeDisplayName": "United Kingdom",
"placeTypeName": "property",
"value": "Hampton by Hilton London Stansted Airport"
}
]
FreeTextSuggest provides suggestions for a given free text query based on AI feature
const result = await sapiClient.freeTextSuggest(
"5 stars hotels in Amsterdam with pets allowed for tomorrow 2 nights"
);
name | type | description | required | example |
---|---|---|---|---|
query |
string |
Query string | yes | 5 stars hotels in Amsterdam with pets allowed for tomorrow 2 nights |
const result = await sapiClient.freeTextSuggest(
"5 stars hotels in Amsterdam with pets allowed for tomorrow 2 nights"
);
[
{
"filters": {
"starRating": 5,
"facilities": [
{
"id": 8,
"value": "Pet Friendly"
}
]
},
"checkIn": "2024-06-12",
"checkOut": "2024-06-14",
"highlightValue": "<em>Amsterdam</em>",
"objectID": "47319",
"objectType": "place",
"placeDisplayName": "The Netherlands",
"placeTypeName": "city",
"value": "Amsterdam"
},
{
"filters": {
"starRating": 5,
"facilities": [
{
"id": 8,
"value": "Pet Friendly"
}
]
},
"checkIn": "2024-06-12",
"checkOut": "2024-06-14",
"highlightValue": "InterContinental Amstel <em>Amsterdam</em>, an IHG Hotel",
"objectID": "1363313",
"objectType": "hotel",
"placeDisplayName": "Weesperbuurt en Plantage, Amsterdam, The Netherlands",
"placeTypeName": "property",
"value": "InterContinental Amstel Amsterdam, an IHG Hotel"
}
]
Rooms is a method of sapiClient for retrieving rooms information and offers for a particular itinerary:
const rooms = await sapiClient.rooms({
hotelId: "1714808",
checkIn: "2021-10-10",
checkOut: "2021-10-11",
rooms: "2",
});
name | type | description | required | example |
---|---|---|---|---|
hotelId |
string |
Hotel Id to retrieve rooms | yes | 1714808 |
checkIn |
string |
Check in date (YYYY-MM-DD ) |
yes | 2021-10-10 |
checkOut |
string |
Check out date (YYYY-MM-DD ) |
yes | 2021-10-11 |
rooms |
string |
Rooms configuration | yes | 2 |
providerCode |
string |
Provider code used for retrieving rooms offers | no | GAR |
cugDeals |
string |
Type of cug (closed user group) deals to retrieve | no | signed_in,offline |
tier |
string |
User tier | no | plus |
clickedOfferId |
string |
Offer id that user clicked on SRP | no | oXstvXafDb2o |
clickedOfferBaseRate |
number |
Base rate value of the offer which user clicked on SRP | no | 25 |
clickedOfferTaxes |
number |
Taxes value of the offer which user clicked on SRP | no | 10 |
clickedOfferHotelFees |
number |
Hotel fees value of the offer which the user clicked on SRP | no | 5 |
preHeat |
number |
Enables pre-heat mode | no | 1 |
label |
string |
Opaque value that will be passed to tracking systems | no | gha-vr |
userId |
string |
User ID is an authenticated user ID, e.g. the Google ID of a user. | no | 7ea95191-b929-469d-8b02-0397dafd53a1 |
emailDomain |
string |
User email domain is for authenticated user as a value, if email is available. | no | @findhotel.net |
deviceId |
string |
Device ID (the IDFV of an iOS device or the GAID of an Android device) | no | |
searchId |
string |
SearchId override (SDK generates a new one if no provided) | no | 08230dfcc5f0fb95caaa82ce559ea60c4a975d6f |
metadata |
Record<string, string> |
Additional data to be passed to API | no | {vclid: '21d2d152-de19-4f39-b40a-d4bc3002c6e8'} |
bundleId |
string |
Bundle Id clicked on SRP. Used to fetch bundle data from cache | no | 13b5d152-de19-4f39-b40a-d4bc3002c3u9 |
{
"anonymousId": "fd9dbb5f-b337-4dd7-b640-1f177d1d3caa",
"hotelId": "1714808",
"searchId": "08230dfcc5f0fb95caaa82ce559ea60c4a975d6f",
"rooms": [
{
"amenities": ["Non-Smoking Facility"],
"bedTypes": [],
"description": "20 sqm room Continental breakfast included Free WiFi LCD TV Spacious work desk Choice of pillows Coffee and tea facilities Large walk-in power shower",
"id": "K0LnAe-G9WI",
"images": [{ "url": "http://images.getaroom-cdn.com/image/...." }],
"masterId": "9643931",
"name": "1 Double Standard",
"offers": [
{
"availableRooms": 0,
"canPayLater": false,
"cancellationPenalties": [],
"cug": ["signed_in"],
"id": "o0KDe_mFPN4k",
"links": [
{
"href": "https://secure.findhotel.net/checkout/?hotelID=1714808...",
"method": "GET",
"type": "checkout"
}
],
"prices": [
{
"chargeable": { "base": "1352.77", "taxes": "59.94" },
"currencyCode": "EUR",
"hotelFees": { "breakdown": [], "total": "0" },
"type": "chargeable_currency"
}
],
"providerCode": "GAR",
"providerRateType": "public",
"services": ["breakfast"]
}
]
}
]
}
Hotel is a method of sapiClient for retrieving a single hotel by id
const hotel = await sapiClient.hotel("1196472");
name | type | description | required | example |
---|---|---|---|---|
hotelId |
string |
Hotel Id | yes | 1196472 |
An example of the response for request with hotelId
1196472
and "pt-BR" language
{
"objectID": "1196472",
"guestRating": {
"cleanliness": 8.82,
"dining": 8.73,
"facilities": 8.73,
"location": 8.8,
"overall": 8.54,
"pricing": 4.49,
"rooms": 8.82,
"service": 8.67
},
"isDeleted": false,
"starRating": 4,
"_geoloc": {
"lat": 52.377805,
"lon": 4.914172
},
"feesOpt": "<p>Os seguintes depósitos e taxas são cobrados pelo hotel no momento do serviço prestado, durante o check-in ou check-out. </p> <ul> <li>Taxa para café da manhã em estilo buffet: EUR 25.00 por pessoa (aproximadamente)</li> <li>Taxa para o acesso à internet com fio no quarto: EUR 15 por dia (as tarifas podem variar)</li> </ul> <p>A lista acima pode estar incompleta. As taxas e os depósitos podem não incluir impostos e estão sujeitos a mudanças. </p>",
"checkInSpInst": "O funcionário da recepção receberá os hóspedes na chegada. Para mais informações, entre em contato com o estabelecimento usando os dados que estão na confirmação da reserva. Os hóspedes que forem usar o traslado da Estação Central de Amsterdã devem entrar em contato com o estabelecimento com antecedência. Devido à COVID-19, as opções de comida e bebida deste estabelecimento podem estar limitadas de acordo com os regulamentos locais.",
"policies": "<ul> <li>Este estabelecimento oferece transporte da estação de trem. Os hóspedes devem entrar em contato com o estabelecimento antes da viagem com os detalhes da chegada usando as informações para contato presentes na confirmação da reserva. </li> <li>É necessário reservar os seguintes serviços: serviços de massagem. As reservas podem ser feitas contatando este hotel antes da viagem usando as informações para contato fornecidas na confirmação da reserva. </li> <li>Somente hóspedes registrados podem ter acesso aos quartos. </li></ul>",
"phone": "+31205191200",
"imageURIs": [
"https://i.travelapi.com/hotels/2000000/1460000/1452100/1452083/a39e2fc8_w.jpg",
"https://i.travelapi.com/hotels/2000000/1460000/1452100/1452083/3892e861_w.jpg",
"https://i.travelapi.com/hotels/2000000/1460000/1452100/1452083/aed25438_w.jpg"
],
"checkInTime": "15:00",
"checkInInst": "<ul> <li>Pessoas extras podem incorrer em taxas adicionais que variam dependendo da política do estabelecimento</li><li>Documento de identificação oficial com foto e cartão de crédito, cartão de débito ou depósito em dinheiro podem ser exigidos no momento do check-in para despesas extras.</li></ul>",
"reviewCount": 17538,
"chainID": "2101",
"checkInEnd": "01:00",
"lastBooked": 1608030831,
"checkOutTime": "12:00",
"feesMnd": "<p>Você deverá pagar os seguintes encargos no estabelecimento:</p> <ul><li>Depósito: EUR 50 por noite</li><li>A cidade cobra um imposto de EUR 3.00 por pessoa, por noite até 21 noites. Esse imposto não se aplica a crianças de até 16 anos. </li><li>Será cobrado um imposto municipal/local de 6.422 %</li></ul> <p>Incluímos todas as cobranças que o estabelecimento nos forneceu. No entanto, as cobranças podem variar com base, por exemplo, na duração da estadia ou no tipo de quarto reservado. </p>",
"deposit": {
"value": {
"currency": "USD",
"amount": 300.00
},
"description": "Deposit: USD 300.00 per accommodation<br>Breakage deposit: USD 230.00"
},
"reviewCountBkt": 9,
"hotelName": "Movenpick Hotel Amsterdam City Centre",
"sentiments": [
{
"value": "Gostou do bar",
"id": 46
},
{
"value": "Processo rápido de check-in/check-out",
"id": 180
}
],
"facilities": [
{
"categoryID": 4,
"importance": 2,
"value": "Centro de Negócios",
"id": 1
},
{
"categoryID": 17,
"importance": 2,
"value": "Serviço de quarto",
"id": 2
}
],
"placeID": "311007",
"guestType": {
"business": 1333,
"couples": 3125,
"families": 1484,
"groups": 1121,
"solo": 206
},
"themes": [
{
"value": "Cidade",
"id": 2
},
{
"value": "Empresarial",
"id": 12
}
],
"propertyType": {
"value": "Hotel",
"id": 0
},
"placeDisplayName": "Oostelijk Havengebied, Amsterdã",
"displayAddress": "Piet Heinkade 11, Oostelijk Havengebied, Amsterdã, Holanda"
}
Hotel is a method of sapiClient for retrieving multiple hotels by hotel ids
const hotels = await sapiClient.hotels(["1714808", "1380416", "1710829"]);
name | type | description | required | example |
---|---|---|---|---|
hotelIds |
string[] |
Hotel Ids | yes | ['1714808','1380416','1710829'] |
An example of the response for request with hotelId
1196472
and "pt-BR" language
{
"1196472": {
"objectID": "1196472",
"guestRating": {
"cleanliness": 8.82,
"dining": 8.73,
"facilities": 8.73,
"location": 8.8,
"overall": 8.54,
"pricing": 4.49,
"rooms": 8.82,
"service": 8.67
},
"isDeleted": false,
"starRating": 4,
"_geoloc": {
"lat": 52.377805,
"lon": 4.914172
},
"feesOpt": "<p>Os seguintes depósitos e taxas são cobrados pelo hotel no momento do serviço prestado, durante o check-in ou check-out. </p> <ul> <li>Taxa para café da manhã em estilo buffet: EUR 25.00 por pessoa (aproximadamente)</li> <li>Taxa para o acesso à internet com fio no quarto: EUR 15 por dia (as tarifas podem variar)</li> </ul> <p>A lista acima pode estar incompleta. As taxas e os depósitos podem não incluir impostos e estão sujeitos a mudanças. </p>",
"checkInSpInst": "O funcionário da recepção receberá os hóspedes na chegada. Para mais informações, entre em contato com o estabelecimento usando os dados que estão na confirmação da reserva. Os hóspedes que forem usar o traslado da Estação Central de Amsterdã devem entrar em contato com o estabelecimento com antecedência. Devido à COVID-19, as opções de comida e bebida deste estabelecimento podem estar limitadas de acordo com os regulamentos locais.",
"policies": "<ul> <li>Este estabelecimento oferece transporte da estação de trem. Os hóspedes devem entrar em contato com o estabelecimento antes da viagem com os detalhes da chegada usando as informações para contato presentes na confirmação da reserva. </li> <li>É necessário reservar os seguintes serviços: serviços de massagem. As reservas podem ser feitas contatando este hotel antes da viagem usando as informações para contato fornecidas na confirmação da reserva. </li> <li>Somente hóspedes registrados podem ter acesso aos quartos. </li></ul>",
"phone": "+31205191200",
"imageURIs": [
"https://i.travelapi.com/hotels/2000000/1460000/1452100/1452083/a39e2fc8_w.jpg",
"https://i.travelapi.com/hotels/2000000/1460000/1452100/1452083/3892e861_w.jpg",
"https://i.travelapi.com/hotels/2000000/1460000/1452100/1452083/aed25438_w.jpg"
],
"checkInTime": "15:00",
"checkInInst": "<ul> <li>Pessoas extras podem incorrer em taxas adicionais que variam dependendo da política do estabelecimento</li><li>Documento de identificação oficial com foto e cartão de crédito, cartão de débito ou depósito em dinheiro podem ser exigidos no momento do check-in para despesas extras.</li></ul>",
"reviewCount": 17538,
"chainID": "2101",
"checkInEnd": "01:00",
"lastBooked": 1608030831,
"checkOutTime": "12:00",
"feesMnd": "<p>Você deverá pagar os seguintes encargos no estabelecimento:</p> <ul><li>Depósito: EUR 50 por noite</li><li>A cidade cobra um imposto de EUR 3.00 por pessoa, por noite até 21 noites. Esse imposto não se aplica a crianças de até 16 anos. </li><li>Será cobrado um imposto municipal/local de 6.422 %</li></ul> <p>Incluímos todas as cobranças que o estabelecimento nos forneceu. No entanto, as cobranças podem variar com base, por exemplo, na duração da estadia ou no tipo de quarto reservado. </p>",
"deposit": {
"value": {
"currency": "USD",
"amount": 300
},
"description": "Deposit: USD 300.00 per accommodation<br>Breakage deposit: USD 230.00"
},
"reviewCountBkt": 9,
"hotelName": "Movenpick Hotel Amsterdam City Centre",
"sentiments": [
{
"value": "Gostou do bar",
"id": 46
},
{
"value": "Processo rápido de check-in/check-out",
"id": 180
}
],
"facilities": [
{
"categoryID": 4,
"importance": 2,
"value": "Centro de Negócios",
"id": 1
},
{
"categoryID": 17,
"importance": 2,
"value": "Serviço de quarto",
"id": 2
}
],
"placeID": "311007",
"guestType": {
"business": 1333,
"couples": 3125,
"families": 1484,
"groups": 1121,
"solo": 206
},
"themes": [
{
"value": "Cidade",
"id": 2
},
{
"value": "Empresarial",
"id": 12
}
],
"propertyType": {
"value": "Hotel",
"id": 0
},
"placeDisplayName": "Oostelijk Havengebied, Amsterdã",
"displayAddress": "Piet Heinkade 11, Oostelijk Havengebied, Amsterdã, Holanda"
}
}
Retrieves offers for a single hotel by provided parameters
const parameters = {
hotelId: "1196472",
checkIn: "2022-10-10",
checkOut: "2022-10-11",
rooms: "2",
};
const callbacks = {
onStart: (response) => {
log("Offers started", response);
},
onOffersReceived: (response) => {
log("Offers received", response);
},
onComplete: (response) => {
log("Offers completed", response);
},
};
const offers = await sapiClient.offers(parameters, callbacks);
name | type | description | required | example |
---|---|---|---|---|
hotelId |
string |
Hotel Id | yes | 1196472 |
checkIn |
string |
Check in date (YYYY-MM-DD) (SDK generates default date if no provided) | no | 2022-10-10 |
checkOut |
string |
Check out date (YYYY-MM-DD)) (SDK generates default date if no provided) | no | 2022-10-11 |
rooms |
string |
Rooms configuration | no | 2 |
searchId |
string |
SearchId override (SDK generates a new one if no provided) | no | 08230dfcc5f0fb95caaa82ce559ea60c4a975d6f |
cugDeals |
string[] |
Codes of closed user group deals to retrieve offers | no | ['signed_in', 'offline'] |
tier |
string |
User tier | no | member |
freeCancellation |
boolean |
(Deprecated, use freeCancellation in the filters object instead) If true, only offers with free cancellation will be returned | no | true |
isAnchor |
boolean |
Anchor/Non anchor hotel (default false ) |
no | true |
originId |
string |
Identifier of origin where the request was originated | no | c3po6twr70 |
label |
string |
Opaque value that will be passed to tracking systems | no | gha-vr |
preferredRate |
number |
Offer's price user saw on a CA (meta) platform | no | 196 |
metadata |
Record<string, string> |
Additional data to be passed to API | no | {esd: 'abcds', epv: 'qwert'} |
filters |
Object |
Object with filters | no | {pay_later:true} |
offersSort |
string |
If present, sorts offers by price (see explanation) | no | |
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 | |
optimizeRooms |
boolean |
If true then rooms optimization logic is enabled for non anchor hotels. Rooms optimization tries to find best offer across possible rooms configurations for a given occupancy |
no | |
optimizeAnchorRooms |
boolean |
If true then rooms optimization logic is enabled for an anchor hotel. Rooms optimization tries to find best offer across possible rooms configurations for a given occupancy |
no | |
sbc |
string |
Split Booking Configuration. If present, searches for split booking offers | no | sbc: '2~3' |
promos |
string[] |
The list of promos to enable | no | ['web2app'] |
Offer sorting by one parameter for now. It is price
, but there are different variants of sorting by price.:
- price:base_asc - sort offers by base price ascending
- price:total_asc - sort offers by total rate breakdown ascending
- price:with_tax_asc - sort offers by base rate with tax ascending
It overwrites OSO sorting and sorting boost as well. If offersSort parameter is provided, then OSO sorting and sorting boost will be ignored.
Object with callbacks:
const callbacks = {
onStart: (response) => {
log("Offers started", response);
},
onOffersReceived: (response) => {
log("Offers received", response);
},
onComplete: (response) => {
log("Offers completed", response);
},
};
-
Runs at the beginning of each new offers request.
Returns adjusted and validated offers request parameters. -
Runs on every received batch of offers.
Returns hotel's offers (incomplete response). -
Runs after offers request complete.
Returns hotel's offers (complete response).
An example of the response for request parameters:
const parameters = {
hotelId: "1926746",
checkIn: "2022-07-10",
checkOut: "2022-07-11",
rooms: "2",
};
The response with the detailed description can be found in the Offers Response
Returns availability of the provided hotels for different dates (aka price calendar)
const parameters = {
hotelIds: ["1380416", "1359951"],
startDate: "2023-08-05",
endDate: "2023-08-12",
nights: 2,
rooms: "2",
};
const callbacks = {
onStart: (response) => {
log("Availability request started", response);
},
onAvailabilityReceived: (response) => {
log("Availability received", response);
},
onComplete: (response) => {
log("Availability completed", response);
},
};
const response = await sapiClient.hotelAvailability(parameters, callbacks);
name | type | description | required | example |
---|---|---|---|---|
hotelIds |
string, string[] |
Hotel id(s) to retrieve offers for | yes | ['1380416','1359951'] |
startDate |
string |
Date of first check in (YYYY-MM-DD) | yes | '2023-10-10' |
endDate |
string |
Date of last check in (including). Can't be further than 61 days from StartDate (YYYY-MM-DD) | yes | '2023-10-11' |
nights |
number |
Nights is length of stay | yes | 3 |
rooms |
string |
Rooms configuration | yes | '2' |
cugDeals |
string[] |
Codes of closed user group deals to retrieve offers | no | ['signed_in', 'offline'] |
tier |
string |
User tier | no | 'member' |
originId |
string |
Identifier of origin where the request was originated | no | 'c3po6twr70' |
Object with callbacks:
const callbacks = {
onStart: (response) => {
log("Availability request started", response);
},
onAvailabilityReceived: (response) => {
log("Availability received", response);
},
onComplete: (response) => {
log("Availability completed", response);
},
};
-
Runs at the beginning of each new availability request.
Returns adjusted and validated availability search parameters. -
Runs on every received batch of availability.
Returns availability with offers (incomplete response). -
Runs after availability request is completed.
Returns availability with offers (complete response).
An example of the response:
{
"1380416": {
"2023-08-05": {
"hotelID": "1380416",
"cheapestRate": {
"base": 531.9901869159,
"taxes": 34.7298130841,
"hotelFees": 0
},
"offers": [
{
"id": "oEfGbUTje2BE",
"currency": "EUR",
"availableRooms": null,
"url": "https://r.vio.com?lbl=providerRateType%3Dmember&ofd=...",
"rate": {
"base": 531.9901869159,
"taxes": 34.7298130841,
"hotelFees": 0
},
"accessTier": "sensitive",
"providerCode": "WTM",
"intermediaryProvider": "FHT",
"package": {
"amenities": ["breakfast"],
"canPayLater": false
},
"cancellationPenalties": [
{
"start": "2023-07-30T10:00:00Z",
"end": "2023-08-02T09:59:00Z",
"amount": 0,
"currency": "EUR"
}
],
"tags": ["top_offer", "exclusive_cheapest_offer"],
"metadata": {
"providerRateType": "member",
"feedID": ""
},
"roomName": "STANDARD DOUBLE/TWIN"
}
]
},
"2023-08-06": {
"hotelID": "1380416",
"cheapestRate": {
"base": 493.9438317757,
"taxes": 32.2961682243,
"hotelFees": 0
},
"offers": [
{
"id": "omVVqhCXEbIw",
"currency": "EUR",
"availableRooms": null,
"url": "https://r.vio.com?lbl=providerRateType%3Dmember&ofd=book_uri...",
"rate": {
"base": 493.9438317757,
"taxes": 32.2961682243,
"hotelFees": 0
},
"accessTier": "sensitive",
"providerCode": "WTM",
"intermediaryProvider": "FHT",
"package": {
"amenities": ["breakfast"],
"canPayLater": false
},
"cancellationPenalties": [],
"tags": ["top_offer", "exclusive_cheapest_offer"],
"metadata": {
"providerRateType": "member",
"feedID": ""
},
"roomName": "STANDARD DOUBLE/TWIN"
}
]
}
}
}
Returns hotels customers reviews by hotel Id(s)
const result = await sapiClient.reviews(1099818);
const result = await sapiClient.reviews([1099818, 8596574]);
name | type | description | required | example |
---|---|---|---|---|
hotelIds |
string , string[]
|
Hotel Ids to get reviews for | yes | [1099818, 8596574] |
const result = await sapiClient.reviews(1099818);
{
"1099818": [
{
"checkIn": "2023-04-07",
"checkOut": "2023-04-10",
"language": "en",
"reviewDate": "2023-04-10 14:34:30",
"reviewSource": "WOT",
"reviewerName": "Pavel",
"reviewerScore": 10,
"text": "Great layout, friendly helpful staff, enjoyable stay"
},
{
"checkIn": "2021-12-25",
"checkOut": "2021-12-26",
"language": "en",
"reviewDate": "2022-01-05 23:21:58",
"reviewSource": "WOT",
"reviewerName": "Eamon",
"reviewerScore": 8,
"text": "Nice, clean and new"
}
]
}
rooms
is a string that encodes the configuration of rooms requested by the user and follows the next rules:
- Rooms are separated by pipe
|
- Adults and children are separated by colon
:
- Children ages are separated by comma
,
-
1:4,6|3
→ Two rooms, one with one adult and two children ages four and six and the other with three adults and no children -
3
→ One room with three adults and no children -
2:4
→ One room with two adults and one child aged four -
1:0,13,16
→ One room with one adult and three children (aged zero, thirteen and sixteen)
Every search should have a searchId
- a random unique string used for tracking purposes. SAPI SDK automatically generates a unique searchId
each time clients call search()
, rooms()
or offers()
methods. Sometimes it might be useful to preserve the searchId
between multiple actions. For this case all mentioned methods accept searchId
as a parameter and use it instead of internally generated one.
SAPI SDK exposes a special method generateSearchId
to generate searchId
which then can be used in the clients app.
import { generateSearchId } from "@findhotel/sapi";
const searchId = generateSearchId();
const rooms = await sapiClient.rooms({
hotelId: "47319",
checkIn: "2023-10-10",
checkOut: "2023-10-11",
rooms: "2",
searchId,
});