Search Guide

Table of Contents

  1. How to use the Offers API
  2. Search Overview
    1. Search by trip pattern
    2. Search by stop places
    3. Search by authority
    4. Search by zones
    5. Search for personalised offers
      1. Campaign codes
      2. Personalisation programs
      3. Personnel tickets
      4. Discounted offers
  3. Search Response Overview
    1. Geographical Validity
  4. Offline clients

How to use the Offers API

(back to Table of contents)

Offers API provides REST-endpoints for generating offers that in turn can be used to create tickets, granting access to public transport services. The most typical use cases start by searching for a specific trip or an area of travel, using the Journey Planner API to find the necessary information to create Offers requests. Offers uses the definition of products defined in the Products API to calculate prices and evaluate valid products for the requested journey. For a more detailed guide on how to complete a sale, see the Sales guide.

Search Overview

(back to Table of contents)

Offers have four endpoints used to search for offers by different means:

  • Trip pattern when a specific departure is known.
  • Zones when the desired ticket should be valid for a zone or zones, but not a specific departure.
  • Stop places if the desired ticket should not be associated with any specific departure, but should yield travel rights between the two stop places provided.
  • Authority to search for offers from a specific authority. Typically, for products where geography is not a factor when calculating prices.

All endpoints return the same OfferSummary response, providing a concise overview of the offer without the underlying complexity of the product definition. Offers are valid for 30 minutes, after which they can no longer be purchased. A response header Expires is provided in the response indicating the time when the offer expires.

The products that give a user a right to travel are found under preassignedProducts. Each PreassignedProduct has an attribute properties shared with optionalProducts that contains most of the information needed for a given product.

Traveller combinations
It is strongly recommended to use one request per traveller or travelling party, in order to receive the correct products and recommendations for your traveller(s). Failure to do so may result in increased latency and/or no individual recommendations.

All requests for all endpoints must contain at least one traveller, represented by the travellers field. Either age or userType must be set.

To receive offers for optional supplement products for a traveller, the baggageTypes field containing the desired type(s) must be included.

To indicate that a traveller already holds a valid ticket (product, discount, or entitlement), include either productIds under each traveller in the travellers array, or provide the existingTicket object separately. Offers returned will consider the existing ticket(s) when determining which additional products may be needed, potentially at a reduced price. Use productIds under each traveller for single- or multi-traveller requests to indicate individually owned tickets (supported by all endpoints). For single-traveller requests that require specifying zones or service journeys, use existingTicket (available only in the Trip pattern and Zones endpoints).

For more info see Swagger documentation


Search by trip pattern

(back to Table of contents)
Swagger documentation

When a trip is found using the Journey Planner API, legs for the request to the Offers API can be constructed by extracting travelDate, fromStopPlaceId, toStopPlaceId, and serviceJourneyId from the Journey Planner response.

ExampleRequests to Journey Planner

  • travelDate is the operatingDay of the DatedServiceJourney representing the specific trip. Note that the date of embarkation at the requested from stop is not necessarily the same as the travelDate; typically for ServiceJourneys that starts before, and crosses midnight. operatingDay of the referred DatedServiceJourney will always point at the correct date, and for ServiceJourneys without a DatedServiceJourney, the date of the first estimated call is typically correct.
  • fromStopPlaceId is the id of the StopPlace where the leg starts
  • toStopPlaceId is the id of the StopPlace where the leg ends
  • serviceJourneyId is the id of the ServiceJourney that in combination with travelDate represents the specific trip

A request can contain multiple legs if the trip spans multiple means of transport.

ExampleRequests to search/trip-pattern

A basic request to the trip-pattern endpoint may contain tripPattern (including legs), and travellers (including userType or age).


If more than one traveller is travelling together, the travellers attribute can contain multiple Traveller objects, representing each traveller with their respective userType and/or age. Do not use grouping as a shortcut when searching for offers for multiple travellers unless they are expected to be travelling together. For requests with groups of travellers, the groupConfig attribute can be used to specify the number of compartments desired for a group (numberOfCompartments). This will only apply to products that are sold as group tickets and yields a compartment.

ExampleResponses from search/trip-pattern


Search by stop-places

(back to Table of contents)
Swagger documentation

Use the stop-places endpoint if you want to request offers that are not associated with any specific departure. The offers returned are period tickets or single tickets that are valid between stop places and for a given duration. Some combinations of stop places may result in offers that cover parts of the distance. As an example, let's say the "from" stop place is A, and the "to" stop place is C. There may not be a ticket that is valid from A to C, but tickets that are valid from A to B, and B to C. In that case you will receive offers that are valid for A to B and B to C. If you only want offers that cover the whole distance, set offersForWholeTripOnly to true.

ExampleRequest to search/stop-places

A basic request to the stop-places endpoint may contain travelDate, from, to, and travellers (including userType or age).

ExampleResponse from search/stop-places


Search by zones

(back to Table of contents)
Swagger documentation

Use the search/zones endpoint if you want to get offers for products that have validity based on zones specified. As with the search/stop-places endpoint, the search/zones endpoint responds with products that are not limited to a specific departure. From search/zones you will receive single tickets and period tickets that are valid in the zones specified and for the duration specified in the period ticket.

