Open data
 
Open data API HTTP Get Interface
 

HTTP Get interface

 N.B: This version of the API will be shut down from 5.11.2013 onwards

1 Instructions

1.1 Reittiopas API address

Reittiopas API is located in the following address.

http://api.reittiopas.fi/public-ytv/fi/api/


The API server has the most recent timetable data provided by YTV. Due to security and load reasons the API server has been separated from other parts of the Reittiopas system. However, the API is automatically updated with new data simultaneously with the other parts. The timetable data is updated approximately every two weeks. This does not affect the functioning of the service.

1.2 Login

The use of the interface requires a username and a password. The interface server does not have an actual login system, but login information is provided with every HTTP-request and it is used for logging purposes.

Frontpage: http://api.reittiopas.fi/public-ytv/fi/api/?user=[username]&pass=[password]
Example: http://api.reittiopas.fi/public-ytv/fi/api/?user=nano&pass=test

1.3 Reittiopas API modules

Every request to Reittiopas API uses HTTP GET. GET parameter values must be in ISO-8859-1 charset. Reittiopas API response is in XML format. Response xml is in ISO-8859-1 charset.

Modules of the Reittiopas API:

1.    Geocoding (includes stops and points of interest (POI))
2.    Reverse geocoding
3.    Routing between two points
4.    Search for the stop’s timetable (Response in ascii-format)

1.4 Coordinatesystem

Reittiopas API uses coordinates in Finnish KKJ2 (EPSG:2392) coordinate system. 

1.5 Geocoding

Geocoding returns the coordinates and the names of the POIs, stops and addresses. The search uses the same logic as the www-service of Reittiopas. Locations have been classified to different categories. Response coordinates are returned in KKJ2 and WGS-84 (EPSG:4326) coordinate systems.


The search term is provided through a variable that is added to the URL with the user credentials.

Variable Name Type
Search term
key String


 

 

Below are some search examples:

1. A search that returns all kinds of locations:
    http://api.reittiopas.fi/public-ytv/fi/api/?key=tee&user=nano&pass=test

Results for the search:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<MTRXML version="1.0">
  <GEOCODE key="tee">
    <LOC name1="Teeripuisto" number="" city="Helsinki" code="1701" address="" type="3" category="poi" x="2556686" y="6682815" lon="25.02051" lat="60.2528" />
    <LOC name1="Teekkaripolku" number="" city="Espoo" code="" address="" type="900" category="street" x="2546340" y="6675352" lon="24.832" lat="60.18713" />
    <LOC name1="Teemuntie" number="" city="Helsinki" code="" address="" type="900" category="street" x="2557985" y="6685213" lon="25.04465" lat="60.27414" />
    <LOC name1="Teerenpelinpolku" number="" city="Helsinki" code="" address="" type="900" category="street" x="2556532" y="6682578" lon="25.01767" lat="60.2507" />
    <LOC name1="Teerentie" number="" city="Kirkkonummi" code="" address="" type="900" category="street" x="2524959" y="6686629" lon="24.44804" lat="60.2902" />
    <LOC name1="Teerikuja" number="" city="Vantaa" code="" address="" type="900" category="street" x="2559094" y="6693721" lon="25.06718" lat="60.35033" />
    <LOC name1="Teerikukonkuja" number="" city="Helsinki" code="" address="" type="900" category="street" x="2556861" y="6683030" lon="25.02373" lat="60.25471" />
    <LOC name1="Teerikukontie" number="" city="Helsinki" code="" address="" type="900" category="street" x="2556888" y="6682971" lon="25.0242" lat="60.25417" />
    <LOC name1="Teerimäentie" number="" city="Kerava" code="" address="" type="900" category="street" x="2560257" y="6698983" lon="25.08981" lat="60.39737" />
    <LOC name1="Teerimäentie" number="" city="Vantaa" code="" address="" type="900" category="street" x="2562518" y="6686969" lon="25.12709" lat="60.28923" />
    <LOC name1="Teerimäentie" number="" city="Espoo" code="" address="" type="900" category="street" x="2536615" y="6673635" lon="24.65643" lat="60.1727" />
    <LOC name1="Teeripolku" number="" city="Vantaa" code="" address="" type="900" category="street" x="2559118" y="6693833" lon="25.06764" lat="60.35133" />
    <LOC name1="Teeririnne" number="" city="Vantaa" code="" address="" type="900" category="street" x="2559182" y="6693629" lon="25.06874" lat="60.34949" />
    <LOC name1="Teerisuonkuja" number="" city="Helsinki" code="" address="" type="900" category="street" x="2556947" y="6682640" lon="25.02518" lat="60.25119" />
    <LOC name1="Teerisuontie" number="" city="Helsinki" code="" address="" type="900" category="street" x="2556822" y="6682723" lon="25.02294" lat="60.25196" />
    <LOC name1="Teeritie" number="" city="Vantaa" code="" address="" type="900" category="street" x="2559089" y="6693605" lon="25.06705" lat="60.34929" />
    <LOC name1="Teekkarikylä" number="" city="Espoo" code="2222208" address="Otakaari" type="10" category="stop" x="2546445" y="6675512" lon="24.83393" lat="60.18855" />
    <LOC name1="Teerisuonkuja" number="" city="Helsinki" code="1382186" address="Teerisuontie" type="10" category="stop" x="2556964" y="6682609" lon="25.02547" lat="60.25091" />
    <LOC name1="Teerisuontie" number="" city="Helsinki" code="1382141" address="Teerisuontie" type="10" category="stop" x="2556740" y="6682861" lon="25.0215" lat="60.25321" />
    <LOC name1="Teeritie" number="" city="Vantaa" code="4810204" address="Korsontie" type="10" category="stop" x="2559002" y="6694007" lon="25.06559" lat="60.35291" />
  </GEOCODE>
