Ero sivun ”Journeys API” versioiden välillä

ITS Factory Developer Wikistä
(luokat lisätty)
 
(193 välissä olevaa versiota 2 käyttäjän tekeminä ei näytetä)
Rivi 1: Rivi 1:
This is a workspace for Journeys API which allows developers and clients to access public transport lines, routes, stops and schedules. All material on this page are draft material and subject to significant change.
==Concept==
==Concept==
Journeys API allows developers and clients to access following information via REST API
Journeys API allows developers and clients to access Public Transport information via REST API
* '''Routes''' on which public transport services operate
* '''Routes''' on which public transport services operate
* '''Lines''', or in other words grouping of routes. For example Line 2, which runs from Rauhaniemi to Pyyninkintori in Tampere
* '''Lines''', or in other words grouping of routes. For example Line 2, which runs from Rauhaniemi to Pyyninkintori in Tampere
* '''Journeys''' made by public transport vehicles on certain line and route at certain day and time
* '''Journeys''' made by public transport vehicles on certain line and route at certain day and time
* '''Stops''' where public transport vehicles stop during their journeys
* '''Stops''' where public transport vehicles stop during their journeys
* '''Vehicle Monitoring''' where public transport vehicles stop during their journeys
The API allows accessing these concepts as hierarchy of objects (see later) as well as performing searches.
The API allows accessing these concepts as hierarchy of objects (see later) as well as performing searches.
Journeys API combines together various data sources and offers their contents to developers and clients via JSON requests made over HTTP. Static data (ie. lines, routes, stops and time schedules) comes from GTFS (https://developers.google.com/transit/gtfs/) files. This data is augmented with proprietary MALA format (tariff zones, municipalities). Real-time data (observations on where public transport vehicles are currently operating) are polled from siri.ij2010.tampere.fi SIRI VM endpoint once in a second. This data includes for example real-time coordinate updates for public transport vehicles.
[[File:Journeys_API_Network.png]]


==API Entities==
==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]]
 
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.


[[File:Journeys_API_Entities.png|none]]
===Routes===
===Route, Route Link and Route Point===
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). A ROUTE is made up of a sequence of ROUTE LINKS which split the route into "pieces". Each ROUTE LINK starts and stops on ROUTE POINTS which typically map to a certain place in city infrastructure (a road junction, stopping place or a point of interest). All ROUTE LINKS laid out into a sequence form up the ROUTE (the start ROUTE POINT of the first ROUTE LINK is the start of the ROUTE and the end ROUTE POINT of the last ROUTE LINK is the ending point of the ROUTE). Following picture is taken from Tampere "reittikartta" and outlines a ROUTE through Tampere. [[File:Journ_Line_2.png|400px|none]]


===Line===
===Line===
LINE entity is a grouping of ROUTES that is generally known to the public with a common name, such as "Line 2". ROUTES on the same LINE usually follow similar ROUTEs.
LINE entity is a grouping of ROUTES that is generally known to the public with a common name, such as "Line 2". ROUTES on the same LINE usually follow similar ROUTEs.