When a traveller already own a valid ticket, the fields productIds (when there can be one or more travellers) or existingTicket (only for when there is only one traveller) can be used.

ExampleRequests to search/zones

A basic request to the zones endpoint may contain travelDate, from, to, and travellers (including userType or age).

ExampleResponses from search/zones


Search by authority

(back to Table of contents)
Swagger documentation

Use the search/authority endpoint if you want to get offers for products with a static geographical validity, using only a traveller and authority as input. Only constraints that will have an affect are Purchase Window, Authority, Distribution Channel and User Profile, everything else will be ignored when evaluating the product definition.

ExampleRequests to search/authority

A basic request to the authority endpoint may contain travelDate, authorityId, and travellers (including userType or age).

ExampleResponses from search/authority


Search for personalised offers

(back to Table of contents)

Travellers might have certain benefits or entitlements that can be used to get discounted offers. This can be different kinds of campaigns the customer is part of, personalisation programs or other types of benefits.

Campaign codes

(back to Table of contents)

The campaign codes are set on the traveller object when searching for offers. If the code gives access to an entitlement that is valid for the offer, it will be returned with the discounted price.

Personalisation programs

(back to Table of contents)

For travellers that are part of a personalisation program, the search endpoints can be used to get discounted offers when the customer is identified by customerId. The customerId points to the customerNumber of the Entur-customer that is enrolled in a program.

If buying an offer will result in the customer gaining points in a personalisation program, it will be included in eligibleForAccrualInPrograms.

If a program appears in availablePrograms, the customer may be added to the program in order to be eligible for accrual. The caller must themselves implement the logic to add customers to personalisation programs, using the Personalisation API.

The id of the program can in turn be used to get more information about the program or check the customers status through the Personalisation API.


Personnel tickets

(back to Table of contents)

Some customers have an entitlement that gives them offers with greatly reduced price. For personnel tickets, the EntitlementProduct needs to be supplied directly in the Offers request, in addition to the customerId.

When reserving the offer in the /v1/reserve-offers Sales API, the EntitlementProduct needs to be supplied in the request as well.

Discounted offers

(back to Table of contents)

Offers that are discounted as a result of an applied entitlement or benefit, will contain information about the discount in the response. The discount summary is located under offers[].preassignedProducts[].discountRight in the Offers response.


Search Response Overview

(back to Table of contents)

All Offers endpoints return a SearchResponse, which may contain one or multiple OfferSummary. In addition, the response may include one or more components such as Recommendation (see Recommendations Guide), OptionalProduct, and UnavailableProduct.

OfferSummary presents one or more valid offers. Each offer includes details such as its name, description, price, the products it contains, geographical validity, and available fulfillment methods.

Geographical Validity

(back to Table of contents)

Geographical Validity is a component of the search response and may appear in multiple sections. It describes the geographical validity for where an offer, product or recommendation is valid. This includes validity on Service Journeys, Point To Point Validity, and Zonal Validity. In cases of replacement transport, these fields describe the replacement journey.

Service Journeys

The serviceJourneys field specifies the Service Journey and Dated Service Journey on which the product is valid.

Point To Point Validity

The pointToPointValidity field specifies the geographical start and stop places between which the product is valid.

Zonal Validity

The zonalValidity field specifies the geographical zones in which the product is valid. The fareZones field lists the specific fare zones where the product is valid, based on the zones the trip traverses. The namedGroupOfTariffZones field lists the Group of Tariff Zones that define the complete area of validity through the fare zones contained in these groups. If Zonal Validity includes namedGroupOfTariffZones, the group with its zones represents the full area of validity for the product, and the fareZones field is redundant and may be ignored. (In Offers v3, fareZones will not be listed when a namedGroupOfTariffZones is defined, since this encompasses all applicable fare zones by default.)


Offline clients

(back to Table of contents)

For clients that have poor or no access to the internet, we offer a solution where the client can download a set of data files that can be used to generate offers offline. Access to this functionality is given on request.

In essence, there are two different approaches, both sharing the same limitations. All methods return SearchResponseFull, which is more detailed than the regular search endpoints so that the client may build their own orders. Offers created this way cannot be used through the regular sales flow at Entur (/reserve-offers).

If the client wishes to get offers for specific trips, zones, stopPlaces etc, they can use the offline versions of the search endpoints. This approach gives the client full control over what they wish to request. The offline versions works exactly like their online counterparts, except for the limitations outlined above. All endpoints are also found in the api spec

  • Instead of /offers/v2/search/trip-pattern, use /offers/v2/offline-cache/trip-pattern
  • Instead of /offers/v2/search/zones, use /offers/v2/offline-cache/zones
  • Instead of /offers/v2/search/stop-places, use /offers/v2/offline-cache/stop-places
  • Instead of /offers/v2/search/authority, use /offers/v2/offline-cache/authority

ServiceJourney with StopPlaces

Swagger documentation

Generates offers for all subsequent pairs of stop places on the given ServiceJourney, for UserTypes ADULT, CHILD, INFANT, SENIOR, YOUTH, STUDENT and MILITARY. The products one can expect are restricted to single tickets without quotas, with no capacity requirements, no personalisation and no recommendations. In addition, only distance based products are supported. Do NOT use for zone based pricing.