</MTRXML>

2. A search that returns a single stop (as there should be only one result found with the search term):

http://api.reittiopas.fi/public-ytv/fi/api/?key=teekkarik&user=nano&pass=test

Result for the search:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<MTRXML version="1.0">
  <GEOCODE key="teek">
    <LOC name1="Teekkarikylä" number="" city="Espoo" code="2222208" address="Otakaari" type="10" category="stop" x="2546445" y="6675512" lon="24.83393" lat="60.18855" />
  </GEOCODE>
</MTRXML>

3. If the search term includes a digit, the search is done mainly for streets:

http://api.reittiopas.fi/public-ytv/fi/api/?key=tee+3&user=nano&pass=test

Result for the search:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<MTRXML version="1.0">
  <GEOCODE key="tee 3">
    <Loc name1="Teemuntie" number="3" city="Helsinki" code="" address="" type="900" category="street" x="2558009" y="6685216" lon="25.04509" lat="60.27416" />
    <Loc name1="Teerenpelinpolku" number="3" city="Helsinki" code="" address="" type="900" category="street" x="2556532" y="6682578" lon="25.01767" lat="60.2507" />
    <Loc name1="Teerentie" number="3" city="Kirkkonummi" code="" address="" type="900" category="street" x="2524983" y="6686436" lon="24.44845" lat="60.28846" />
    <Loc name1="Teerikuja" number="3" city="Vantaa" code="" address="" type="900" category="street" x="2559115" y="6693722" lon="25.06756" lat="60.35033" />
    <Loc name1="Teerikukonkuja" number="3" city="Helsinki" code="" address="" type="900" category="street" x="2556871" y="6683085" lon="25.02393" lat="60.2552" />
    <Loc name1="Teerikukontie" number="3" city="Helsinki" code="" address="" type="900" category="street" x="2556818" y="6683024" lon="25.02296" lat="60.25466" />
    <Loc name1="Teerimäentie" number="3" city="Espoo" code="" address="" type="900" category="street" x="2536588" y="6673694" lon="24.65595" lat="60.17323" />
    <Loc name1="Teerimäentie" number="3" city="Vantaa" code="" address="" type="900" category="street" x="2562518" y="6686969" lon="25.12709" lat="60.28923" />
    <Loc name1="Teerimäentie" number="3" city="Kerava" code="" address="" type="900" category="street" x="2560228" y="6698960" lon="25.08928" lat="60.39717" />
    <Loc name1="Teeripolku" number="3" city="Vantaa" code="" address="" type="900" category="street" x="2559118" y="6693833" lon="25.06764" lat="60.35133" />
    <Loc name1="Teeririnne" number="3" city="Vantaa" code="" address="" type="900" category="street" x="2559165" y="6693408" lon="25.06837" lat="60.34751" />
    <Loc name1="Teerisuonkuja" number="3" city="Helsinki" code="" address="" type="900" category="street" x="2556954" y="6682677" lon="25.02531" lat="60.25152" />
    <Loc name1="Teerisuontie" number="3" city="Helsinki" code="" address="" type="900" category="street" x="2557034" y="6682586" lon="25.02673" lat="60.2507" />
    <Loc name1="Teeritie" number="3" city="Vantaa" code="" address="" type="900" category="street" x="2559079" y="6693862" lon="25.06695" lat="60.35159" />
  </GEOCODE>
