Ero sivun ”Journeys API” versioiden välillä

← Vanhempi muutos

Journeys API (näytä wikiteksti)

Versio 4. marraskuuta 2022 kello 14.35

5 409 merkkiä lisätty , 4. marraskuuta 2022 kello 14.35

luokat lisätty

ITdeveloper

approved, botit, byrokraatit, käyttöliittymän ylläpitäjät, ylläpitäjät

209

muokkausta

@@ Rivi 13: / Rivi 13: @@
 ==API Entities==
-The API is built on top of NeTEx entity model (http://user47094.vs.easily.co.uk/netex/), from which the entities in this API are derived. Following picture outlines the entities and their relationships.
+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]]
@@ Rivi 127: / Rivi 127: @@
 <pre>
 api/1/lines
-	- id : String
 	- description : String
@@ Rivi 151: / Rivi 150: @@
 	- lastStopPointId : String
 	- stopPointId : String
+        - gtfsTripId: String
 api/1/stop-points
@@ Rivi 169: / Rivi 169: @@
   	- 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>
+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 ====
@@ Rivi 308: / Rivi 328: @@
      "departureTime" : "00:10:00",
      "arrivalTime" : "00:38:00",
+    "headSign" : "Nokian asema C",
+    "directionId" : "1",
+    "wheelchairAccessible": false,
+    "gtfs" : {
+       "tripId": "4740073787Y"
+    },
      "dayTypes" : [ "monday" ],
      "dayTypeExceptions" : [ {
@@ Rivi 373: / Rivi 399: @@
      "originStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1592",
      "destinationStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8524",
+    "direction" : "0",
      "name" : "Kalkku - Nokian asema C",
      "stopPoints" : [ {
@@ Rivi 415: / Rivi 442: @@
        "departureTime" : "06:10:00",
        "arrivalTime" : "06:21:00",
+      "headSign" : "Nokian asema C",
        "dayTypes" : [ "friday" ],
        "dayTypeExceptions" : [ {
@@ Rivi 426: / Rivi 454: @@
        "departureTime" : "06:10:00",
        "arrivalTime" : "06:21:00",
+      "headSign" : "Nokian asema C",
        "dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ],
        "dayTypeExceptions" : [ {
@@ Rivi 450: / Rivi 479: @@
      "name" : "Keskustori M",
      "shortName" : "0001",
-     "tariffZone" : "1",
+     "tariffZone" : "A",
      "municipality" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
@@ Rivi 463: / 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.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=1 will return list of all STOP POINTS within Tariff Zone 1.
+* 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 =====
-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
-* "1" for Tariff Zone 1
-* "2" for Tariff Zone 2
-* "3" for Tariff Zone 3
-* "S" for Tariff Zone S ("Seutuliikenne", regional transport)
-Please see http://joukkoliikenne.tampere.fi/fi/muutokset-tampereen-seudun-joukkoliikenteessa-30.6.2014/tariffijarjestelma-ja-vyohykejako.html (in finnish) for more details on tariff zones.
+Please see https://www.nysse.fi/en/tickets-and-fares/zones.html for more details on tariff zones.
 ==== Municipalities ====
@@ Rivi 514: / Rivi 539: @@
        "originShortName" : "3615",
        "destinationShortName" : "1028",
+      "speed" : "10.0",
        "originAimedDepartureTime" : "2240",
        "onwardCalls" : [ {
@@ Rivi 557: / Rivi 583: @@
 * originShortName specifies the number of the stop where the vehicle started
 * 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
 * bearing specifies the direction the vehicle is travelling
@@ Rivi 572: / Rivi 599: @@
 ** on journey which started from stop 0001
 ** 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>
+{
+: [
+    {
+      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]]