===Journey, Call, 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 this day is Labor Day".  
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.
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==
=== REST styled API ===
=== REST styled API ===
Journeys API follows RESTful design pattern. This means that all entities returned by the API have an unique URL via which the entity can be accessed at all times. The returned entities refer to each other via these URLs, and each entity URL is always included in the entity itself as "href" property. Following is a fragment from JOURNEY entity response:
Journeys API follows RESTful design pattern. This means that all entities returned by the API have an unique URL via which the entity can be accessed at all times. The returned entities refer to each other via these URLs, and each entity URL is always included in the entity itself as "href" property. Following is a fragment from STOP POINT entity response:
<pre>
<pre>
...
...
    "data" : {
"body" : [
        "href" : "http://example.com/journeys/api/journeys/111",
    {
        "departureTime" : "08:00:00+0300",
    "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0001",
        "dayTypes" : [
    "location" : "61.49751,23.76151",
            {
    "name" : "Keskustori M",
                "href" : "http://example.com/journeys/api/day-types/weekdays"
    "shortName" : "0001",
            }
    "tariffZone" : "1",
        ],
    "muncipality" : {
        "dayTypeExceptions" : [
      "url" : "http://data.itsfactory.fi/journeys/api/1/muncipalities/837",
            {
      "shortName" : "837",
                "href" : "http://example.com/journeys/api/day-type-exceptions/111",
      "name" : "Tampere"
                "date" : "2014-05-05",
    }
                "runs" : "no"
  }
            }
]
        ],
        "calls" : [
            {
                "href" : "http://example.com/journeys/api/calls/1123",
                "arrival" : "08:00:00+0300",
                "departure" : "08:00:00+0300",
                "stopPoint" : {
                    "href" : "http://example.com/journeys/api/stop-points/222"
                }
            }
...
...
</pre>
</pre>
The JOURNEY itself has a href property (http://example.com/journeys/api/journeys/111) which points to the JOURNEY entity itself. A client can use this URL access this entity at any time. The dayType entity has also an href property which tells the client how to access the DAY TYPE data. Whenever a client encounters a href property in the response, the client should make a HTTP GET request to that url in order to access the entity data. The client the can "attach" the returned data to the original response. Depending on the request, the Journeys API might "expand" a entity in a response. For example, a DAY TYPE EXCEPTION element in the response above contains '''both''' href property as well as "date" and "runs" properties. This means that the client does not need to make a request to the href URL in order to access the entity data. Instead, the Journeys API has already included the full data of the entity into the request.
The STOP POINT itself has a url property which points to the STOP POINT entity itself. A client can use this URL access this entity at any time. Nested objects may also include urls as in case of muncipality inside the stopPoint.
<br><br>
There are no rules when the Journeys API will expand an element (even though typically first level children of an element are typically expanded). Therefore, the client must follow these rules '''at all times'''.
 
* If any entity (including nested child entities) contains href property, and no other properties, the client needs to make a HTTP GET request to the URL the href property specifies
* If any entity (including nested child entities) contains href property, and other properties, the client should not make a HTTP GET request, since Journeys API has already expanded the entity (and all its child entities) in the response. The expanded entity can however contain child entities which have only href property present; in this case, the client is expected to make HTTP GET request for that child entity.


=== API-Wide URL parameters ===
=== API-Wide URL parameters ===
==== Time ====
==== Indent ====
All Journeys API calls relate to certain time (in present, future or past). Journeys API elements are versioned over time, in other words changes in the entities are recorded with time stamps. By issuing requestTime parameter, the client can define the time from which the client wish to see the entities. For example: lets assume that a first version of time tables, lines and journeys is made 1.1.2013 (for winter schedules) and 1.6.2013 new version (for summer schedules is added). Each version would have different entities (lines, journeys etc...) since winter schedules would differ from summer schedules. Now, by issuing
Indent formats the server response to more human readable format.
<pre>
http://example.com/journeys/lines/?requestTime=2013-01-10
</pre>
request the Journeys API would return entities from the winter schedule. Respectively, a request to url
<pre>
<pre>
http://example.com/journeys/lines/?requestTime=2013-06-10
http://data.itsfactory.fi/journeys/api/1/lines?indent=yes
</pre>
</pre>
would return entities from the summer schedule. <br>
<br>
The requestTime parameter can be omitted, in this case requestTime is considered to be the time when the client made the request.


=== Response structure ===
=== Response structure ===
Rivi 80: Rivi 64:
<pre>
<pre>
{
{
     "headers" : {
     "status" : "success",
         "dataValidityPeriod" : {
    "data" : {
             "validFrom" : "2013-01-01",
         "headers" : {
            "validTo" : "2013-05-31"
             "paging" : {
                "startIndex" : 0,
                "pageSize" : 1,
                "moreData" : false
            }
         },
         },
         "startIndex" : 0,
         "body": [
        "pageSize" : 10,
            ...
        "moreData" : false
        ]
 
    },
    "data" : {
      ...
     }
     }
}
}
</pre>
</pre>


The response has headers and data elements. Headers contain metadata-like information about the response. For example dataValidityPeriod tells the time span during which response data is valid. This would reflect the winter and summer example introduced previously. Data element contains the actual response data, and its content varies depending on the request made by the client. StartIndex tells the index of the first returned element, pageSize tells how many items were returned and moreData tells if the client should make another request to fetch the additional data. This approach is called "paging". The client can specify startIndex parameter to the request URL to specify the starting index of an entity list, for example:
The response has headers and data elements. Data element contains the actual response data, and its content varies depending on the request made by the client. Headers contain metadata-like information about the response. startIndex tells the index of the first returned element, pageSize tells how many items were returned and moreData tells if the client should make another request to fetch the additional data. This approach is called "paging". The client can specify startIndex parameter to the request URL to specify the starting index of an entity list, for example:


<pre>
<pre>
http://example.com/journeys/api/lines?startIndex=10
http://data.itsfactory.fi/journeys/api/1/lines?startIndex=10
</pre>
</pre>


If omitted, the Journeys API assumes startIndex to be zero.
If omitted, the Journeys API assumes startIndex to be zero.
In case of a malformed request, such as wrongly formatted coordinate strings, server responds with a fail message:
<pre>
{
  "status" : "fail",
  "data" : {
    "title" : "Coordinates",
    "message" : "Illegal format: must be latitude,longitude"
  }
}
</pre>
In internal server error cases, server responds with similar response, except the status is "error":
<pre>
{
  "status" : "error",
  "data" : {
    "message" : "Guru Meditation"
  }
}
</pre>


=== Entity Queries ===
=== Entity Queries ===
==== About Query Parameters ====
Journeys API allows the client user URL parameters in queries. You can find out valid query parameters for each entity on this page. A client can issue none or all query parameters in a query. For example a client could query:
<pre>
http://data.itsfactory.fi/journeys/api/1/lines
</pre>
or
<pre>
http://data.itsfactory.fi/journeys/api/1/lines?name=13&description=hermia
</pre>
by using multiple query parameters.
==== Query Parameter Reference ====
Below you can find allowed query parameters by Journeys API url.
<pre>
api/1/lines
- description : String
api/1/routes
- lineId : String
- name : String
api/1/journey-patterns
- lineId : String
- name : String
- firstStopPointId : String
- lastStopPointId : String
- stopPointId : String
api/1/journeys
- lineId : String
- routeId : String
- journeyPatternId : String
- dayTypes : comma separated list of: monday, tuesday, wednesday, friday, saturday, sunday
- departureTime : hh:mm
- arrivalTime : hh:mm
- firstStopPointId : String
- lastStopPointId : String
- stopPointId : String
        - gtfsTripId: String
api/1/stop-points
- name: String
- location: lat,lon or lat1,lon1:lat2,lon2 (upper left corner of a box : lower right corner of a box)
- tariffZone : one of: 1,2,3,S (http://joukkoliikenne.tampere.fi/fi/muutokset-tampereen-seudun-joukkoliikenteessa-30.6.2014/tariffijarjestelma-ja-vyohykejako.html)
- municipalityName: String
- municipalityShortName: String
api/1/municipalities
- name: String
- shortName: String
api/1/vehicle-activity
- lineRef: String or comma separated list of strings with * as wildcard, for example: lineRef=3 or lineRef=3,1*
- vehicleRef: String or comma separated list of strings with * as wildcard (see lineRef)
- 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>
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 ====
Each entity in Journeys API has an id (the url field ends to it), for example in line id "Y4" in url
<pre>
http://data.itsfactory.fi/journeys/api/1/lines/Y4
</pre>
* LINE ids relate to "known" line names by the scheduling, for example line Y4 has id Y4. This id is unlikely to change.
* STOP POINT ids relate to "known" stop point numbers by the scheduling, for example stop point Keskustori M has number 0001 which is also the id of the stop point. This id is unlikely to change.
ROUTEs, JOURNEYs, MUNCIPALITIES and JOURNEY PATTERNs have ids which are likely change over time. These ids should be stored in the client only for short periods of time.
==== Lines ====
==== Lines ====
A client can access specific LINE'S details by issuing request at http://example.com/journeys/api/lines/123
A client can access specific LINE'S details by issuing request at http://data.itsfactory.fi/journeys/api/1/lines/13


This request would produce following response:
This request would produce following response:
<pre>
<pre>
{
{
     "headers" : {
     "status" : "success",
         "dataValidityPeriod" : {
    "data" : {
             "validFrom" : "2013-01-01",
         "headers" : {
            "validTo" : "2013-05-31"
             "paging" : {
                "startIndex" : 0,
                "pageSize" : 1,
                "moreData" : false
            }
         },
         },
         "startIndex" : 0,
         "body": [
        "pageSize" : 1,
        "moreData" : false
    },
    "data" : {
        "lines":[
             {
             {
                 "href" : "http://example.com/journeys/api/lines/123",
                 "href" : "http://data.itsfactory.fi/journeys/api/1/lines/123",
                 "name" : "13",
                 "name" : "13",
                 "description" : "Hermia - Lukonmäki - Keskustori - Tesoma - Lamminpää - Ylöjärvi"
                 "description" : "Hermia - Lukonmäki - Keskustori - Tesoma - Lamminpää - Ylöjärvi"
Rivi 132: Rivi 228:
</pre>
</pre>


A client can search LINES by issuing following requests:<br>
A client can search LINES by issuing for example following requests:<br>
* http://example.com/journeys/api/lines will return paged list of all LINES  
* http://data.itsfactory.fi/journeys/api/1/lines will return paged list of all LINES  
* http://example.com/journeys/api/lines?lineName=13 will return LINES which name contains text "13" (case-insensitive)
* http://data.itsfactory.fi/journeys/api/1/lines?name=13 will return LINES which name contains text "13" (case-insensitive)
* http://example.com/journeys/api/lines?lineDescription=Hermia will return LINES which description contains text "Hermia" (case-insensitive)
* http://data.itsfactory.fi/journeys/api/1/lines?description=Hermia will return LINES which description contains text "Hermia" (case-insensitive)
* http://example.com/journeys/api/lines?containsRoute=123 returns LINE that operates on given ROUTE
 
==== Routes ====
A client can access specific ROUTE'S details by issuing request at http://data.itsfactory.fi/journeys/api/1/routes/288
 
This request would produce following response:
<pre>
{
    "url" : "http://data.itsfactory.fi/journeys/api/1/routes/288",
    "lineUrl" : "http://data.itsfactory.fi/journeys/api/1/lines/50",
    "name" : "Lempäälä - Koskipuisto H",
    "journeyPatterns" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/507",
      "originStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/7559",
      "destinationStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0517",
      "name" : "Lempäälä - Koskipuisto H"
    } ],
    "journeys" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/8726",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/507",
      "departureTime" : "07:10:00",
      "arrivalTime" : "07:52:30",
      "dayTypes" : [ "friday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-04-30",
        "to" : "2015-04-30",
        "runs" : "yes"
      } ]
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/8728",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/507",
      "departureTime" : "07:10:00",
      "arrivalTime" : "07:52:30",
      "dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-05-14",
        "to" : "2015-05-14",
        "runs" : "no"
      } ]
    } ],
    "geographicCoordinateProjection" : "6131429,2375268:-349,183:-259,177:-334,61:-225,-67 ..."
  }
</pre>
In addition to its own url, a ROUTE contains url to the LINE under which it is running. ROUTE has a name. ROUTE also has references to JOURNEY PATTERNs and JOURNEYs operating on it. geographicCoordinateProjection contains information on how to draw the route on a map. This field is encoded to save bandwidth and the client must decode the fields value. The field takes form:
<pre>
number,number:number,number etc.
</pre>
 
These are encoded coordinates, in a form of:
 
<pre>
lat1,lon1:delta lat2,delta lon2:delta lat3,delta lon3
</pre>
 
a client would decode the field by substracting delta lon2 from lon1 as well as substracting delta lat2 from lat1 and dividing result with 1e5. This would result in a coordinate pair from which delta lat3 and delta lon3 could again be substracted and so on. First lat1 and lon1 should be just divided with 1e5. For example:
 
First ":"-separated value is 6131429,2375268. First pair of coordinates can be obtained by dividing comma separated values with 1e5. Therefore first coordinate pair would be
<pre>
lat1: 6131429 / 100000 = 61.31429
lon1: 2375268 / 100000 = 23.75268
 
==> lat1,lon1 = 61.31429,23.75268
</pre>
 
Second coordinate pair would be obtained by substracting:
 
<pre>
lat2: (6131429 - (-349)) = 6131778 => 6131778 / 100000 = 61.31778
lon2: (2375268 - 183) = 2375085 =>  2375085 / 100000 = 23.75085
 
==> lat2,lon2 = 61.31778,23.75085
</pre>
 
Respectively, third coordinate pair would be obtained by substracting:


<pre>
lat3: (6131778 - (-259)) = 6132037 => 6132037 / 100000 = 61.32037
lon3: (2375085 - 177) = 2374908 =>  2374908 / 100000 = 23.74908


These queries return response like above, with entities matching the criteria. All query parameters are exclusive (if you specify multiple conditions, the conditions are ANDed together).
==> lat3,lon3 = 61.32037,23.74908
</pre>


==== Routes ====
And so on.
A client can access specific ROUTE'S details by issuing request at http://example.com/journeys/api/routes/123
 
==== Journeys ====
A client can access specific JOURNEY'S details by issuing request at http://data.itsfactory.fi/journeys/api/1/journeys/2010


This request would produce following response:
This request would produce following response:
<pre>
<pre>
{
{
     "headers" : {
     "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/2010",
        "dataValidityPeriod" : {
    "activityUrl" : "http://data.itsfactory.fi/journeys/api/1/vehicle-activity?journeyRef=3_0010_3615_0002",
            "validFrom" : "2013-01-01",
    "routeUrl" : "http://data.itsfactory.fi/journeys/api/1/routes/398",
            "validTo" : "2013-05-31"
    "lineUrl" : "http://data.itsfactory.fi/journeys/api/1/lines/3",
        },
    "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/333",
        "startIndex" : 0,
    "departureTime" : "00:10:00",
        "pageSize" : 1,
    "arrivalTime" : "00:38:00",
        "moreData" : false
    "headSign" : "Nokian asema C",
    "directionId" : "1",
    "wheelchairAccessible": false,
    "gtfs" : {
      "tripId": "4740073787Y"
     },
     },
     "data" : {
     "dayTypes" : [ "monday" ],
        "routes" : [
    "dayTypeExceptions" : [ {
            {
      "from" : "2015-04-04",
                "href" : "http://example.com/journeys/api/routes/123",
      "to" : "2015-04-04",
                "line" : "http://example.com/journeys/api/lines/123",
      "runs" : "yes"
                "pointsOnRoute": [
    } ],
                    {
    "calls" : [ {
                        "location": "61.48016,23.83057"
      "arrivalTime" : "00:10:00",
                    },                  
      "departureTime" : "00:10:00",
                    {
      "stopPoint" : {
                        "location": "60.48016,23.83057"
        "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0002",
                    },
        "location" : "61.49756,23.76148",
                    {
        "name" : "Keskustori L",
                        "location": "59.48016,23.83057"
        "shortName" : "0002",
                    }                   
        "tariffZone" : "1",
                ]
        "municipality" : {
            }
          "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
        ]
          "shortName" : "837",
          "name" : "Tampere"
        }
      }
    }, {
      "arrivalTime" : "00:11:00",
      "departureTime" : "00:11:00",
      "stopPoint" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0500",
        "location" : "61.49794,23.76558",
        "name" : "Koskipuisto C",
        "shortName" : "0500",
        "tariffZone" : "1",
        "municipality" : {
          "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
          "shortName" : "837",
          "name" : "Tampere"
        }
      }
     }
     }
}
    ...
    ]
  }
</pre>
</pre>
A client can search ROUTES by issuing following requests:<br>
JOURNEY element contains property called "call". A call is NeTEx element which binds together journeys arrival and departure times with STOP POINT information. For example the JOURNEY in the response has three calls: first call tells that the JOURNEY start time and that it starts from STOP POINT with id 222. activityUrl points to records of journey's current activity on the street network (assuming a vehicle is operating currently on this journey). Please see chapter "Vehicle Activity" for more details.
* http://example.com/journeys/api/routes will return paged list of all ROUTES
* http://example.com/journeys/api/routes?lineId=123 will return ROUTES which run on the LINE with id 123


These queries return response like above, with entities matching the criteria. All query parameters are exclusive (if you specify multiple conditions, the conditions are ANDed together).
A client can search JOURNEYS by issuing following requests:<br>
* http://data.itsfactory.fi/journeys/api/1/journeys will return paged list of all JOURNEYS
* http://data.itsfactory.fi/journeys/api/1/journeys?lineId=2 will return JOURNEYS which run on the LINE with id 2
* http://data.itsfactory.fi/journeys/api/1/journeys?routeId=1 will return JOURNEYS which run on the ROUTE with id 1
* http://data.itsfactory.fi/journeys/api/1/journeys?departureTime=08:00:00 will return JOURNEYS which depart at the given time
* http://data.itsfactory.fi/journeys/api/1/journeys?arrivalTime=08:21:00 will return JOURNEYS which last call arrives at STOP POINT at 08:21:00+0300
* http://data.itsfactory.fi/journeys/api/1/journeys?dayTypes=Monday,Tuesday,Wednesday will return JOURNEYS which run on given day types
* http://data.itsfactory.fi/journeys/api/1/journeys?stopPointId=111 will return JOURNEYS which contains a call which contains STOP POINT with id 111
* http://data.itsfactory.fi/journeys/api/1/journeys?firstStopPointId=111 will return JOURNEYS which first call which contains STOP POINT with id 111
* http://data.itsfactory.fi/journeys/api/1/journeys?lastStopPointId=111 will return JOURNEYS which last call which contains STOP POINT with id 111


==== Route Patterns ====
==== Journey Patterns ====
List of route patterns is not available, clients are expected to navigate to a certain route pattern via lines or routes.
A client can access specific JOURNEY PATTERNS details by issuing request at http://data.itsfactory.fi/journeys/api/1/journey-patterns/260
 
A client can access specific ROUTE PATTERN'S details by issuing request at http://example.com/journeys/api/route-patterns/111


This request would produce following response:
This request would produce following response:
<pre>
<pre>
{
{
     "headers" : {
     "url" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/260",
        "dataValidityPeriod" : {
    "routeUrl" : "http://data.itsfactory.fi/journeys/api/1/routes/327",
            "validFrom" : "2013-01-01",
    "lineUrl" : "http://data.itsfactory.fi/journeys/api/1/lines/71",
            "validTo" : "2013-05-31"
    "originStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1592",
        },
    "destinationStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8524",
         "startIndex" : 0,
    "direction" : "0",
         "pageSize" : 1,
    "name" : "Kalkku - Nokian asema C",
         "moreData" : false
    "stopPoints" : [ {
     },
      "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1592",
    "data" : {
      "location" : "61.49475,23.56963",
         "route-patterns" : [
      "name" : "Kalkku",
            {
      "shortName" : "1592",
                "href" : "http://example.com/journeys/api/route-patterns/111",
      "tariffZone" : "1",
                "route" : "http://example.com/journeys/api/routes/123",
      "municipality" : {
                "pointsOnRoute": [
         "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
                    {
         "shortName" : "837",
                        "latitude" : "61.48016",
         "name" : "Tampere"
                        "longitude" : "23.83057"
      }
                    },
     }, {
                    {
      "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8549",
                        "latitude" : "60.48016",
      "location" : "61.49445,23.56352",
                        "longitude" : "23.83057"
      "name" : "Välimaantie",
                    },
      "shortName" : "8549",
                    {
      "tariffZone" : "2",
                        "latitude" : "59.48016",
      "municipality" : {
                        "longitude" : "23.83057"
         "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/536",
                    }
        "shortName" : "536",
                ]
        "name" : "Nokia"
            }
      }
         ]
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8547",
      "location" : "61.49267,23.55689",
      "name" : "Vihnuskallionkatu",
      "shortName" : "8547",
      "tariffZone" : "2",
      "municipality" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/536",
        "shortName" : "536",
        "name" : "Nokia"
      }
    }
    ...
    ],
    "journeys" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/2040",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/260",
      "departureTime" : "06:10:00",
      "arrivalTime" : "06:21:00",
      "headSign" : "Nokian asema C",
      "dayTypes" : [ "friday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-05-01",
        "to" : "2015-05-01",
        "runs" : "no"
      } ]
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/2374",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/260",
      "departureTime" : "06:10:00",
      "arrivalTime" : "06:21:00",
      "headSign" : "Nokian asema C",
      "dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-05-14",
        "to" : "2015-05-14",
         "runs" : "no"
      } ]
     }
     }
}
    ...
 
    ]
  }
