Ero sivun ”Journeys API” versioiden välillä

ITS Factory Developer Wikistä
Rivi 128: Rivi 128:
</pre>
</pre>


LINE ids relate to "known" line names by the scheduling, for example line Y4 has id Y4. This id is unlikely to change.
* 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.
* 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.


==== Lines ====
==== Lines ====

Versio 6. lokakuuta 2014 kello 00.28

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.

A beta-phase API is available at http://data.itsfactory.fi/journeys/api/1/lines please see examples on this page for queries.

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.

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. Lines with filled diamond represent relation with ownership rule: the entity which has a diamond shape attached to it, owns the entity or property at other end of the line. Lines with empty diamond represent relation reference rule: the entity which has an empty diamond shape attached to it, is referred by entity or property at other end of the line. For example ROUTE owns JOURNEY PATTERN, and JOURNEY references a STOP POINT. 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: LINE and ROUTE share a relation. In this relation, a ROUTE relates to one LINE, whereas a LINE relates to zero or more ROUTEs.

Routes

ROUTE entity describes a path through (a road or a rail) network, which is used by a public transport service (such as bus or a tram). ROUTE has typically one or more projections. Projection is a way to describe a ROUTE on selected canvas. For example a route could be presented on a map by drawing it as a line on it. Another way would be project a ROUTE for example to OpenStreetMap by using OpenStreetMap roads to present the ROUTE. Journeys API currently supports only projecting the ROUTE as coordinate shape. Following picture is taken from Tampere "reittikartta" and outlines a ROUTE through Tampere.

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 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. CALLs on a certain JOURNEY follow a JOURNEY PATTERN. JOURNEY PATTERN is in essence a sequence of STOP POINTS on which the JOURNEY stops. In other words: ROUTE describes the vehicle's path through road network, and a JOURNEY PATTERN "overlays" it with a sequence of STOP POINTs. Consider a ROUTE as continuous drawn line and STOP POINTs as drawn circles on top of the line. STOP POINTs must follow the drawn line since those have to be on the vehicle's route. Single ROUTE can, however, have multiple JOURNEY PATTERNs: for example one for express line (which skips some of the stops) and one for the normal line which stops on every STOP POINT.

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.

About IDs

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

http://data.itsfactory.fi/journeys/api/1/lines/2
  • 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.

Lines

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

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 following requests:

Routes

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

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/routes/123",
                "line" : "http://data.itsfactory.fi/journeys/api/1/lines/123",
                "pointsOnRoute": [
                    {
                        "location": "61.48016,23.83057"
                    },                    
                    {
                        "location": "60.48016,23.83057"
                    },
                    {
                        "location": "59.48016,23.83057"
                    }                    
                ]
            }
        ]
    }
}

The ROUTE entity refers to LINE via the "line" property. The ROUTE entity also owns multiple POINT ON ROUTEs, which each have location property. The location property tells the latitude and longitude of the POINT ON ROUTE. Location has format: latitude,longitude.

A client can search ROUTES by issuing following requests:

Journeys

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

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/journeys/111",
                "route" : "http://data.itsfactory.fi/journeys/api/1/routes/123",
                "departureTime" : "08:00:00",
                 arrivalTime" : "08:20:00",
                "dayTypes" : ["Monday","Tuesday","Wednesday","Thursday","Friday"],
                "dayTypeExceptions" : [
                    {
                        "date" : "2014-05-05",
                        "runs" : "no"
                    }
                ],
                "calls" : [
                    {
                        "arrival" : "08:00:00",
                        "departure" : "08:00:00",
                        "stopPoint" : {
                            "href" : "http://data.itsfactory.fi/journeys/api/1/stop-points/222"
                            "location" : "61.44960,23.87165",
                            "name" : "Hermia",
                            "shortName" : "3633"   
                        }
                    },
                    {
                        "arrival" : "08:10:00",
                        "departure" : "08:10:00",
                        "stopPoint" : {
                            "href" : "http://data.itsfactory.fi/journeys/api/1/stop-points/223"
                            "location" : "61.43054,23.81566",
                            "name" : "Vuoreksen koulu",
                            "shortName" : "3635"
                        }
                    },
                    {
                        "arrival" : "08:20:00",
                        "departure" : "08:20:00",
                        "stopPoint" : {
                            "href" : "http://data.itsfactory.fi/journeys/api/1/stop-points/224"
                            "location" : "61.44273,23.86268",
                            "name" : "Näyttämönkatu",
                            "shortName" : "3637"
                        }
                    }
                ]
            }            
        ]
    }
}

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.

A client can search JOURNEYS by issuing following requests:

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). For example query:

Stop Points

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

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/stop-points/222",
                "location" : "61.44960,23.87165",
                "name" : "Hermia",
                "shortName" : "3633",
                "tariffZone" : "1"            
            }            
        ]
    }
}

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:

  • "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.

Noudettu kohteesta ”https://it103.infotripla.fi/itsfactorywiki/index.php?title=Journeys_API&oldid=1611”