Search offers
This guide gets you from zero to your first Sales v2 .
Eager to start experimenting with code? Explore the Sales v2 API spec directly at https://developer.entur.no/apis/sales/latest/openapi.json (does not require auth).
Before you begin
To use this guide, you need to:
- Be an authorised Entur partner.
- Have OAuth2 client credentials (
client_idandclient_secret). - Have header values for and .
- Use the Sales v2 dev base URL
https://api.dev.entur.io/sales/v2.
See Authentication.
1. Specify who is travelling
When searching for offers, Sales v2 supports two traveller models:
individual_traveller: an identifiable traveller (with specific attributes such as age, name, and possibly other personal details).user_profile: an anonymous traveller profile with a count.
You can use one of them, or both in the same request.
Both models require an id that you supply. It can be any string up to 200 characters, so you can reuse IDs from your own system.
Sales v2 keeps these IDs throughout the purchase. You refer to them as travellerId when you update or remove a traveller in a draft package.
Code
2. Search for your first offer
Use the search-offers process to send your first request.
Using place references
Sales v2 supports several place models in specification, most commonly:
- Fare zones (
ORG:FareZone:*) - Stop places (
NSR:StopPlace:*) - GPS coordinates (
GPS:lat,long[,alt])
Searching with zones or stop places is a common way to search for simple single-product offers, typically to let the user purchase a single ticket in a specific zone or set of zones.
These place references are used throughout the Entur platform and are based on concepts. Read about the and concepts, or see all accepted formats for Sales v2 .
Code
Use FareZone in your application. Sales v2 does not support the deprecated spelling TariffZone, which some other Entur services still accept.
Using trip patterns from Journey Planner
You can also use a TripPattern from the Entur Journey Planner to search for offers, which is often the preferred way to search for offers.
Code
When using a TripPattern, the client is responsible for the integration with Entur's Journey Planner and any use of Entur's Geocoder API for autocompletion or reverse geocoding.
3. Understand the response
Confirm that:
- The request returns HTTP
200. - The response contains at least one .
- Returned offers match expected s and traveller inputs.
Example response
Code
Sales v2 returns offers with Leg objects, even for simple Zone-Zone or StopPlace-StopPlace searches. In these cases, the leg represents a single traveller on a single product. To see which traveller belongs to which product, check the legs.
Troubleshooting tips
- If you receive an empty
offersarray, check that yourspecificationparameters (place IDs, time range) align with available data in the dev environment. - Common errors are invalid place IDs, duplicate traveller IDs, and missing required fields or headers.
- If requests fail with
401or403, check that your OAuth2 token is valid and has the scopes for Sales v2, and that the headers match your distribution channel and POS. - If you need help, contact Entur support with your request and response. Include the
X-Correlation-IDresponse header so we can trace the request.
Next steps
Coming soon
- Apply discounts for eligible travellers, such as students and employees, with
entitlements. - Search for a group of travellers.