</pre>
</pre>
A client can search ROUTE PATTERNS by issuing following requests:
* http://example.com/journeys/api/route-patterns returns all ROUTE PATTERNS
* http://example.com/journeys/api/route-patterns?routeId=111 will return ROUTE PATTERN for ROUTE with id 111
* http://example.com/journeys/api/route-patterns?startsAt=61.48016,23.83057 will return ROUTE PATTERNS that start at given coordinates
* http://example.com/journeys/api/route-patterns?startsAt=(61.48016,23.83057),(51.83057,13.83057) will return ROUTE PATTERNS that start within given coordinate box. Format: (upper left corner of the box),(lower right corner of the box)
* http://example.com/journeys/api/route-patterns?stopsAt=61.48016,23.83057 will return ROUTE PATTERNS that stop at given coordinates
* http://example.com/journeys/api/route-patterns?stopsAt=(61.48016,23.83057),(51.83057,13.83057) will return ROUTE PATTERNS that stop within given coordinate box. Format: (upper left corner of the box),(lower right corner of the box)


==== Journeys ====
A JOURNEY PATTERN contains references to STOP POINTs (which form the JOURNEY PATTERN) as well as references to JOURNEYs which run on this JOURNEY PATTERN.
List of route JOURNEYS not available, clients are expected to navigate to a certain JOURNEY via LINES or ROUTES.


