@karhoo/demand-api

Karhoo Demand API

This library provides the ability to contact Karhoo's public API and allows you to send and receive network calls and responses. The Demand API is designed to enable it's consumers to integrate faster because they do not need to create their own complete network stack.

Read The Docs

---

Installation

npm i @karhoo/demand-api

Usage

You can use each service separately, or you can use getApi method which returns all available services

import {
  getApi,
  HttpService,
  LocationService,
  PoiService,
  QuotesV2Service,
  errorCodes,
} from '@karhoo/demand-api'

const url = 'https://public-api.karhoo.com' // please note that there should not be a slash at the end of the url

const correlationIdPrefix = 'prefix'

const requestOptionsGetter = () => ({
  headers: {
    'custom-header': 'Custom header',
  },
})

const middleware = <T>(response: HttpResponse<T>): HttpResponse<T> => {
  console.log(response.status)

  return response
}

Please note that by default fetch will be called with following config

{
  credentials: 'include',
  mode: 'cors',
}

You can override this default settings using defaultRequestOptionsGetter

getApi usage:

All config fields are optional, default value for url - https://public-api.karhoo.com in case if NODE_ENV === 'production', otherwise https://public-api.sandbox.karhoo.com.

Default value for correlationIdPrefix - ''.

Default value for authServiceDefaultOptionsGetter - () => ({}).

const options = {
  url,
  defaultRequestOptionsGetter: requestOptionsGetter,
  authServiceDefaultOptionsGetter,
  responseMiddleware: middleware,
  correlationIdPrefix,
}

const api = getApi(options)

Http service usage:

const apiV1 = 'https://public-api.karhoo.com/v1' // please note that version should be specified

const httpService = new HttpService(url)
  .setCorrelationIdPrefix(correlationIdPrefix)
  .setDefaultRequestOptionsGetter(requestOptionsGetter)
  .setResponseMiddleware(middleware)

const response = await httpService.post('locations/address-autocomplete', { query: 'lond' })

Location service usage:

const locationService = new LocationService(httpService)

Poi service:

const poiService = new PoiService(httpService)

Quotes service:

:warning: QuotesService is deprecated. Please use QuotesV2Service instead

const quotesService = new QuotesV2Service(httpService)

Trip service:

const tripService = new TripService(httpService)

Fare service:

const fareService = new FareService(httpService)

Payment service:

const paymentService = new PaymentService(httpService)

Flags service:

const flagsService = new FlagsService(httpService)

User service:

const userService = new UserService(httpService)

Auth service:

const authService = new AuthService(httpService)

Example

Let's see how to use one of the services, listed above.

For example, you need to get a list of quotes for trip from one location to another. For this purpose you have to use Quotes service and call quotesSearch method:

const quotesSearchParams = {
  origin: {
    latitude: '51.501364',
    longitude: '-0.14189',
    displayAddress: 'Buckingham Palace, London SW1A 1AA',
  },
  destination: {
    latitude: '41.78650',
    longitude: '1.78954',
    displayAddress: 'Big Ben, Westminster, London SW1A 0AA, UK',
  },
  local_time_of_pickup: '2020-05-12T10:00',
}

const quotesResponse = quotesService
  .quotesSearch(quotesSearchParams)
  .then(result => {
    //handleResult
  })
  .catch(error => {
    //handle error
  })

Issues

Looking to contribute?

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior with a label API

💡 Feature Requests

Please file an issue to suggest new features with a label API. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

❓ Questions

For questions related to using the library, please re-visit a documentation first. If there are no answer, please create an issue with a label help needed and API.

Contributing

License

BSD-2-Clause

Changelog

20.1.2 (2024-01-17)

Note: Version bump only for package web-lib-demand