Trippe 🏨

Unofficial Node client to check hotel prices and reward night availability at over 6.000 hotels worldwide - suitable for an intercontinental lifestyle. Please get in touch with the hotel company before using this software in production. Please also note that Trippe will not work 'out of the box' but needs a (static) API key to perform any request to the backend.

First of all

This is both a labour of love and a work in progress. During development Trippe has been tested and fine-tuned thoroughly, things like method names and the structure of both parameters as well as output are unlikely to change anytime soon. There are however a sheer infinite number of combinations when it comes to hotels, prices and dates meaning 'special cases' are bound to keep popping up. If you find a bug or just notice that the output of a certain search makes no sense at all, make sure to open an issue.

Installation

npm install trippe

Warning: This package is native ESM and does not provide a CommonJS export. If your project uses CommonJS, you'll have to convert to ESM or use the dynamic import() function.

Getting started

Import Trippe and set up a new instance of the class with the API key as the sole parameter:

import Trippe from 'trippe'

const trippe = new Trippe('API_KEY')

Usage

getHotelDetails(hotelCode)

The getHotelDetails method will return some basic info on a specific hotel in the system. It needs a single parameter, in the form of the unique hotelCode of the property. This id of 5 characters (all letters, all uppercase) will be used for almost every other method as well.

// Get details for a specific hotel in Antwerp, Belgium
const hotelDetails = await trippe.getHotelDetails('ANRAW')

Returns

Returns a Promise that will resolve with an object containing the following keys:

| Key | Type | Description | | --- | ---- | ----------- | | hotelCode | String | The systemwide id ('mnemonic') of the hotel | hotelName | String | The name of the hotel, not taking into account the brand name of the (sub)chain it belongs to | brandCode | String | The code of the (sub)chain the hotel belongs to | brandName | String | The brand name of the (sub)chain the hotel belongs to | description.long & description.short | String | A description of the property, in two formats | numberOfRooms | Number | The number of available rooms | closestCity | String | The closest city to the hotel (could be the actual city of the address) | street | Array | The street part of the property address, with one entry for each line needed (maximum 2) | postalCode | String | The postal code of the property | city | String | The city the hotel is in | state | String | The state part of the address, null when not locally used | country | String | The country the hotel is in, expressed as an ISO 3166-1 alpha-2 code | coordinates | Array | The coordinates of the hotel, expressed as [longitude, latitude] | url | String | The URL of the hotel's homepage

getStayPrices(hotelCode, [options])

The getStayPrices method allows you to get a full list of all possible prices at a specific hotel and for a specific set of dates. It returns a list of room types available for booking (Standard Room, Junior Suite...), the different rate plans being offered (Advanced Purchase, Non-Refundable, Member Rates...) and the price of any combination of rooms and rates - both in points as well in cash including taxes.

// Get all available rates for a two-night stay in Tokyo
const stayPrices = await trippe.getStayPrices('TYOHB', {
  checkinDate: '2023-03-01',
  checkoutDate: '2023-03-03',
  adults: 2
})

Options

As above, the hotelCode parameter should always be provided. The options object is optional, as are any of its keys. Keys and default values are as follows:

| Key | Type | Default | Description | | --- | ---- | ------- | ----------- | | checkinDate | String | Today's date in your local timezone | The check-in date in ISO 8601 date format | | checkoutDate | String | The date following the checkinDate | The checkout date in ISO 8601 date format | | adults | Number | 1 | The number of adults sharing the room | | children | Number | 0 | The number of children sharing the room |

Returns

Returns a Promise that will resolve with an object containing the following keys:

| Key | Type | Description | | --- | ---- | ----------- | | products | Array | Available products (room types), see below | | ratePlans | Array | Available rate plans, see below | currencyCode | String | The ISO 4217 currency code in which prices are expressed | | prices | Array | Available combinations of products and rate plans, see below

The products array contains objects with these keys:

| Key | Type | Description | | --- | ---- | ----------- | | productCode | String | A 4-letter code indicating the type of room | | productName | String | The name of the room type as displayed to the user | | productDescription | String | A longer description of the room type | | productIsPremium | Boolean | Whether this is considered to be a premium room at the hotel |

The ratePlans array contains objects with these keys:

| Key | Type | Description | | --- | ---- | ----------- | | rateCode | String | A short code indicating the type of rate | | rateName | String | The name of the rate plan as displayed to the user | | rateDescription | String | A longer description of the rate plan |

Rate plans might differ by things such as payment and cancellation conditions, whether membership in the loyalty program is required to book it, whether breakfast is included and by the number of bonus points being awarded to members. Please note that a rate plan being listed here does not mean that it will be available for this stay. The same goes for a product being included in the products array.

Finally, the combinations of products and rate plans being offered are listed in the prices array which contains objects with these keys:

| Key | Type | Description | | --- | ---- | ----------- | | productCode | String | The product id, as used in products above | | rateCode | String | The rate plan id, as used in ratePlans above | | cashPrice | Number | The room price in the hotel's currency. Will be null for reward rates | | points | Array or null | The room price in points, including points and cash offers - formatted as an array of objects with points and cashPrice keys. Will be null if the rateCode refers to a cash rate |

Please note that any cashPrice included as part of a cash and points offers will always be in US Dollars!

getDestinations(query)

The getDestinations method can autocomplete any geographic text query and show the corresponding set of coordinates. Useful queries include (partial) city or airport names, landmarks and even full addresses in major cities.

const destinations = await trippe.getDestinations('Van')
// Returns suggestions such as 'Vancouver, BC, CAN' and 'Van Gogh Museum, Amsterdam, Netherlands'

Returns

Returns a Promise that will resolve with an array of objects each containing the following keys:

