Search Guide

Table of Contents

  1. How to use the Offers API
  2. Search by trip pattern
  3. Search by stop places
  4. Search by authority
  5. Search by zones
  6. Search for personalised offers
    1. Campaign codes
    2. Personalisation programs
    3. Personnel tickets
    4. Discounted offers
  7. 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 starts 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 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 end points return the same OfferSummary response, providing a concise overview of the offer without the underlying complexity of the product definition. The offers are valid for 30 minutes, after which time 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.

Travaller 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.

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.

  • 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.

The endpoint also requires that at least one Traveller is specified.

ExampleRequests to search/trip-pattern

If the traveller already owns a valid ticket, the existingTicket attribute can be used to specify the zones the ticket is valid for, to potentially get offers that can be combined with the existing ticket for a reduced price. When supplying an existingTicket, only one traveller can be specified in the request.

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

ExampleResponse from search/stop-places

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

ExampleResponses from search/authority

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.

ExampleRequests to search/zones

ExampleResponses from search/zones

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.

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.