209
muokkausta
(luokat lisätty) |
|||
(33 välissä olevaa versiota 2 käyttäjän tekeminä ei näytetä) | |||
Rivi 13: | Rivi 13: | ||
==API Entities== | ==API Entities== | ||
The API is built on top of NeTEx entity model | The API is built on top of NeTEx entity model, from which the entities in this API are derived. Following picture outlines the entities and their relationships. | ||
[[File:API_Entities_1.1.png|none]] | [[File:API_Entities_1.1.png|none]] | ||
In the picture above, entities are drawn with purple color. Boxes with blue color are properties of the entities, but drawn out to explain the concepts. Lines in the picture represent UML-styled relations. | In the picture above, entities are drawn with purple color. Boxes with blue color are properties of the entities, but drawn out to explain the concepts. Lines in the picture represent UML-styled relations. Diamond (either filled or empty) indicates ownership, in other words: the entity which has a diamond attached to it is considered a parent and owns the entity at the other end of the line, which is considered a child. Lines with filled diamond represent composite relationship indicating that the child cannot exist without its parent, empty diamond indicates aggregate relationship where the child can exist without the parent. Numbers at the end of lines are multiplicity rules, which tell how many entities or properties are included in the relation. If number is not present at the end of a line, it is assumed that number one would exist at the end of that line. For example: a JOURNEY PATTERN cannot exist without a ROUTE (and ROUTE owns the JOURNEY PATTERN), but a STOP POINT can exist without JOURNEY PATTERN although JOURNEY PATTERN owns the STOP POINT. A ROUTE can own multiple JOURNEY PATTERNs, however each JOURNEY PATTERN must be owned by single ROUTE. JOURNEY PATTERN on the other hand can have two or more STOP POINTS (at minimum the start and stop points of the pattern), and one STOP POINT can be present on many JOURNEY PATTERNS. | ||
===Routes=== | ===Routes=== | ||
ROUTE entity describes a path through (a road or a rail) network, which is used by a public transport service (such as bus or a tram). ROUTE has typically one or more projections. Projection is a way to describe a ROUTE on selected canvas. For example a route could be presented on a map by drawing it as a line on it. Another way would be project a ROUTE for example to OpenStreetMap by using OpenStreetMap roads to present the ROUTE. Journeys API currently supports only projecting the ROUTE as coordinate shape. Following picture is taken from Tampere "reittikartta" and outlines a ROUTE through Tampere. [[File:Journ_Line_2.png|400px|none]] | ROUTE entity describes a path through (a road or a rail) network, which is used by a public transport service (such as bus or a tram). ROUTE has typically one or more projections. Projection is a way to describe a ROUTE on selected canvas. For example a route could be presented on a map by drawing it as a line on it. Another way would be project a ROUTE for example to OpenStreetMap by using OpenStreetMap roads to present the ROUTE. Journeys API currently supports only projecting the ROUTE as coordinate shape. Following picture is taken from Tampere "reittikartta" and outlines a ROUTE through Tampere. [[File:Journ_Line_2.png|400px|none]] | ||
Rivi 25: | Rivi 26: | ||
===Journey, Journey Pattern, DayType, DayTypeException and StopPoint=== | ===Journey, Journey Pattern, DayType, DayTypeException and StopPoint=== | ||
JOURNEY describes public transport vehicle's run on a given ROUTE through the city. Typically the run occurs at the same time on multiple days during a week. For example a certain JOURNEY on given ROUTE could start 10:00 AM on Mondays, Tuesdays, Wednesdays, Thursdays and Fridays. DAY TYPE, attached to a JOURNEY, classifies the conditions on which kind of days the JOURNEY occurs. Conditions can be week day names, but other kind of conditions can apply too (such as "busy day" or "all weekdays"). DAY TYPE EXCEPTION provides mechanism to temporarily deviate from conditions imposed by a DAY TYPE. For example if a JOURNEY would occur on all weekdays, public holidays could be modeled as DAY TYPE EXCEPTIONS. In other words we could say "This JOURNEY runs on every week day except 21.5.2014, because | JOURNEY describes public transport vehicle's run on a given ROUTE through the city. Typically the run occurs at the same time on multiple days during a week. For example a certain JOURNEY on given ROUTE could start 10:00 AM on Mondays, Tuesdays, Wednesdays, Thursdays and Fridays. DAY TYPE, attached to a JOURNEY, classifies the conditions on which kind of days the JOURNEY occurs. Conditions can be week day names, but other kind of conditions can apply too (such as "busy day" or "all weekdays"). DAY TYPE EXCEPTION provides mechanism to temporarily deviate from conditions imposed by a DAY TYPE. For example if a JOURNEY would occur on all weekdays, public holidays could be modeled as DAY TYPE EXCEPTIONS. In other words we could say "This JOURNEY runs on every week day except 21.5.2014, because that day is Labor Day". | ||
<br><br> | <br><br> | ||
On a given time on a given DAY TYPE or a given ROUTE, the JOURNEY stops on certain STOP POINTS from where passengers can board or alight the vehicle. A CALL groups together the STOP POINT where the vehicle stops, and the time when the vehicle stops on that STOP POINT. Since the vehicle stops multiple times during a JOURNEY, a CALL also contains the order of the stop. CALLs on a certain JOURNEY follow a JOURNEY PATTERN. JOURNEY PATTERN is in essence a sequence of STOP POINTS on which the JOURNEY stops. In other words: ROUTE describes the vehicle's path through road network, and a JOURNEY PATTERN "overlays" it with a sequence of STOP POINTs. Consider a ROUTE as continuous drawn line and STOP POINTs as drawn circles on top of the line. STOP POINTs must follow the drawn line since those have to be on the vehicle's route. Single ROUTE can, however, have multiple JOURNEY PATTERNs: for example one for express line (which skips some of the stops) and one for the normal line which stops on every STOP POINT. | On a given time on a given DAY TYPE or a given ROUTE, the JOURNEY stops on certain STOP POINTS from where passengers can board or alight the vehicle. A CALL groups together the STOP POINT where the vehicle stops, and the time when the vehicle stops on that STOP POINT. Since the vehicle stops multiple times during a JOURNEY, a CALL also contains the order of the stop. CALLs on a certain JOURNEY follow a JOURNEY PATTERN. JOURNEY PATTERN is in essence a ordered sequence of STOP POINTS on which the JOURNEY stops. In other words: ROUTE describes the vehicle's path through road network, and a JOURNEY PATTERN "overlays" it with a sequence of STOP POINTs. Consider a ROUTE as continuous drawn line and STOP POINTs as drawn circles on top of the line. STOP POINTs must follow the drawn line since those have to be on the vehicle's route. Single ROUTE can, however, have multiple JOURNEY PATTERNs: for example one for express line (which skips some of the stops) and one for the normal line which stops on every STOP POINT. | ||
==Queries and Responses== | ==Queries and Responses== | ||
Rivi 126: | Rivi 127: | ||
<pre> | <pre> | ||
api/1/lines | api/1/lines | ||
- description : String | - description : String | ||
Rivi 150: | Rivi 150: | ||
- lastStopPointId : String | - lastStopPointId : String | ||
- stopPointId : String | - stopPointId : String | ||
- gtfsTripId: String | |||
api/1/stop-points | api/1/stop-points | ||
Rivi 163: | Rivi 164: | ||
api/1/vehicle-activity | api/1/vehicle-activity | ||
- lineRef: String | - lineRef: String or comma separated list of strings with * as wildcard, for example: lineRef=3 or lineRef=3,1* | ||
- vehicleRef: String | - vehicleRef: String or comma separated list of strings with * as wildcard (see lineRef) | ||
- journeyRef: String | - journeyRef: String or comma separated list of strings with * as wildcard (see lineRef) | ||
- directionRef: String, choice of 1 or 2 | |||
</pre> | |||
==== Field Exclusion ==== | |||
Journeys API allows exclusion of returned fields depending on the end point. Below are list of end points which allow field exclusion. | |||
<pre> | |||
api/1/journey-patterns | |||
- exclusions: stopPoints, journeys | |||
api/1/journeys | |||
- exclusions: calls | |||
api/1/routes | |||
- exclusions: journeyPatterns, journeys, geographicCoordinateProjection | |||
</pre> | </pre> | ||
For each end point a single or multiple exclusion can be used. Multiple exclusions are separated by comma. For example a client might call: | |||
* http://data.itsfactory.fi/journeys/api/1/routes?exclude-fields=journeys | |||
* http://data.itsfactory.fi/journeys/api/1/routes?exclude-fields=journeys,journeyPatterns | |||
* http://data.itsfactory.fi/journeys/api/1/routes?exclude-fields=journeys,journeyPatterns,geographicCoordinateProjection | |||
Also the vehicle-activity end point support field exclusion, please see that section for details on field exclusion on vehicle-activity end point | |||
==== About IDs ==== | ==== About IDs ==== | ||
Each entity in Journeys API has an id (the url field ends to it), for example in line id " | Each entity in Journeys API has an id (the url field ends to it), for example in line id "Y4" in url | ||
<pre> | <pre> | ||
Rivi 306: | Rivi 328: | ||
"departureTime" : "00:10:00", | "departureTime" : "00:10:00", | ||
"arrivalTime" : "00:38:00", | "arrivalTime" : "00:38:00", | ||
"headSign" : "Nokian asema C", | |||
"directionId" : "1", | |||
"wheelchairAccessible": false, | |||
"gtfs" : { | |||
"tripId": "4740073787Y" | |||
}, | |||
"dayTypes" : [ "monday" ], | "dayTypes" : [ "monday" ], | ||
"dayTypeExceptions" : [ { | "dayTypeExceptions" : [ { | ||
Rivi 321: | Rivi 349: | ||
"shortName" : "0002", | "shortName" : "0002", | ||
"tariffZone" : "1", | "tariffZone" : "1", | ||
" | "municipality" : { | ||
"url" : "http://data.itsfactory.fi/journeys/api/1/ | "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837", | ||
"shortName" : "837", | "shortName" : "837", | ||
"name" : "Tampere" | "name" : "Tampere" | ||
Rivi 336: | Rivi 364: | ||
"shortName" : "0500", | "shortName" : "0500", | ||
"tariffZone" : "1", | "tariffZone" : "1", | ||
" | "municipality" : { | ||
"url" : "http://data.itsfactory.fi/journeys/api/1/ | "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837", | ||
"shortName" : "837", | "shortName" : "837", | ||
"name" : "Tampere" | "name" : "Tampere" | ||
Rivi 371: | Rivi 399: | ||
"originStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1592", | "originStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1592", | ||
"destinationStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8524", | "destinationStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8524", | ||
"direction" : "0", | |||
"name" : "Kalkku - Nokian asema C", | "name" : "Kalkku - Nokian asema C", | ||
"stopPoints" : [ { | "stopPoints" : [ { | ||
Rivi 378: | Rivi 407: | ||
"shortName" : "1592", | "shortName" : "1592", | ||
"tariffZone" : "1", | "tariffZone" : "1", | ||
" | "municipality" : { | ||
"url" : "http://data.itsfactory.fi/journeys/api/1/ | "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837", | ||
"shortName" : "837", | "shortName" : "837", | ||
"name" : "Tampere" | "name" : "Tampere" | ||
Rivi 389: | Rivi 418: | ||
"shortName" : "8549", | "shortName" : "8549", | ||
"tariffZone" : "2", | "tariffZone" : "2", | ||
" | "municipality" : { | ||
"url" : "http://data.itsfactory.fi/journeys/api/1/ | "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/536", | ||
"shortName" : "536", | "shortName" : "536", | ||
"name" : "Nokia" | "name" : "Nokia" | ||
Rivi 400: | Rivi 429: | ||
"shortName" : "8547", | "shortName" : "8547", | ||
"tariffZone" : "2", | "tariffZone" : "2", | ||
" | "municipality" : { | ||
"url" : "http://data.itsfactory.fi/journeys/api/1/ | "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/536", | ||
"shortName" : "536", | "shortName" : "536", | ||
"name" : "Nokia" | "name" : "Nokia" | ||
Rivi 413: | Rivi 442: | ||
"departureTime" : "06:10:00", | "departureTime" : "06:10:00", | ||
"arrivalTime" : "06:21:00", | "arrivalTime" : "06:21:00", | ||
"headSign" : "Nokian asema C", | |||
"dayTypes" : [ "friday" ], | "dayTypes" : [ "friday" ], | ||
"dayTypeExceptions" : [ { | "dayTypeExceptions" : [ { | ||
Rivi 424: | Rivi 454: | ||
"departureTime" : "06:10:00", | "departureTime" : "06:10:00", | ||
"arrivalTime" : "06:21:00", | "arrivalTime" : "06:21:00", | ||
"headSign" : "Nokian asema C", | |||
"dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ], | "dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ], | ||
"dayTypeExceptions" : [ { | "dayTypeExceptions" : [ { | ||
Rivi 448: | Rivi 479: | ||
"name" : "Keskustori M", | "name" : "Keskustori M", | ||
"shortName" : "0001", | "shortName" : "0001", | ||
"tariffZone" : " | "tariffZone" : "A", | ||
" | "municipality" : { | ||
"url" : "http://data.itsfactory.fi/journeys/api/1/ | "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837", | ||
"shortName" : "837", | "shortName" : "837", | ||
"name" : "Tampere" | "name" : "Tampere" | ||
Rivi 461: | Rivi 492: | ||
* http://data.itsfactory.fi/journeys/api/1/stop-points?location=61.69978,23.89121 will return STOP POINTS that reside at given coordinates | * http://data.itsfactory.fi/journeys/api/1/stop-points?location=61.69978,23.89121 will return STOP POINTS that reside at given coordinates | ||
* http://data.itsfactory.fi/journeys/api/1/stop-points?location=61.49978,23.69121:61.79978,23.99121 will return STOP POINTS that start within given coordinate box. Format: (upper left corner of the box):(lower right corner of the box) | * http://data.itsfactory.fi/journeys/api/1/stop-points?location=61.49978,23.69121:61.79978,23.99121 will return STOP POINTS that start within given coordinate box. Format: (upper left corner of the box):(lower right corner of the box) | ||
* http://data.itsfactory.fi/journeys/api/1/stop-points?tariffZone= | * http://data.itsfactory.fi/journeys/api/1/stop-points?tariffZone=A will return list of all STOP POINTS within Tariff Zone A | ||
===== About Tariff Zones ===== | ===== About Tariff Zones ===== | ||
Journeys API returns tariff zones as tariff zone ids defined by City of Tampere. Valid tariff zone ids are: | Journeys API returns tariff zones as tariff zone ids defined by City of Tampere. Valid tariff zone ids are: A,B,C,D,E,F and G | ||
Please see | Please see https://www.nysse.fi/en/tickets-and-fares/zones.html for more details on tariff zones. | ||
==== | ==== Municipalities ==== | ||
A client can access specific | A client can access specific municipalities details by issuing request at http://data.itsfactory.fi/journeys/api/1/municipalities/837 | ||
This request would produce following response: | This request would produce following response: | ||
<pre> | <pre> | ||
{ | { | ||
"url": "http://data.itsfactory.fi/journeys/api/1/ | "url": "http://data.itsfactory.fi/journeys/api/1/municipalities/837", | ||
"shortName": "837", | "shortName": "837", | ||
"name": "Tampere" | "name": "Tampere" | ||
Rivi 512: | Rivi 539: | ||
"originShortName" : "3615", | "originShortName" : "3615", | ||
"destinationShortName" : "1028", | "destinationShortName" : "1028", | ||
"speed" : "10.0", | |||
"originAimedDepartureTime" : "2240", | "originAimedDepartureTime" : "2240", | ||
"onwardCalls" : [ { | "onwardCalls" : [ { | ||
Rivi 555: | Rivi 583: | ||
* originShortName specifies the number of the stop where the vehicle started | * originShortName specifies the number of the stop where the vehicle started | ||
* destinationShortName specifies the number of the stop where the bus is heading to | * destinationShortName specifies the number of the stop where the bus is heading to | ||
* speed indicates the vehicle current speed in km/h | |||
* latitude and longitude specifies the map position of the vehicle at the time of the observation | * latitude and longitude specifies the map position of the vehicle at the time of the observation | ||
* bearing specifies the direction the vehicle is travelling | * bearing specifies the direction the vehicle is travelling | ||
Rivi 564: | Rivi 593: | ||
* lineRef, which filters away everything except activity on given line | * lineRef, which filters away everything except activity on given line | ||
* vehicleRef, which filters away everything except activity on given vehicle | * vehicleRef, which filters away everything except activity on given vehicle | ||
* directionRef, which filters away everything except activity towards given direction | |||
* journeyRef, which filters away everything except activity on given journey. Takes form: [lineId]_[start time as HHmm]_[last stop id]_[first stop id], for example journeyRef=2_2230_0001_1234 would obtain activity | * journeyRef, which filters away everything except activity on given journey. Takes form: [lineId]_[start time as HHmm]_[last stop id]_[first stop id], for example journeyRef=2_2230_0001_1234 would obtain activity | ||
* on line 2 | ** on line 2 | ||
* on journey which started today at 22:30 | ** on journey which started today at 22:30 | ||
* on journey which started from stop 0001 | ** on journey which started from stop 0001 | ||
* on journey which ends to stop 1234 | ** on journey which ends to stop 1234 | ||
The client can also filter certain fields from the response. Filtering is based on exclude-fields url parameter. Filtered field names are nested. Client can specify multiple filtered fields as comma-separated list. For example to filter out recordedAtTime and onwardCalls elements, the client would make following request | |||
http://data.itsfactory.fi/journeys/api/1/vehicle-activity?exclude-fields=monitoredVehicleJourney.onwardCalls,recordedAtTime | |||
==Stop Monitoring== | |||
Journeys API allows clients to access real-time location of vehicles moving through the street network from stop point perspective. To do this, client would make a HTTP GET request to url | |||
<br><br> | |||
http://data.itsfactory.fi/journeys/api/1/stop-monitoring?stops=0001,0002 | |||
<br><br> | |||
where stops argument contains a list of stop short names for which to fetch the data. NOTE: you can specify at maximum 100 stop short names into single request | |||
The call would result in a following response: | |||
<pre> | |||
{ | |||
1001: [ | |||
{ | |||
lineRef: "3R", | |||
directionRef: "2", | |||
vehicleLocation: { | |||
longitude: "23.7337863", | |||
latitude: "61.5007787" | |||
}, | |||
operatorRef: "TKL", | |||
bearing: "70", | |||
delay: "-P0Y0M0DT0H1M18.000S", | |||
vehicleRef: "TKL_41", | |||
journeyPatternRef: "3R", | |||
originShortName: "1028", | |||
destinationShortName: "0002", | |||
originAimedDepartureTime: "2016-04-23T02:35:00+03:00", | |||
call: { | |||
vehicleAtStop: false, | |||
expectedArrivalTime: "2016-04-23T02:53:00+03:00", | |||
expectedDepartureTime: "2016-04-23T02:53:00+03:00", | |||
aimedArrivalTime: "2016-04-23T02:55:00+03:00", | |||
aimedDepartureTime: "2016-04-23T02:55:00+03:00", | |||
departureStatus: "onTime", | |||
arrivalStatus: "onTime", | |||
visitNumber: "24", | |||
vehicleLocationAtStop: { | |||
longitude: "23.7337863", | |||
latitude: "61.5007787" | |||
} | |||
} | |||
} | |||
] | |||
} | |||
... | |||
</pre> | |||
The response contains a list of elements (grouped by requested stop short names) described above. Following fields are present: | |||
* lineRef specifies the line where the bus is currently operating. | |||
* directionRef sepecifies the direction the bus is travelling on the line. 1 = from origin stop to destination stop, 2= from destination stop back to origin stop. | |||
* originAimedDepartureTime specifies which time the vehicle departed from the origin stop | |||
* latitude and longitude specifies the map position of the vehicle at the time of the observation | |||
* originShortName specifies the number of the stop where the vehicle started | |||
* destinationShortName specifies the number of the stop where the bus is heading to | |||
* bearing specifies the direction the vehicle is travelling | |||
* delay specifies the relative time the vehicle is behind or ahead of its planned schedule | |||
* vehicleRef uniquely identifies the monitored vehicle | |||
* call element tells when the journey is expected to reach the requested stop, as well as its departure estimation | |||
The response data changes once in a minute, so clients are not recommended to poll the interface very often. | |||
==GTFS Zip files== | |||
Journeys API provides public transport data in form of GTFS ZIP files. These files are meant for purposes where offline usage of public transport data is required. Please see https://developers.google.com/transit/gtfs/reference for more details on GTFS. | |||
Zip files are available at: http://data.itsfactory.fi/journeys/files/gtfs/ | |||
Journeys API provides two zip files: | |||
* gtfs_tampere.zip is a file which adheres strictly to GTFS format. This file however does not include all information available via Journeys API GTFS Zip files. Use this file when you need to be fully compatible with GTFS | |||
* extended_gtfs_tampere.zip is a file which extends standard GTFS Zip file with information about tariff zones and municipalities. Use this file when you need the extra info and when you do not need to be fully compatible with GTFS. Please note however, that extended GTFS Zip file is not in conflict with GTFS specification, but extends it. So in most cases you should be able to use it. | |||
==Support / Community== | |||
You can contact us via email: dev-support@itsfactory.fi | |||
You can also visit Journeys API Facebook page at https://www.facebook.com/journeysapi, where we update news and other noteworthy issues and you can ask questions as well. | |||
[[Luokka:Api]] | |||
[[Luokka:Public Transport APIs]] | |||
[[Luokka:Tampere APIs]] |