This SDK simplifies the use of Entur's travel APIs in JavaScript apps. For more information about Entur's APIs, see https://www.entur.org/dev/
Miss anything? Found a bug? File an issue or create a pull request!
npm install @entur/sdk@^0.10.3 --savev1.0.0-next.x versions are still experimental, and we recommend installing the latest v0.x release.
import EnturService from '@entur/sdk'
const service = new EnturService({ clientName: 'awesomecompany-awesomeapp' })| Name | Type | Default | Description |
|---|---|---|---|
| clientName | string |
undefined |
The name of your application |
| hosts | {object of hosts} |
{} |
Override default endpoints |
We require that you pass a clientName that identifies your application. It should contain the name of your company or organization,
followed by a hyphen and your application's name. See https://www.entur.org/dev/api/header/ for more information.
The Entur SDK uses multiple endpoints for its services. Each endpoint can be overridden with hosts config (in case you use a proxy or a local instance of the endpoint). Available hosts are:
{
journeyplanner: '',
geocoder: ''
}(from: string, to: string, date?: Date | string | number) => Promise<Array<TripPattern>>Finds up to 5 trip patterns from to at the time specified. This is a convenience method, which first tries to find locations for the given and strings before searching for trips between them. If you need more control, see the getTripPatterns method.
If no locations are found for either or , or if is invalid, an error will be thrown.
The place you want to search from. For instance "Oslo"
The place you want to search from. For instance "Bergen"
The wanted time of departure. Can be anything that is parseable by new Date(). If not provided, the search will be from "now".
(query: TripPatternsQuery) => Promise<Array<TripPattern>>Types: TripPattern
getTripPatterns is for searching for itineraries for a trip from some location to a destination at a given time. The method takes one argument query, which is an object with search parameters.
If you are going to do a huge amount of different searches at the same time, consider using our throttler utility.
A search query is an object on the following form.
| Key | Type | Default | Description |
|---|---|---|---|
searchDate |
Date |
when to calculate patterns | |
from |
Location |
departure location | |
to |
Location |
arrival location | |
arriveBy |
boolean |
false |
depart by searchDate, or arrive by searchDate |
modes |
Array of Modes |
['foot', 'bus', 'tram', 'rail', 'metro', 'water', 'air'] |
modes of transport to include in trip |
limit |
number |
5 |
Limit search to |
wheelchairAccessible |
boolean |
false |
include only stops which are wheelchair accessible |
service.getTripPatterns({
searchDate: new Date(),
from: {
name: 'Ryllikvegen, Lillehammer',
coordinates: {
latitude: 61.102848368937416,
longitude: 10.51613308426234
},
},
to: {
place: 'NSR:StopPlace:337',
name: 'Oslo S, Oslo'
}
})See example/get-trip.js for a more in depth example
(query: string, coords?: Coordinates, params?: GetFeaturesQuery) => Promise<Array<Feature>>Types: Feature, Coordinates
getFeatures is for searching for stop places, stations or addresses.
The search string that should resemble the name of the desired stop place or address. Examples: "Oslo S", "Schweigaards gate 23, Oslo", "Voss stasjon".
A set of coordinates to use when the weighting search results. Examples: { latitude: 59.909774, longitude: 10.763712 }.
The results closest to the coordinates will be weighted above results with equally good string matches.
As an example, the street Dronningens gate exists both in Oslo and Trondheim. If you call service.getFeatures('Dronningens gate', { latitude: 63.4305103, longitude: 10.3949874 }) (coordinates of Trondheim city center), the Dronningens gate in Trondheim will be preferred to the one in Oslo.
An optional object of parameters to pass to the query.
| Key | Type | Default | Description |
|---|---|---|---|
layers |
string |
"venue,address" |
The types of places to search for in a comma-separated string. venue means stop places and stations, address means postal addresses that might not be connected to public transport. |
(stopPlaceId: string, params?: GetStopPlaceDeparturesParams) => Promise<Array<EstimatedCall>>(stopPlaceIds: Array<string>, params?: GetStopPlaceDeparturesParams) => Promise<Array<{ id: string, departures: Array<EstimatedCall> }>>Types: EstimatedCall
getStopPlaceDepartures finds departures from one or more given stop places.
The ID or IDs of the stop places you are interested in. If a string is passed, it is interpreted as a single ID. The method will then return a Promise which will resolve to an array of departures for that stop place.
If an array of strings is passed, the method will return an array of objects containing fields for the stop place's id and departures.
An optional object of parameters to pass to the query.
| Key | Type | Default | Description |
|---|---|---|---|
startTime |
ISO8601 string | Now | DateTime for when to fetch estimated calls from. |
timeRange |
number |
86400 |
The time range for departures to include in seconds. |
departures |
number |
5 |
The number of departures to return for each stop place. |
includeNonBoarding |
boolean |
false |
Whether to include departures that do not accept boarding at given stop place. |
(stationId: string) => Promise<BikeRentalStation>Types: BikeRentalStation
getBikeRentalStation finds a single bike rental station by its ID.
The ID of the bike rental station you are interested in. The method will return a Promise which will resolve to an object of type BikeRentalStation.
(coordinates: Coordinates, distance?: number) => Promise<Array<BikeRentalStation>>Types: BikeRentalStation
getBikeRentalStations finds bike rental stations within an area surrounding a coordinate.
The coordinates of which to find bike rental stations around.
Default: 500
The "radius" in meters of the surrounding bounding box in which you want to find bike rental stations.
The width and height of the bounding box are therefore 2 * distance, and the coordinates given are its centerpoint.
(id: string) => Promise<StopPlace>Types: StopPlace
getStopPlace finds the stop place with the given ID.
(coordinates: Coordinates, distance?: number) => Promise<Array<StopPlace>>Types: StopPlace
getStopPlacesByPosition finds stop places within an area surrounding a coordinate.
The coordinates of which to find bike rental stations around.
Default: 500
The "radius" in meters of the surrounding bounding box in which you want to find stop places.
The width and height of the bounding box are therefore 2 * distance, and the coordinates given are its centerpoint.
If you are going to do a lot of requests at the same time, you are likely to exceed our rate limits.
To help you with this, we have a throttler utility that throttles the requests in order to respect the rate limits.
Example usage:
import EnturService, { throttler, convertFeatureToLocation } from '@entur/sdk'
const service = new EnturService({ clientName: 'myawesomecompany-myawesomeapp' })
async function getTripPatternsForVeryManyDifferentLocations() {
const [fromLocation] = await service.getFeatures('Oslo S')
const [toLocation] = await service.getFeatures('Drammen stasjon')
const params = {
searchDate: new Date(),
from: convertFeatureToLocation(fromLocation),
to: convertFeatureToLocation(toLocation),
}
// A huge array of arguments that we want to call a function with, one by one.
const queries = Array(3000).fill(params)
// We pass the function and the huge list of arguments to the throttler.
// The resulting list will be in the same order as the arguments passed.
const tripPatterns = await throttler(query => service.getTripPatterns(query), queries)
console.log('Done!')
return tripPatterns
}
We provide library definitions for Flow and TypeScript. TypeScript should work out of the box. For Flow, make sure you include the following in your .flowconfig:
[libs]
node_modules/@entur/sdk/lib/libdef.flow.js