Intro

Welcome to the Offers API.

Offers API provides endpoints for generating and retrieving offers for a combination of origin and destination.

The Offers API provide four endpoints:

• Search for offers with a trip pattern generated from Journey Planner
• Search for offers with zones from National Stop Register (NSR)
• Search for offers with stop places from National Stop Register (NSR)
• Search for offers with your authority id

The services enrich the request with information about the journey requested, inventory and seating before identifying all possible offers and calculating price. Be the response is returned, the services filter unavailable offers and grouping offers in recommendations. Offers API is caching the produced offers for 30 minutes.

Authentication

Currently, the only requirement for authentication is when requesting offers for a certain distribution channel. Some offers are only valid for a specific distribution channel, these offers can only be retrieved if a valid combination of an Entur-issued 0Auth2 bearer token and distribution channel is passed in the request.

In order to issue a valid token you must have a client_id and client_secret(the mechanisms for obtaining these are not in place yet).

curl --request POST \
  --url 'https://<type_of_token>.<environment>.entur.org/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"client_credentials","client_id": "<clientid>","client_secret": "<clientsecret>","audience": "https://api.<envirnoment>.entur.io"}

Headers

All requests will have a correlation id which is pertained with a request as it propagates through the system. This value will show which request is being processed as it flows through the system. This value is automatically created and maintained by the internal logging library, and should not require any further actions from client developers.

Currency

The Offers API has a standardised way of representing value of products. Firstly, a currency code must always be specified for a given product (e.g. "NOK", "USD", etc.). Secondly, the amount for the given currency is represented as a numeric string with two decimal points (e.g. "100.00").