Fare data
Fare data is everything that decides what a traveller can buy and what it costs: the rules and parameters that apply to a product, the product itself, the prices, and the sales packages that make the product available in sales channels. As an Entur partner you can create and maintain your own fare data through the API.
The API enforces the rules that connect these elements. It checks that the parameters a product refers to exist and are published for the whole time the product is valid, and that the effective dates of an element's published versions have no overlaps or gaps. If a request breaks a rule, the API rejects it with a message that says why. See Versions and lifecycle for the rules.
Access
To create and maintain fare data, you need:
- An Entur partner agreement. Your organisation must be onboarded as a partner before it can use the API.
- A client with OAuth 2.0 client credentials. See Authentication.
- The
ET-Client-Nameheader on every request. - The permissions the endpoints you use need. The API reference lists the required permission for each endpoint.
Every element belongs to an organisation. When you create an element, it belongs to the organisation in your token. You can only change elements your organisation owns.
Data model
The fare data you maintain is made up of these elements:
| Element | What it is |
|---|---|
| Product | What the traveller gets, for example a ticket or a supplement. Supplement products (SupplementProduct), such as parking, bicycle or seat reservation, are one type. |
| Rules and parameters | Separate elements that decide when, where, for whom and on which conditions a product can be bought and used. Examples: a purchase window (PurchaseWindow) for when it can be bought, and a usage validity period (UsageValidityPeriod) for how long it can be used after purchase or activation. New types are added over time. See the Product parameters API. |
FareTable | The prices for a product. A product refers to its fare tables by id. |
SalesOfferPackage | What is actually sold in a sales channel. It contains one or more products. |
DistributionAssignment | Which sales channels may sell a sales package, and whether they may sell, refund or exchange it. |
Rules and parameters are shared. Several products can refer to the same parameter.
You change an element by creating a new version of it. Each version has effective dates, the travel dates it applies to, and a status that says which Entur environment it is available in: none yet, the staging environment for testing, or the production environment.
APIs
Fare data is spread across three partner APIs:
| API | Use it for |
|---|---|
| Products | Products and sales packages |
| Product parameters | Rules and parameters |
| Pricing | Fare tables |
Next steps
Read on:
- Versions and lifecycle explains versions, effective dates, statuses, the order to publish in, and the most common errors.
- Set up fare data takes you step by step from access to a published, priced product in a sales package.