Journeys API

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

Journeys API allows developers and clients to access following 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

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

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.

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

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, Call, 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".

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.

Queries and Responses

API-Wide URL parameters

Time

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

http://example.com/journeys/lines/?requestTime=2013-01-10

request the Journeys API would return entities from the winter schedule. Respectively, a request to url

http://example.com/journeys/lines/?requestTime=2013-06-10 

would return entities from the summer schedule.

The requestTime parameter can be omitted, in this case requestTime is considered to be the time when the client made the request.

Response structure

Journeys API response is structured as follows:

{
    "headers" : {
        "dataValidityPeriod" : {
            "validFrom" : "2013-01-01",
            "validTo" : "2013-05-31"
        }
    },
    "data" : {
       ...
    }
}

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.

Entity Queries

Lines

A client can access full list of LINES by making HTTP GET request to url http://example.com/journeys/api/lines/

This request would produce following response:

{
    "headers" : {
        "dataValidityPeriod" : {
            "validFrom" : "2014-05-01",
            "validTo" : "2014-06-30"
        }
    },
    "data" : {
        "lines":[
            {
                "href" : "http://example.com/journeys/api/lines/123",
                "name" : "13",
                "description" : "Hermia - Lukonmäki - Keskustori - Tesoma - Lamminpää - Ylöjärvi"
            }
            ...
        ]
    }
}

A client can access specific LINE'S details by issuing request at http://example.com/journeys/api/lines/123

This request would produce following response:

{
    "headers" : {
        "dataValidityPeriod" : {
            "validFrom" : "2014-05-01",
            "validTo" : "2014-06-30"
        }
    },
    "data" : {
        "lines":[
            {
                "href" : "http://example.com/journeys/api/lines/123",
                "name" : "13",
                "description" : "Hermia - Lukonmäki - Keskustori - Tesoma - Lamminpää - Ylöjärvi"
            }
        ]
    }
}