@findhotel/sapi

Table of Contents

1. Glossary
2. Tutorials
   1. Getting Started
   2. Usage
      1. Hotels search
      2. Get rooms
3. API Reference
   1. SAPI client
      1. Supported options
      2. Available client callbacks
   2. search() method
      1. Search parameters
      2. Callbacks
      3. Response
   3. suggest() method
      1. Suggest parameters
      2. Response
   4. rooms() method
      1. Rooms parameters
      2. Response

SDK provides a high level TypeScript/JavaScript API for searching hotels, hotels' offers and rooms.

Glossary

Glossary contains terms that are used throuout the documentation.

• HotelId: FindHotel hotel id
• Itinerary: tuple of hotelId, checkIn, checkOut

Tutorials

Getting Started

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',
  userCountry: 'US'
})

Now SAPI client is ready to be used in your application.

For full documentation and supported options check client api.

Usage

Hotels search

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) => {
    console.log('Search started', response)
  },
  onAnchorReceived: (response) => {
    console.log('Anchor received', response)
  },
  onHotelsReceived: (response) => {
    console.log('Hotels received', response)
  },
  onOffersReceived: (response) => {
    console.log('Offers received', response)
  },
  onComplete: (response) => {
    console.log('Search completed', response)
  }
}

const search = await sapiClient.search(searchParameters, callbacks)

For full documentation, check search method api.

Get rooms

Get rooms 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.

API Reference

SAPI client

Create SAPI client:

const profileKey = 'profile-key'

const sapiClient = await sapi(profileKey, {
  anonymousId: 'fd9dbb5f-b337-4dd7-b640-1f177d1d3caa',
  language: 'en',
  currency: 'USD',
  userCountry: 'US',
  deviceCategory: 'mobile',
  includeLocalTaxes: true,
  includeTaxes: false,
  pageSize: 20,
  useSaf: false,
  initWithProfile: {
    features: ['search', 'configs'],
  },
  algoliaClientOptions: {
    timeouts: {
      connect: 1, // Connection timeout in seconds
      read: 2, // Read timeout in seconds
      write: 30, // Write timeout in seconds
    },
  },
  callbacks: {
    onConfigReceived: (config) => {
      console.log('Config received', config)
    }
  }
})

Supported options

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`
`userCountry`	no	`string`	`US`	2-char uppercased ISO country code	`US`
`deviceCategory`	yes	`string`		`desktop` or `mobile`	`desktop`
`includeLocalTaxes`	no	`boolean`		Include or not local taxes based in the displayed price	`false`
`includeTaxes`	no	`boolean`		Include or not taxes based in the displayed price	`false`
`pageSize`	no	`number`	`20`	Displayed page size	`20`
`initWithProfile`	no	`Record`		External profile to override internal client profile
`algoliaClientOptions`	no	`AlgoliaSearchOptions`		Algolia client options used for debugging and setting additional options like timeouts etc.
`variations`	no	`Record`		A/B test variations	`{'pp000004-tags2': 'b', 'pp000004-tags3': '1'}`
`callbacks`	no	`Record`		Client callbasks

Available client callbacks

1. onConfigReceived(configs)

   Returns configuration settings that are in use by sapiClient when received from remote endpoint.

search() method

Search is a method of sapiClient for searching hotels and offers for provided searchParameters:

const search = await sapiClient.search(searchParameters, callbacks)

Search parameters

All parameters are optional.

name	type	description	example
`hotelId`	`string`	Hotel Id for hotel search. If present, takes precedence over `placeId`, `query` and `geolocation`.	`1371626`
`placeId`	`string`	Place Id for place search. If present, takes precedence over `query` and `geolocation`.	`47319`
`geolocation`	`{lat: number, lon: number}`	Geolocation query. If present, takes precedence over `query`	`{lat: 36.114303, lon: -115.178312}`
`query`	`string`	Free-text query	`Amsterdam city`
`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](https://github.com/FindHotel/search-data-pipelines/wiki/Glossary#rooms-configuration)	`2`

Callbacks

Search method receives callbacks object as the second argument:

const callbacks =  {
  onStart: (response) => {
    console.log('Search started', response)
  },
  onAnchorReceived: (response) => {
    console.log('Anchor received', response)
  },
  onHotelsReceived: (response) => {
    console.log('Hotels received', response)
  },
  onOffersReceived: (response) => {
    console.log('Offers received', response)
  },
  onComplete: (response) => {
    console.log('Search completed', response)
  }
}

1. onStart()

   Runs at the beginning of the 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.

2. onAnchorReceived()

   Runs when SAPI receives anchor (and?) anchor hotel
   response - in progress…

3. onHotelsReceived()

   Runs when SAPI receives static search results
   response - in progress…

4. onOffersReceived()

   Runs when SAPI receives a bunch of offers
   response - in progress…

5. onComplete()

   Runs when current search is complete and all offers are retrieved
   response - in progress…

Response

in progress…

suggest() method

Suggest provides autosuggestions for a given query

const suggestions = await sapiClient.suggest('London', 6)

Suggest parameters

name	type	description	required	example
`query`	`string`	Query string	yes	`London`
`suggestsCount`	`number`	Desired number of suggestions (default 6)	no	`10`

Response

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"
  }
]

rooms() method

Rooms is a method of sapiClient for retrieving rooms information and offers for a particular itinerary:

const rooms = sapiClient.rooms({
  hotelId: '47319',
  checkIn: '2021-10-10',
  checkOut: '2021-10-11',
  rooms: '2'
})

Rooms parameters

name	type	description	required	example
`hotelId`	`string`	Hotel Id to retrieve rooms	yes	`1371626`
`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](https://github.com/FindHotel/search-data-pipelines/wiki/Glossary#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`

Response

in progress…

SAPI rooms() method will have the similar response body as BoFH API /rooms endpoint. For now please refer to BoFH documentation.