A client can access specific JOURNEY'S details by issuing request at http://example.com/journeys/api/journeys/111
==== Stop Points ====
A client can access specific STOP POINTS details by issuing request at http://data.itsfactory.fi/journeys/api/1/stop-points/0001


This request would produce following response:
This request would produce following response:
<pre>
<pre>
{
{
     "headers" : {
     "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0001",
        "dataValidityPeriod" : {
    "location" : "61.49751,23.76151",
            "validFrom" : "2013-01-01",
    "name" : "Keskustori M",
            "validTo" : "2013-05-31"
    "shortName" : "0001",
        },
    "tariffZone" : "A",
        "startIndex" : 0,
    "municipality" : {
        "pageSize" : 1,
      "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
        "moreData" : false
      "shortName" : "837",
    },
      "name" : "Tampere"
    "data" : {
        "journeys" : [
            {
                "href" : "http://example.com/journeys/api/journeys/111",
                "departureTime" : "08:00:00+0300",
                "dayTypes" : [
                    {
                        "href" : "http://example.com/journeys/api/day-types/weekdays"
                    }
                ],
                "dayTypeExceptions" : [
                    {
                        "href" : "http://example.com/journeys/api/day-type-exceptions/111",
                        "date" : "2014-05-05",
                        "runs" : "no"
                    }
                ],
                "calls" : [
                    {
                        "href" : "http://example.com/journeys/api/calls/1123",
                        "arrival" : "08:00:00+0300",
                        "departure" : "08:00:00+0300",
                        "stopPoint" : {
                            "href" : "http://example.com/journeys/api/stop-points/222"
                        }
                    },
                    {
                        "href" : "http://example.com/journeys/api/calls/1124",
                        "arrival" : "08:10:00+0300",
                        "departure" : "08:10:00+0300",
                        "stopPoint" : {
                            "href" : "http://example.com/journeys/api/stop-points/223"
                        }
                    },
                    {
                        "href" : "http://example.com/journeys/api/calls/1125",
                        "arrival" : "08:20:00+0300",
                        "departure" : "08:20:00+0300",
                        "stopPoint" : {
                            "href" : "http://example.com/journeys/api/stop-points/224"
                        }
                    }
                ]
            }
        ]
     }
     }
}
  }