| Key | Type | Description | | --- | ---- | ----------- | | display | String | The text of the suggested destination | | coordinates | Array | The coordinates of that destination in [longitude, latitude] format |

Although queries are language-specific, getDestinations can for the moment only work with query strings in English. More language support is coming soon.

getLowestAreaPrices(coordinates, [options])

The getLowestAreaPrices method allows you to compare hotel prices in a radius of up to 100 miles / 160 kilometres around a geographic centre point. It will provide you with the lowest price (in both cash and points) available at each hotel within that radius for a given night and including taxes. Prices always represent a stay of 1 night in 1 room, but you can specify the number of guests.

// Get the lowest prices for a one-night stay in a radius of 20 km
// around the Place de la Concorde in Paris
const lowestAreaPrices = await trippe.getHotelDetails([2.321096215980252, 48.86542132948351], {
  radius: 20,
  unit: 'km',
  checkinDate: '2023-04-01'
  adults: 2
})

Coordinates should be expressed as [longitude, latitude] (can be exported from getDestinations). As with all methods that involve specifying a date, Trippe expects the checkinDate to be a string formatted as YYYY-MM-DD (AKA ISO 8601)

Options

The options object is optional, as are any of its keys. Keys and default values are as follows:

| Key | Type | Default | Description | | --- | ---- | ------- | ----------- | | radius | Number | 100 | The search radius around coordinates up to a maximum value of 100 | | unit = | String | mi | Either 'mi' for miles or 'km' for kilometres | | checkinDate | String | Today's date in your local timezone | The check-in date in ISO 8601 date format | | adults | Number | 1 | The number of adults sharing the room | | children | Number | 0 | The number of children sharing the room |

Returns

Returns a Promise that will resolve with an array of objects each containing the following keys:

| Key | Type | Description | | --- | ---- | ----------- | | hotelCode | String | The systemwide id ('mnemonic') of the hotel | | cashPrice | Number | The lowest available price at the hotel for that night, in the hotel's currency | | currencyCode | String | The ISO 4217 currency code in which the cashPrice is expressed | | points | Number | The lowest available price at the hotel for that night, in points |

Please note that this method will not include hotels that have no rooms available. You should therefore not use this method to get a list of hotels in a certain area.

getLowestHotelPrices(hotelCode, [options])

The getLowestHotelPrices method will do more or less the opposite of the getLowestAreaPrices method above. It will provide you with pricing data from one single hotel (as specified by hotelCode) but spread out over up to 62 days. This 'price calender' shows both cash rates as well as prices in points. It is important to note though that cash prices DO NOT include taxes - see below for more details.

// Get a calendar of prices for a stay in Mexico City in spring (April and May)
const lowestPrices = trippe.getLowestHotelPrices('MEXHA', {
  startDate: '2023-04-01',
  endDate: '2023-05-30'
})

Options

The options object is optional, as are any of its keys. Keys and default values are as follows:

| Key | Type | Default | Description | | --- | ---- | ------- | ----------- | | startDate | String | Today's date in your local timezone | The first check-in date (in ISO 8601 date format) for which prices are to be determined | | endDate | String | Today's date in your local timezone + 59 days | The last check-in date (in ISO 8601 date format) for which prices are to be determined |

Returns

Returns a Promise that will resolve with an array of objects each containing the following keys:

| Key | Type | Description | | --- | ---- | ----------- | | checkinDate | String | The check-in date to which these prices are applicable (in ISO 8601 date format) | | currencyCode | String | The ISO 4217 currency code in which prices are expressed | | cashPrice | Number | The lowest room price in the hotel's currency. Will be null if no rooms are available. | | points | Array or null | The lowest room price in points. Will be null if no reward stays are available. |

All prices reflect a one-night stay by 1 adult in 1 room.

getBookingPageUrl(hotelCode, [options])

The getBookingPageUrl method will allow you to link to the booking page on the official site. When using the URL returned by this method, all details about the stay will be prefilled and users will be able to select a room type and rate.

// Book a two-night stay in early March in Tokyo
const bookingUrl = await trippe.getBookingPageUrl('TYOHB', {
  checkinDate: '2023-03-01',
  checkoutDate: '2023-03-03',
  adults: 2
})

Options

This method uses the same parameters as the getStayPrices method

Returns

The URL as a string.

Good to know

Taxes

TL;DR: It's complicated. You should probably avoid getting prices without tax from the API or be sure you can correctly calculate the additional taxes yourself.

Most Trippe methods will return cash prices with all taxes included and thus represent the final and full price to pay at the time of booking. The only method that doesn't follow this logic is getLowestHotelPrices which will mostly show prices without taxes as that is all the API gives us for this method.

The difference isn't however as clear-cut as you'd expect. Depending on local laws, prices without taxes might already include things like a sales tax but not an often much smaller local tourism tax that is added per person and night. This is certainly the case for many European hotels which means that, in locations where no tourism tax is added, prices with and without taxes could be the same.

In other places the difference between both numbers may be significant as sales taxes, local hotel taxes and so-called amenity fees CAN be left out and really add up. While Trippe could get itemised tax rates for each hotel from the hotel, it turns out that these numbers aren't always correct - certainly not often enough to feed them to an automated system.

Throttling

Every method listed above corresponds to - at the most - one underlying API call. This means, for instance, that using the getLowestAreaPrices will not return hotel names, as this info is not returned from the API. It is up to your code to use getHotelDetails to translate a hotelCode to the name, address or location of the hotel in question and to store that information where needed. It also means that Trippe doesn't do any throttling* towards the API. Your code should make sure that calls to Trippe methods are 'spaced out' in such a way that you don't get blocked by the API. For a quick and easy rate-limiting setup, Bottleneck works well.

Contributing

If you found a bug or want to propose a feature, feel free to visit the issues page.