</MTRXML>

1.6 Reverse geocoding

Reverse geocoding searches for a street address closest to given coordinates. The search terms are provided through a variable that is added to the URL with the user credentials.

Variable Name Type
x-coordinate x number(7)
y-coordinate y number(7)



 

 

The coordinates are provided in KKJ2 -format.

Below are some search examples:

1. A search for the street name for the coordinates given:

http://api.reittiopas.fi/public-ytv/fi/api/?x=2546445&y=6675512&user=nano&pass=test

Result for the search:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<MTRXML version="1.0">
  <REVERSE x="2546445" y="6675512">
    <LOC name1="Otakaari" number="16" city="Espoo" />
  </REVERSE>
</MTRXML>

1.7 Closest stop with radius

Reittiopas API can be used to search for stops within a square with a given radius. Given point is the center of the square. Square’s side is twice the length of the given radius (see picture below). Center point can be either in KKJ2 or WGS-84 coordinate system. Coordinate system used in the response depends on the coordinate system used in the request.

 

Variable Name Type
Controller closest_stops 1 = closest stop search
Center point x coordinate y KKJ2 coordinate
Center point y coordinate x KKJ2 coordinate
Center point longitude lon WGS-84 coordinate
Center point latitude lat WGS-84 coordinate
Radius radius Meters, max 5000m

 

 

 

 

 

 

 Sample request: (Brackets means request and response are in WGS-84 coordinate system).

http://api.reittiopas.fi/public-ytv/fi/api/?closest_stops=1&x=2558009&y=6685216&(lon=25.04509&lat=60.27416&)user=nano&pass=test&radius=100

Result for the search:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<MTRXML version="1.0">

  <STOPS x=”2558009” y=”6685216” (lon=”25.04509” lat=”60.27416”) radius=”100”>

     <LOC code="1411101" x="2557978" y="6685207" dist="32"/>

     <LOC code="1411128" x="2557958" y="6685257" dist="65"/>

   </STOPS>

</MTRXML>

1.8 Routing

Routing returns the route between two coordinate points. In routing it is recommended to use street addresses (their coordinates) as it is difficult for the end user to know where exactly a stop is located. There might be several bus stops with the same name (for example the stop “Sturenkatu” in Helsinki).


The search terms are provided through a variable that is added to the URL with the user credentials.

Variable Name Type
Coordinates for the point A a string (15)  = x,y
Coordinates for the point A b string (15)  = x,y
Time time hhmm
Time mode timemode 1=departure time
2=arrival time
Date date yyyymmdd
Method of optimizing optimize 1=default
2=fastest
3=least transfers
4=least walking

Following values will be enabled:


default: $waitcost=1.0;  $walkcost=1.2; 
fastest: $waitcost=1.0;  $walkcost=1.0; 
min_changes: $waitcost=1.0;  $walkcost=1.5; 
min_walk
: $waitcost=1.0;  $walkcost=5.0; 

Transfer safety margin.  The minimum time between transfers. margin 3 minutes as default. Allowed values  are 0-10
Transfer penalty; this means that the user rather reaches the destination 5 min (default) later than transfers to another vehicle penalty 5 minutes as default. Allowed values 1-99.
Walking speed walkspeed 1=slow (30 m/min)
2=fast (70 m/min)
3=normal (100 m/min)
4=running (200 m/min)
5=cycling (300 m/min)
How many route suggestions will be shown show Allowed values 1/3/5
Transport type restriction use_bus
use_train
use_ferry
use_metro
use_tram
default value=1, to exclude transport type from routing use value 0.
Mode cost mode_cost_1
mode_cost_2
mode_cost_3

mode_cost_25

Can be used to weigh different transport types such as service lines or trams. Transport types correspond to YTV types 1-25.

Values can be either -1 or between 0.1 – 10.0. Value -1 excludes transport type from routing.

This parameter overrides Transport type restriction parameter.

Mobility mobility

Allowed values 0 and 1. This parameter excludes all other lines than low-floor lines.

Note, value is based on departures in register of public transportation. It cannot be fully confirmed that the low-floor line information is consistent. Forexample this information has been inconsistent in local traffic trains.