</pre>
</pre>
A client can search JOURNEYS by issuing following requests:<br>
* http://example.com/journeys/api/journeys will return paged list of all JOURNEYS
* http://example.com/journeys/api/journeys?lineId=123 will return JOURNEYS which run on the LINE with id 123
* http://example.com/journeys/api/journeys?routeId=123 will return JOURNEYS which run on the ROUTE with id 123
* http://example.com/journeys/api/journeys?departureDate=2013-06-10 will return JOURNEYS which depart at the given date
* http://example.com/journeys/api/journeys?departureTime=08:00:00+0300 will return JOURNEYS which depart at the given time
* http://example.com/journeys/api/journeys?dayTypeId=123 will return JOURNEYS which run on the DAY TYPE with id 123
* http://example.com/journeys/api/journeys?dayTypeExceptionId=111 will return JOURNEYS which have a DAY TYPE EXCEPTION with id 111
* http://example.com/journeys/api/journeys?stopPointId=111 will return JOURNEYS which contains a CALL which contains STOP POINT with id 111
* http://example.com/journeys/api/journeys?lastCallStopPointArrivalTime=08:20:00+0300 will return JOURNEYS which last CALL arrives at STOP POINT at 08:20:00+0300
* http://example.com/journeys/api/journeys?firstStopPointId=111 will return JOURNEYS which first CALL which contains STOP POINT with id 111
* http://example.com/journeys/api/journeys?lastStopPointId=111 will return JOURNEYS which last CALL which contains STOP POINT with id 111


These queries return response like above, with entities matching the criteria. All query parameters are exclusive (if you specify multiple conditions, the conditions are ANDed together).
A client can search STOP POINTS by issuing following requests:<br>
* http://data.itsfactory.fi/journeys/api/1/stop-points will return list of all STOP POINTS
* 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=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: A,B,C,D,E,F and G
 
Please see https://www.nysse.fi/en/tickets-and-fares/zones.html for more details on tariff zones.


==== DayTypes ====
==== Municipalities ====
A client can access paged list of DAY TYPES by making HTTP GET request to url http://example.com/journeys/api/day-types
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>
{
{
    "headers" : {
  "url": "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
        "dataValidityPeriod" : {
  "shortName": "837",
            "validFrom" : "2013-01-01",
  "name": "Tampere"
            "validTo" : "2013-05-31"
        },
        "startIndex" : 0,
        "pageSize" : 10,
        "moreData" : false
    },
    "data" : {
        "dayTypes" : [
            {
                "href" : "http://example.com/journeys/api/day-types/weekdays",
                "properties" : [
                    {
                        "daysOfWeek" : "Monday,Tuesday,Wednesday,Thursday,Friday"
                    }
                ]
            }
            ...
        ]
    }
}
}
</pre>


==Vehicle Activity==
Journeys API allows clients to access real-time location of vehicles moving through the street network. To do this, client would make a HTTP GET request to url
<br><br>
http://data.itsfactory.fi/journeys/api/1/vehicle-activity
<br><br>
The call would result in a following response:
<pre>
{
    "recordedAtTime" : "2014-10-05T23:22:00.008+03:00",
    "validUntilTime" : "2014-10-05T23:22:30.008+03:00",
    "monitoredVehicleJourney" : {
      "lineRef" : "3",
      "directionRef" : "1",
      "framedVehicleJourneyRef" : {
        "dateFrameRef" : "2014-10-05",
        "datedVehicleJourneyRef" : "http://data.itsfactory.fi/journeys/api/1/journeys/3_2240_1028_3615"
      },
      "vehicleLocation" : {
        "longitude" : "23.6904222",
        "latitude" : "61.5267588"
      },
      "operatorRef" : "TKL",
      "bearing" : "92.0",
      "delay" : "-P0Y0M0DT0H3M20.000S",
      "vehicleRef" : "TKL_028",
      "journeyPatternRef" : "3V",
      "originShortName" : "3615",
      "destinationShortName" : "1028",
      "speed" : "10.0",
      "originAimedDepartureTime" : "2240",
      "onwardCalls" : [ {
        "expectedArrivalTime" : "2014-10-05T23:22:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:22:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1414",
        "order" : "46"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:23:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:23:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1416",
        "order" : "47"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:24:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:24:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1024",
        "order" : "48"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:25:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:25:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1026",
        "order" : "49"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:25:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:25:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1028",
        "order" : "50"
      } ]
    }
  }
  ...
</pre>
</pre>


A client can access specific DAY TYPE'S details by for example issuing request at http://example.com/journeys/api/day-types/weekdays
The response contains a list of elements described above. Each element corresponds to a active vehicle currently operating in the road network. Following fields are present:


This request would produce following response:
* recordedAtTime specifes the point of time when the vehicle's activity is monitored
* validUntilTime specifies the maximum time this data is valid. Records are updated once in a second, so the client should not wait until the validUntilTime has passed to request more data.
* 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.
* dataFrameRef specifies the date when the vehicle started from the origin stop
* datedVehicleJorneyRef contains a link back to Journeys API from which more information about this JOURNEY can be obtained.
* originAimedDepartureTime specifies which time the vehicle departed from the origin stop
* 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
* delay specifies the relative time the vehicle is behind or ahead of its planned schedule
* vehicleRef uniquely identifies the monitored vehicle
* onwardCalls contains a list of stops where the vehicle is stopping next as well as estimated times on each stop. Each onwardCall also contains stopPointRef which points back to Journeys API and provides more information on the stop in question. PointOrder indicates the position of the stop in the full stop point list obtainable from datedVehicleJorneyRef link.
 
