API Documentation
Rate Limit
The number of HTTP requests you can send is constraint by the rate limit of timetable.search.ch.
API Resources
The Transport API builds on REST style resources which respond in JSON. Individual resources are detailed below. Cross Origin Resource Sharing (CORS) is enabled, so you can easily use the API on transport.opendata.ch from any website (avoid setting custom headers though).
/locations
Returns the matching locations for the given parameters. Either query
or ( x
and y
) are required.
The locations in the response are scored to determine which is the most exact location.
This method can return a refine response, what means that the request has to be redone.
Resource URL
http://transport.opendata.ch/v1/locations
Request Parameters
Name | Required | Description | Example |
---|---|---|---|
query |
optional | Specifies the location name to search for | Basel |
x |
optional | Latitude | 47.476001 |
y |
optional | Longitude | 8.306130 |
type |
optional |
Only with query parameter.
Specifies the location type, possible types are:
|
address |
Response parameters
Name | Description |
---|---|
stations |
A list of locations |
Example Request
GET http://transport.opendata.ch/v1/locations?query=Basel
Example response
{ "stations": [ { "id": "000000022", "name": "Basel", "score": null, "coordinate": { "type": "WGS84", "x": 47.547408, "y": 7.589547 }, "distance": null } ] }
/connections
Returns the next connections from a location to another.
Resource URL
http://transport.opendata.ch/v1/connections
Request Parameters
Name | Required | Description | Example |
---|---|---|---|
from |
required | Specifies the departure location of the connection | Lausanne |
to |
required | Specifies the arrival location of the connection | Genève |
via |
optional | Specifies up to five via locations. When specifying several vias, array notation (via[]=via1&via[]=via2 ) is required. |
Bern |
date |
optional | Date of the connection, in the format YYYY-MM-DD | 2012-03-25 |
time |
optional | Time of the connection, in the format hh:mm | 17:30 |
isArrivalTime |
optional | defaults to 0 , if set to 1 the passed date and time is the arrival time |
1 |
transportations |
optional | Transportation means; one or more of train , tram , ship , bus , cableway |
transportations[]=tram& transportations[]=bus |
limit |
optional | 1 - 16. Specifies the number of connections to return. If several connections depart at the same time they are counted as 1. | 4 |
page |
optional | 0 - 3. Allows pagination of connections. Zero-based, so first page is 0, second is 1, third is 2 and so on. | 3 |
Response parameters
Name | Description |
---|---|
connections |
A list of connections |
Example Requests
GET http://transport.opendata.ch/v1/connections?from=Lausanne&to=Genève
which is the same as
GET http://transport.opendata.ch/v1/connections?from=008501120&to=008501008
Example response
{ "connections" : [ { "from" : { "arrival" : null, "arrivalTimestamp" : null, "departure" : "2012-03-31T08:58:00+02:00", "departureTimestamp" : 1333177080, "platform" : "7", "prognosis" : { "platform" : null, "arrival" : null "departure" : null "capacity1st" : "-1", "capacity2nd" : "-1", }, "station" : { "coordinate" : { "type" : "WGS84", "x" : "6629086", "y" : "46516785" }, "id" : "008501120", "name" : "Lausanne", "score" : null } }, "to" : { "arrival" : "2012-03-31T09:46:00+02:00", "arrivalTimestamp" : 1333179960, "departure" : null, "departureTimestamp" : null, "platform" : "2", "prognosis" : { "platform" : null, "arrival" : null, "departure" : null "capacity1st" : null, "capacity2nd" : null, }, "station" : { "coordinate" : { "type" : "WGS84", "x" : "6142437", "y" : "46210217" }, "id" : "008501008", "name" : "Genève", "score" : null } } }, ], // ... }
/stationboard
Returns the next connections leaving from a specific location.
Resource URL
http://transport.opendata.ch/v1/stationboard
Request Parameters
Name | Required | Description | Example |
---|---|---|---|
station |
required | Specifies the location of which a stationboard should be returned | Aarau |
id |
optional | The id of the station whose stationboard should be returned.
Alternative to the station parameter; one of these two is required. If both an id and a station are specified the id has precedence. |
8503059 (for Zurich Stadelhofen) |
limit |
optional | Number of departing connections to return.
This is not a hard limit - if multiple connections leave at the same time it'll return any connections that leave at the same time as the last connection within the limit. For example: limit=4 will return connections leaving at :
|
15 |
transportations |
optional | Transportation means; one or more of train , tram , ship , bus , cableway |
?transportations[]=tram&transportations[]=bus |
datetime |
optional | Date and time of departing connections, in the format YYYY-MM-DD hh:mm . |
2012-03-25 17:30 |
type |
optional | departure (default) or arrival |
arrival |
Response parameters
Name | Description |
---|---|
station |
The first matched location based on the query. The stationboard will be displayed if this is a station. |
stationboard |
A list of journeys with the stop of the line leaving from that station. |
Example Requests
GET http://transport.opendata.ch/v1/stationboard?station=Aarau&limit=10
which is the same as
GET http://transport.opendata.ch/v1/stationboard?id=008502113&limit=10
Example response
{ "stationboard" : [ { "stop": { "station": { "id": "8502996", "name": "Aarau, Bahnhof", "score": null, "coordinate": { "type" : "WGS84", "x": "8050864", "y": "47392020" } }, "arrival": null, "arrivalTimestamp": null, "departure": "2012-03-31T14:39:00+02:00", "departureTimestamp": 1333197540, "platform": "", "prognosis": { "platform": null, "arrival": null, "departure": null, "capacity1st": "-1", "capacity2nd": "-1" } }, "name": "BUS13543", "category": "BUS", "number": "13543", "operator": null, "to": "Frick, Bahnhof" },{ "stop": { "station": { "id": "8502996", "name": "Aarau, Bahnhof", "score": null, "coordinate": { "type": "WGS84", "x": "8050864", "y": "47392020" } }, "arrival": null, "arrivalTimestamp": null, "departure": "2012-03-31T14:39:00+02:00", "departureTimestamp": 1333197540, "platform": "", "prognosis": { "platform": null, "arrival": null, "departure": null, "capacity1st": "-1", "capacity2nd": "-1" } }, "name": "Bus 2", "category": "Bus", "number": "2", "operator": "BBA", "to": "Aarau Rohr, Unterdorf" }, // ... ] }
API Objects
API responses are composites of the following objects:
Location Object
Name | Description |
---|---|
id |
The id of the location |
type |
Type of the location, can contain:
|
name |
The location name |
score |
The accuracy of the result |
coordinates |
The location coordinates |
distance |
If search has been with coordinates, distance to original point in meters |
Coordinates Object
Name | Description |
---|---|
type |
The type of the given coordinate |
x |
Latitude |
y |
Longitude |
Connection Object
A connection represents a possible journey between two locations.
Name | Description | Example |
---|---|---|
from |
The departure checkpoint of the connection | |
to |
The arrival checkpoint of the connection | |
duration |
Duration of the journey | 00d00:43:00 |
service |
Service information about how regular the connection operates | |
products |
Array with transport products | IR, S9 |
capacity1st |
The maximum estimated occupation load of 1st class coaches | 1 |
capacity2nd |
The maximum estimated occupation load of 2nd class coaches | 2 |
sections |
A list of sections |
Service Object
Operation information for a connection.
Name | Description | Example |
---|---|---|
regular |
Information about how regular a connection operates. | daily |
irregular |
Additional information about irregular operation dates. | not 23., 24. Jun 2012 |
Prognosis Object
A prognosis contains "realtime" informations on the status of a connection checkpoint.
Name | Description | Example |
---|---|---|
platform |
The estimated arrival/departure platform | 8 |
departure |
The departure time prognosis to the checkpoint Date format: ISO 8601 |
2012-03-31T08:58:00+02:00 |
arrival |
The arrival time prognosis to the checkpoint Date format: ISO 8601 |
2012-03-31T09:35:00+02:00 |
capacity1st |
The estimated occupation load of 1st class coaches | 1 |
capacity2nd |
The estimated occupation load of 2nd class coaches | 2 |
Stop Object
A checkpoint represents an arrival or a departure point (in time and space) of a connection.
Name | Description | Example |
---|---|---|
station |
A location object showing this line's stop at the requested station. | |
arrival |
The arrival time to the checkpoint | 14:58:00 |
departure |
The departure time from the checkpoint | null |
delay |
The delay at this checkpoint, can be null if no prognosis is available. | 2 |
platform |
The arrival/departure platform | 8 |
prognosis |
The checkpoint prognosis |
Section Object
A connection consists of one or multiple sections.
Name | Description | Example |
---|---|---|
journey |
A journey, the transportation used by this section. Can be null | |
walk |
Information about walking distance, if available | null |
departure |
The departure checkpoint of the connection | |
arrival |
The arrival checkpoint of the connection |
Journey Object
The actual transportation of a section, e.g. a bus or a train between two stations.
Name | Description | Example |
---|---|---|
name |
The name of the transportation | 019351 |
category |
Category of the transportation | S |
categoryCode |
An internal category code of the transportation | 1 |
number |
The number of the transportation line | 13 |
operator |
The company performing the transportation | 8 |
to |
Final destination of the train | Zürich HB |
passList |
Checkpoints the train passed on the journey | |
capacity1st |
The maximum estimated occupation load of 1st class coaches | 1 |
capacity2nd |
The maximum estimated occupation load of 2nd class coaches | 2 |
Limit response
You can limit the response data with the fields
parameter.
If any fields[]
is passed, only the specified fields are in the response.
The API is aware of the hierarchy, if you set a field, everything below is in the response unless a more specific (further down in the hierarchy) field is set.
Example Request
GET http://transport.opendata.ch/v1/connections?from=Lausanne&to=Genève&fields[]=connections/from/departure&fields[]=connections/to/arrival
Example response
{ "connections":[ { "from":{ "departure":"2012-05-01T19:42:00+0200", }, "to":{ "arrival":"2012-05-01T20:15:00+0200", } }, ], //.... }
Example Request
GET http://transport.opendata.ch/v1/connections?from=Lausanne&to=Genève&fields[]=connections/from&fields[]=connections/to/station
Example response
{ "connections":[ { "from":{ "station":{ "id":"008501120", "name":"Lausanne", "score":null, "coordinate":{ "type":"WGS84", "x":6.629086, "y":46.516785 } }, "arrival":null, "arrivalTimestamp":null, "departure":"2012-05-01T19:42:00+0200", "departureTimestamp":1335894120, "platform":"5", "prognosis":{ "platform":null, "arrival":null, "departure":null, "capacity1st":"1", "capacity2nd":"1" } }, "to":{ "station":{ "id":"008501008", "name":"Gen\u00e8ve", "score":null, "coordinate":{ "type":"WGS84", "x":6.142437, "y":46.210217 } } } }, ], // ... }