Because of this inconsistency this parameter is not used in Reittiopas service.

Wait cost waitcost

Values can be between 0.1 – 10.0. With this parameter you can weigh wait time cost when calculating fastest route.

This parameter overrides optimize parameter.

Walk cost walkcost

Values can be between 0.1 – 10.0. With this parameter you can weight walk time cost when calculating fastest route.

This parameter overrides optimize parameter.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1. A sample search that includes only coordinates. The system uses the current time as default; the time is fetched from the NTP –time server.

http://api.reittiopas.fi/public-ytv/fi/api/?a=2546445,6675512&b=2549445,6675513&user=nano&pass=test

2. A search done when the user wants to reach the destination at a certain time.

http://api.reittiopas.fi/public-ytv/fi/api/?a=2546445,6675512&b=2549445,6675513&time=1030&timemode=2&user=nano&pass=test

 

1.8.1 Response XML

1.8.1.1 ROUTE element

<ROUTE
  uid=‘%String’
  from=‘%String’
  to=‘%String’>
  <LENGTH length and duration of route/>
    starting location WALKs and LINEs of the route (optional)destination location
</ROUTE>

Each ROUTE element is a response to a GET_ROUTE element in the request. If the GET_ROUTE element had a user identifier attribute then it is reproduced in the response ROUTE. The from and to attributes are the user identifiers of starting and destination locations in the request.

1.8.1.2 LENGTH element

<LENGTH
time = ‘%Real’
dist = ‘%Distance’/>

This element gives the time in minutes and distance travelled in the distance units of the request of a route, leg or walk.

1.8.1.3 WALK element

<WALK>
<LENGTH length and duration of the walk/>
start location
destination location
</WALK>
 

1.8.1.4 LINE element

<LINE
id = ‘%Integer’
code = ‘%String’
type = ‘%Integer’
mobility = ‘%Integer’>
<LENGTH length and duration of the leg/>
start location
intermediate locations visited (optional)
destination location
</LINE>


The only difference to walks are the additional attributes and the optional list of stops visited during the leg. The id attribute is the line identifier in the trip planner database. The code attribute is the ‘code’ field in the ‘line’ table of the database. The type of a line is the transport type of the vehicle, and mobility is the bit field of properties that the vehicle provides.

1.8.1.5 Response locations (POINT & STOP)

Response locations are either point or stop locations. If a response location is considered to be same as one of the request locations, then it reproduces the user identifier of the request location in a uid attribute. All response locations have attributes x and y that specify the coordinates of the location in the coordinate system of the location database.

<POINT
uid = ‘%String’
x = ‘%Real’
y = ‘%Real’>
<ARRIVAL time when arrived at location/>
<DEPARTURE time when departed location/>
</POINT>

<STOP
uid = ‘%String’
id = ‘%String’
code = ‘%String’
x = ‘%Real’
y = ‘%Real’>
<ARRIVAL time when arrived at location/>
<DEPARTURE time when departed location/>
<NAME name of stop in a language/>
more names
</STOP>

The attribute id is the location id of the stop in the location data base. The code attribute is a concatenation of the ‘company_id’ and ‘code’ fields in the location database in the form company_id:code. The ARRIVAL and DEPARTURE elements are always present in a stop, but NAME elements are only present for those languages in which a stop has a name.

1.8.1.6 ARRIVAL & DEPARTURE elements

<ARRIVAL date=‘%Date’ time=‘%Time’/>
<DEPARTURE date=‘%Date’ time=‘%Time’/>

These elements appear in response locations and say when the traveller arrives and leaves a location.

1.8.1.7 NAME element

<NAME lang=‘%Integer’ val=‘%String’/>

These elements give the stop names in the languages that are in the database. The lang attribute is the number of a language in the database, and the val attribute is the name of the stop in the given language.

1.9 Stop timetable

It is possible to retrieve timetable for any YTV area bus stop from the Reittiopas API. Timetable search uses current time. Response contains at most 100 departures on the given day.
The search terms are provided through a variable that is added to the URL with the user credentials.

 

Variable Name Type
Stop code stop number(7) or number(4) or string+number(5) or string+number(6)
Date date yyyymmdd
Time time hhmm

 

 

 

 

 

 

Stop code is a 7 digit Register of Public Transportation (JORE) code. Code is unique in Helsinki metropolitan area. Used codes can be seen on YTV stop timetable web site (aikataulut.ytv.fi/pysakit/en/).