The client can filter activity by issuing following query parameters:
* lineRef, which filters away everything except activity on given line
* 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
** on line 2
** on journey which started today at 22:30
** 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>
<pre>
{
{
     "headers" : {
  1001: [
         "dataValidityPeriod" : {
     {
            "validFrom" : "2013-01-01",
      lineRef: "3R",
            "validTo" : "2013-05-31"
      directionRef: "2",
         },
      vehicleLocation: {
         "startIndex" : 0,
         longitude: "23.7337863",
         "pageSize" : 1,
        latitude: "61.5007787"
         "moreData" : false
      },
    },
      operatorRef: "TKL",
    "data" : {
      bearing: "70",
         "dayTypes" : [
      delay: "-P0Y0M0DT0H1M18.000S",
            {
      vehicleRef: "TKL_41",
                "href" : "http://example.com/journeys/api/day-types/weekdays",
      journeyPatternRef: "3R",
                "properties" : [
      originShortName: "1028",
                    {
      destinationShortName: "0002",
                        "daysOfWeek" : "Monday,Tuesday,Wednesday,Thursday,Friday"
      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>


</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.


=== Search Queries ===
==Support / Community==
TBW
You can contact us via email: dev-support@itsfactory.fi


A client can search LINES by issuing following requests:<br>
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.
* http://example.com/journeys/api/lines?name=13 will return LINES which name contains text "13" (case-insensitive)
[[Luokka:Api]]
* http://example.com/journeys/api/lines?description=Hermia will return LINES which description contains text "Hermia" (case-insensitive)
[[Luokka:Public Transport APIs]]
[[Luokka:Tampere APIs]]

Nykyinen versio 4. marraskuuta 2022 kello 14.35

Concept

Journeys API allows developers and clients to access Public Transport information via REST API

  • Routes on which public transport services operate
  • Lines, or in other words grouping of routes. For example Line 2, which runs from Rauhaniemi to Pyyninkintori in Tampere
  • Journeys made by public transport vehicles on certain line and route at certain day and time
  • Stops where public transport vehicles stop during their journeys
  • Vehicle Monitoring where public transport vehicles stop during their journeys

The API allows accessing these concepts as hierarchy of objects (see later) as well as performing searches.

Journeys API combines together various data sources and offers their contents to developers and clients via JSON requests made over HTTP. Static data (ie. lines, routes, stops and time schedules) comes from GTFS (https://developers.google.com/transit/gtfs/) files. This data is augmented with proprietary MALA format (tariff zones, municipalities). Real-time data (observations on where public transport vehicles are currently operating) are polled from siri.ij2010.tampere.fi SIRI VM endpoint once in a second. This data includes for example real-time coordinate updates for public transport vehicles.

Journeys API Network.png

API Entities

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.

API Entities 1.1.png

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

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.

Journ Line 2.png

Line

LINE entity is a grouping of ROUTES that is generally known to the public with a common name, such as "Line 2". ROUTES on the same LINE usually follow similar ROUTEs.

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 that day is Labor Day".

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

REST styled API

Journeys API follows RESTful design pattern. This means that all entities returned by the API have an unique URL via which the entity can be accessed at all times. The returned entities refer to each other via these URLs, and each entity URL is always included in the entity itself as "href" property. Following is a fragment from STOP POINT entity response: 

...
"body" : [
    {
    "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0001",
    "location" : "61.49751,23.76151",
    "name" : "Keskustori M",
    "shortName" : "0001",
    "tariffZone" : "1",
    "muncipality" : {
      "url" : "http://data.itsfactory.fi/journeys/api/1/muncipalities/837",
      "shortName" : "837",
      "name" : "Tampere"
    }
  }
]
...

The STOP POINT itself has a url property which points to the STOP POINT entity itself. A client can use this URL access this entity at any time. Nested objects may also include urls as in case of muncipality inside the stopPoint.

API-Wide URL parameters

Indent

Indent formats the server response to more human readable format. 

http://data.itsfactory.fi/journeys/api/1/lines?indent=yes

Response structure

Journeys API response is structured as follows: 

{
    "status" : "success",
    "data" : {
        "headers" : {
            "paging" : {
                "startIndex" : 0,
                "pageSize" : 1,
                "moreData" : false
            }
        },
        "body": [
            ...
        ]
    }
}

The response has headers and data elements. Data element contains the actual response data, and its content varies depending on the request made by the client. Headers contain metadata-like information about the response. startIndex tells the index of the first returned element, pageSize tells how many items were returned and moreData tells if the client should make another request to fetch the additional data. This approach is called "paging". The client can specify startIndex parameter to the request URL to specify the starting index of an entity list, for example: 

http://data.itsfactory.fi/journeys/api/1/lines?startIndex=10

If omitted, the Journeys API assumes startIndex to be zero.

In case of a malformed request, such as wrongly formatted coordinate strings, server responds with a fail message: 

{
  "status" : "fail",
  "data" : {
    "title" : "Coordinates",
    "message" : "Illegal format: must be latitude,longitude"
  }
}

In internal server error cases, server responds with similar response, except the status is "error": 

{
  "status" : "error",
  "data" : {
    "message" : "Guru Meditation"
  }
}

Entity Queries

About Query Parameters

Journeys API allows the client user URL parameters in queries. You can find out valid query parameters for each entity on this page. A client can issue none or all query parameters in a query. For example a client could query: 

http://data.itsfactory.fi/journeys/api/1/lines

or 

http://data.itsfactory.fi/journeys/api/1/lines?name=13&description=hermia

by using multiple query parameters.

Query Parameter Reference

Below you can find allowed query parameters by Journeys API url. 

api/1/lines
	- description : String

api/1/routes
	- lineId : String
	- name : String

api/1/journey-patterns
	- lineId : String
	- name : String
	- firstStopPointId : String
	- lastStopPointId : String
	- stopPointId : String

api/1/journeys
	- lineId : String
	- routeId : String
	- journeyPatternId : String
	- dayTypes : comma separated list of: monday, tuesday, wednesday, friday, saturday, sunday
	- departureTime : hh:mm
	- arrivalTime : hh:mm
	- firstStopPointId : String
	- lastStopPointId : String
	- stopPointId : String
        - gtfsTripId: String

api/1/stop-points
	- name: String 
	- location: lat,lon or lat1,lon1:lat2,lon2 (upper left corner of a box : lower right corner of a box)
	- tariffZone : one of: 1,2,3,S (http://joukkoliikenne.tampere.fi/fi/muutokset-tampereen-seudun-joukkoliikenteessa-30.6.2014/tariffijarjestelma-ja-vyohykejako.html)
	- municipalityName: String
	- municipalityShortName: String

api/1/municipalities
	- name: String
	- shortName: String

api/1/vehicle-activity
	- lineRef: String or comma separated list of strings with * as wildcard, for example: lineRef=3 or lineRef=3,1*
	- vehicleRef: String or comma separated list of strings with * as wildcard (see lineRef)
	- journeyRef: String or comma separated list of strings with * as wildcard (see lineRef)
 	- directionRef: String, choice of 1 or 2

Field Exclusion

Journeys API allows exclusion of returned fields depending on the end point. Below are list of end points which allow field exclusion. 

api/1/journey-patterns
        - exclusions: stopPoints, journeys
api/1/journeys
        - exclusions: calls
api/1/routes
        - exclusions: journeyPatterns, journeys, geographicCoordinateProjection

For each end point a single or multiple exclusion can be used. Multiple exclusions are separated by comma. For example a client might call:

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

Each entity in Journeys API has an id (the url field ends to it), for example in line id "Y4" in url 

http://data.itsfactory.fi/journeys/api/1/lines/Y4
  • LINE ids relate to "known" line names by the scheduling, for example line Y4 has id Y4. This id is unlikely to change.
  • STOP POINT ids relate to "known" stop point numbers by the scheduling, for example stop point Keskustori M has number 0001 which is also the id of the stop point. This id is unlikely to change.

ROUTEs, JOURNEYs, MUNCIPALITIES and JOURNEY PATTERNs have ids which are likely change over time. These ids should be stored in the client only for short periods of time.

Lines

A client can access specific LINE'S details by issuing request at http://data.itsfactory.fi/journeys/api/1/lines/13

This request would produce following response: 

{
    "status" : "success",
    "data" : {
        "headers" : {
            "paging" : {
                "startIndex" : 0,
                "pageSize" : 1,
                "moreData" : false
            }
        },
        "body": [
            {
                "href" : "http://data.itsfactory.fi/journeys/api/1/lines/123",
                "name" : "13",
                "description" : "Hermia - Lukonmäki - Keskustori - Tesoma - Lamminpää - Ylöjärvi"
            }
        ]
    }
}

A client can search LINES by issuing for example following requests:

Routes

A client can access specific ROUTE'S details by issuing request at http://data.itsfactory.fi/journeys/api/1/routes/288

This request would produce following response: 

{
    "url" : "http://data.itsfactory.fi/journeys/api/1/routes/288",
    "lineUrl" : "http://data.itsfactory.fi/journeys/api/1/lines/50",
    "name" : "Lempäälä - Koskipuisto H",
    "journeyPatterns" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/507",
      "originStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/7559",
      "destinationStop" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0517",
      "name" : "Lempäälä - Koskipuisto H"
    } ],
    "journeys" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/8726",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/507",
      "departureTime" : "07:10:00",
      "arrivalTime" : "07:52:30",
      "dayTypes" : [ "friday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-04-30",
        "to" : "2015-04-30",
        "runs" : "yes"
      } ]
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/8728",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/507",
      "departureTime" : "07:10:00",
      "arrivalTime" : "07:52:30",
      "dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-05-14",
        "to" : "2015-05-14",
        "runs" : "no"
      } ]
    } ],
    "geographicCoordinateProjection" : "6131429,2375268:-349,183:-259,177:-334,61:-225,-67 ..."
  }

In addition to its own url, a ROUTE contains url to the LINE under which it is running. ROUTE has a name. ROUTE also has references to JOURNEY PATTERNs and JOURNEYs operating on it. geographicCoordinateProjection contains information on how to draw the route on a map. This field is encoded to save bandwidth and the client must decode the fields value. The field takes form: 

number,number:number,number etc.

These are encoded coordinates, in a form of: 

lat1,lon1:delta lat2,delta lon2:delta lat3,delta lon3

a client would decode the field by substracting delta lon2 from lon1 as well as substracting delta lat2 from lat1 and dividing result with 1e5. This would result in a coordinate pair from which delta lat3 and delta lon3 could again be substracted and so on. First lat1 and lon1 should be just divided with 1e5. For example:

First ":"-separated value is 6131429,2375268. First pair of coordinates can be obtained by dividing comma separated values with 1e5. Therefore first coordinate pair would be 

lat1: 6131429 / 100000 = 61.31429
lon1: 2375268 / 100000 = 23.75268

==> lat1,lon1 = 61.31429,23.75268

Second coordinate pair would be obtained by substracting: 

lat2: (6131429 - (-349)) = 6131778 => 6131778 / 100000 = 61.31778
lon2: (2375268 - 183) = 2375085 =>  2375085 / 100000 = 23.75085

==> lat2,lon2 = 61.31778,23.75085

Respectively, third coordinate pair would be obtained by substracting: 

lat3: (6131778 - (-259)) = 6132037 => 6132037 / 100000 = 61.32037
lon3: (2375085 - 177) = 2374908 =>  2374908 / 100000 = 23.74908

==> lat3,lon3 = 61.32037,23.74908

And so on.

Journeys

A client can access specific JOURNEY'S details by issuing request at http://data.itsfactory.fi/journeys/api/1/journeys/2010

This request would produce following response: 

{
    "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/2010",
    "activityUrl" : "http://data.itsfactory.fi/journeys/api/1/vehicle-activity?journeyRef=3_0010_3615_0002",
    "routeUrl" : "http://data.itsfactory.fi/journeys/api/1/routes/398",
    "lineUrl" : "http://data.itsfactory.fi/journeys/api/1/lines/3",
    "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/333",
    "departureTime" : "00:10:00",
    "arrivalTime" : "00:38:00",
    "headSign" : "Nokian asema C",
    "directionId" : "1",
    "wheelchairAccessible": false,
    "gtfs" : {
       "tripId": "4740073787Y"
    },
    "dayTypes" : [ "monday" ],
    "dayTypeExceptions" : [ {
      "from" : "2015-04-04",
      "to" : "2015-04-04",
      "runs" : "yes"
    } ],
    "calls" : [ {
      "arrivalTime" : "00:10:00",
      "departureTime" : "00:10:00",
      "stopPoint" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0002",
        "location" : "61.49756,23.76148",
        "name" : "Keskustori L",
        "shortName" : "0002",
        "tariffZone" : "1",
        "municipality" : {
          "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
          "shortName" : "837",
          "name" : "Tampere"
        }
      }
    }, {
      "arrivalTime" : "00:11:00",
      "departureTime" : "00:11:00",
      "stopPoint" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0500",
        "location" : "61.49794,23.76558",
        "name" : "Koskipuisto C",
        "shortName" : "0500",
        "tariffZone" : "1",
        "municipality" : {
          "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
          "shortName" : "837",
          "name" : "Tampere"
        }
      }
    }
    ...
    ]
  }

JOURNEY element contains property called "call". A call is NeTEx element which binds together journeys arrival and departure times with STOP POINT information. For example the JOURNEY in the response has three calls: first call tells that the JOURNEY start time and that it starts from STOP POINT with id 222. activityUrl points to records of journey's current activity on the street network (assuming a vehicle is operating currently on this journey). Please see chapter "Vehicle Activity" for more details.

A client can search JOURNEYS by issuing following requests:

Journey Patterns

A client can access specific JOURNEY PATTERNS details by issuing request at http://data.itsfactory.fi/journeys/api/1/journey-patterns/260

This request would produce following response: 

{
    "url" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/260",
    "routeUrl" : "http://data.itsfactory.fi/journeys/api/1/routes/327",
    "lineUrl" : "http://data.itsfactory.fi/journeys/api/1/lines/71",
    "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" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1592",
      "location" : "61.49475,23.56963",
      "name" : "Kalkku",
      "shortName" : "1592",
      "tariffZone" : "1",
      "municipality" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
        "shortName" : "837",
        "name" : "Tampere"
      }
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8549",
      "location" : "61.49445,23.56352",
      "name" : "Välimaantie",
      "shortName" : "8549",
      "tariffZone" : "2",
      "municipality" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/536",
        "shortName" : "536",
        "name" : "Nokia"
      }
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/8547",
      "location" : "61.49267,23.55689",
      "name" : "Vihnuskallionkatu",
      "shortName" : "8547",
      "tariffZone" : "2",
      "municipality" : {
        "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/536",
        "shortName" : "536",
        "name" : "Nokia"
      }
    }
    ...
    ],
    "journeys" : [ {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/2040",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/260",
      "departureTime" : "06:10:00",
      "arrivalTime" : "06:21:00",
      "headSign" : "Nokian asema C",
      "dayTypes" : [ "friday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-05-01",
        "to" : "2015-05-01",
        "runs" : "no"
      } ]
    }, {
      "url" : "http://data.itsfactory.fi/journeys/api/1/journeys/2374",
      "journeyPatternUrl" : "http://data.itsfactory.fi/journeys/api/1/journey-patterns/260",
      "departureTime" : "06:10:00",
      "arrivalTime" : "06:21:00",
      "headSign" : "Nokian asema C",
      "dayTypes" : [ "monday", "tuesday", "wednesday", "thursday" ],
      "dayTypeExceptions" : [ {
        "from" : "2015-05-14",
        "to" : "2015-05-14",
        "runs" : "no"
      } ]
    }
    ...
    ]
  }

A JOURNEY PATTERN contains references to STOP POINTs (which form the JOURNEY PATTERN) as well as references to JOURNEYs which run on this JOURNEY PATTERN.

Stop Points

A client can access specific STOP POINTS details by issuing request at http://data.itsfactory.fi/journeys/api/1/stop-points/0001

This request would produce following response: 

{
    "url" : "http://data.itsfactory.fi/journeys/api/1/stop-points/0001",
    "location" : "61.49751,23.76151",
    "name" : "Keskustori M",
    "shortName" : "0001",
    "tariffZone" : "A",
    "municipality" : {
      "url" : "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
      "shortName" : "837",
      "name" : "Tampere"
    }
  }

A client can search STOP POINTS by issuing following requests:

About Tariff Zones

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 https://www.nysse.fi/en/tickets-and-fares/zones.html for more details on tariff zones.

Municipalities

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: 

{
  "url": "http://data.itsfactory.fi/journeys/api/1/municipalities/837",
  "shortName": "837",
  "name": "Tampere"
}

Vehicle Activity

Journeys API allows clients to access real-time location of vehicles moving through the street network. To do this, client would make a HTTP GET request to url

http://data.itsfactory.fi/journeys/api/1/vehicle-activity

The call would result in a following response: 

{
    "recordedAtTime" : "2014-10-05T23:22:00.008+03:00",
    "validUntilTime" : "2014-10-05T23:22:30.008+03:00",
    "monitoredVehicleJourney" : {
      "lineRef" : "3",
      "directionRef" : "1",
      "framedVehicleJourneyRef" : {
        "dateFrameRef" : "2014-10-05",
        "datedVehicleJourneyRef" : "http://data.itsfactory.fi/journeys/api/1/journeys/3_2240_1028_3615"
      },
      "vehicleLocation" : {
        "longitude" : "23.6904222",
        "latitude" : "61.5267588"
      },
      "operatorRef" : "TKL",
      "bearing" : "92.0",
      "delay" : "-P0Y0M0DT0H3M20.000S",
      "vehicleRef" : "TKL_028",
      "journeyPatternRef" : "3V",
      "originShortName" : "3615",
      "destinationShortName" : "1028",
      "speed" : "10.0",
      "originAimedDepartureTime" : "2240",
      "onwardCalls" : [ {
        "expectedArrivalTime" : "2014-10-05T23:22:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:22:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1414",
        "order" : "46"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:23:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:23:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1416",
        "order" : "47"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:24:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:24:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1024",
        "order" : "48"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:25:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:25:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1026",
        "order" : "49"
      }, {
        "expectedArrivalTime" : "2014-10-05T23:25:00+03:00",
        "expectedDepartureTime" : "2014-10-05T23:25:00+03:00",
        "stopPointRef" : "http://data.itsfactory.fi/journeys/api/1/stop-points/1028",
        "order" : "50"
      } ]
    }
  }
  ...