Four digit codes can also be used as the value of the stop code parameter. Codes can also include municipality prefix: v = Vantaa (e.g. v1001), e = Espoo (e.g. e1001), ka = Kauniainen, ke = Kerava ja ki = Kirkkonummi. Helsinki city stops do not have any prefix.

Search sample for stop code 2222209.
http://api.reittiopas.fi/public-ytv/fi/api/?stop=2222209&user=nano&pass=test

Search result is in ascii-format. Resultset is formatted as follows.

First row: System inner id | Name | Address | City

Following rows: Departure time | Line | Destination | Line code (JORE)

3314|Teekkarikylä|Otakaari|Espoo
1548|4|Kivenlahti|2004  1
1550|15|Jupperi|2015  1
1552|102|Otaniemi|2102  2
1558|2|Soukka|2002  1
1600|102|Otaniemi|2102  2
1600|10K|Puolarmetsä|2010K 1
1605|102|Otaniemi|2102  2
1605|15|Jupperi|2015  1
1608|4|Kivenlahti|2004  1
1611|102|Otaniemi|2102  2
1618|2|Soukka|2002  1
1619|102|Otaniemi|2102  2
1620|10|Puolarmetsä|2010  1
1620|15|Jupperi|2015  1
1628|102|Otaniemi|2102  2
1628|4|Kivenlahti|2004  1
1635|15|Jupperi|2015  1
1638|2|Soukka|2002  1
1639|102|Otaniemi|2102  2
1640|10K|Puolarmetsä|2010K 1
1648|4|Kivenlahti|2004  1
1649|102|Otaniemi|2102  2
1650|15|Jupperi|2015  1
1657|102|Otaniemi|2102  2
1658|2|Soukka|2002  1
1700|10|Puolarmetsä|2010  1
1705|102|Otaniemi|2102  2

2 Frequently asked questions

- Is it possible to do a search by place names or addresses?

The route search cannot be done with an address. Geocoding search needs to be done first. After geocoding the route search can be done with the fetched coordinates.

- How can the route be shown on a map?

To get the route to be shown on a map, the coordinates for all intermediate stops should be parsed from the XML. With the coordinates it is possible to draw the route on a map. There is no open interface for the maps used in Reittiopas.

- Is it possible to do requests in XML format?

Doing requests in XML format is not possible, as the requests are run through an http filter. Thus there is also no need to make firewall openings. The filter performs checks so that only complete requests go to the algorithm so the load on the server is as low as possible.

- Is it possible to use the map images from Reittiopas?

The maps used in Reittiopas are not open for any other use due to contractual restrictions. The use of the maps requires an agreement with YTV.

- Codes of the vehicles?

Line code in the routing response is a unique code from the Register of Public Transport (JORE). The code the passengers know and which can be seen on the bus can be parsed from the JORE-code with the help of transport type id (attribute type in the response).

Please note that there are some special cases such as 1300-series (subway), 1100-series (Helsinki night buses) and 1019 (ferry to Suomenlinna).
JORE line codes are always 7 characters long. For example “2102T 1” which is JORE code for line 102T.

The code consists of following parts:
1. character = area/transport type code (e.g. 2)
2.-4. character = line code (e.g. 102)
5. character = letter variant (e.g. T)
6. character = letter variant or numeric variant (numeric variants are usually not used for base routes and are not shown to the end users)
7. character = direction (always 1 or 2), not shown to end users

More detailed instructions can be asked from YTV.
Area/transport types are:
1=Helsinki internal traffic
2=Espoo internal bus traffic and regional bus traffic from Helsinki to Espoo
3=Local trains
4=Vantaa internal bus traffic and regional bus traffic from Helsinki to Vantaa
5=Regional transverse traffic in Espoo - Helsinki - Vantaa
6=not in use
7=U-lines (buses that drive also outside the YTV area of service)

Transport types:
1 Helsinki/bus
2 Helsinki/tram
3 Espoo internal
4 Vantaa internal
5 Regional traffic
6 Metro traffic
7 Ferry
8 U-lines
9 Other local traffic
10 Long-distance traffic
11 Express
12 VR local traffic
13 VR long-distance traffic
14 All
21 Helsinki service lines
22 Helsinki night traffic
23 Espoo service lines
24 Vantaa service lines
25 Regional night traffic
(types 9,10,11,13,14 are not used in the data)