The response contains a list of elements described above. Each element corresponds to a active vehicle currently operating in the road network. Following fields are present:

  • recordedAtTime specifes the point of time when the vehicle's activity is monitored
  • validUntilTime specifies the maximum time this data is valid. Records are updated once in a second, so the client should not wait until the validUntilTime has passed to request more data.
  • 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.
  • dataFrameRef specifies the date when the vehicle started from the origin stop
  • datedVehicleJorneyRef contains a link back to Journeys API from which more information about this JOURNEY can be obtained.
  • originAimedDepartureTime specifies which time the vehicle departed from the origin stop
  • 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
  • delay specifies the relative time the vehicle is behind or ahead of its planned schedule
  • vehicleRef uniquely identifies the monitored vehicle
  • onwardCalls contains a list of stops where the vehicle is stopping next as well as estimated times on each stop. Each onwardCall also contains stopPointRef which points back to Journeys API and provides more information on the stop in question. PointOrder indicates the position of the stop in the full stop point list obtainable from datedVehicleJorneyRef link.

The client can filter activity by issuing following query parameters:

  • lineRef, which filters away everything except activity on given line
  • 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
    • on line 2
    • on journey which started today at 22:30
    • 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

http://data.itsfactory.fi/journeys/api/1/stop-monitoring?stops=0001,0002

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: 

{
  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"
        }
      }
    }
  ]
}
  ...

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.

Noudettu kohteesta ”https://wiki.itsfactory.fi/index.php?title=Journeys_API&oldid=2018”