Routing

1 Coordinate based routing

Coordinate based routing returns the route between two coordinate points. 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). Result coordinates in KKJ3 (EPSG:2393).

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

 

Name

Params

Description

Start location coordinate

a

string(15) = x,y in Finnish KKJ3 Projection

End location coordinate

b

string(15) = x,y in Finnish KKJ3 Projection

Time

time

hhmm

Date

date

yyyymmdd

Arrival/departure search

 timemode

 

1=departure time
2=arrival time

Optimization method

optimize

1=default
2=fastest
3=minimize changes
4=minimize walks

Change marginal

margin

Default 3, Values 0-10 minutes.
This value must be between every change.

Change penalty

penalty

Default 6, Values 0-99 minutes.
Gives penalty for every transfer. Default 6 minutes means, that user will prefer staying in the same vehicle, even if it is 6 minutes slower trip, than to make a change.

Walking speed

walkspeed

1=slow (30m/min)
2=normal (70m/min)
3=fast (100m/min)
4=running (200m/min)
5=cycling (300m/min)

How many routing results are outputted

show

Valid (1/3/5) routing results


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.matka.fi/?a=3597369,6784330&b=3392009,6686355&user=nano&pass=test

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

http://api.matka.fi/?a=3597369,6784330&b=3392009,6686355&time=1030&timemode=2&user=nano&pass=test

2 Wisetrip Routing

Wisetrip routing returns the route between two locations. There might be several bus stops with the same name (for example the stop “Sturenkatu” in Helsinki). Result coordinates are in WGS-84 (EPSG:4326).

If start and end locations are unique, result is a route. If start or end location name string matches multiple location names, then result will contain list of those locations.

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

Name

Params

Description

Start location name

from

location name in string format

End location name

to

location name in string format

Data source

data_source

Values are: navici or matkafi

navici=Priorize POI locations over streets and stops matkafi=No priorizing

Time

time

hhmm

Date

date

yyyymmdd

Arrival/departure search

 

timemode

1=departure time
2=arrival time

Optimization method

 

optimize

1=default
2=fastest
3=minimize changes
4=minimize walks

Change marginal

margin

Default 3, Values 0-10 minutes.
This value must be between every change.

Change penalty

penalty

Default 6, Values 0-99 minutes.
Gives penalty for every transfer. Default 6 minutes means that user will prefer staying in the same vehicle, even if it is 6 minutes slower trip, than to make a change.

Walking speed

walkspeed

1=slow (30m/min)
2=normal (70m/min)
3=fast (100m/min)
4=running (200m/min)
5=cycling (300m/min)

How many routing results are outputted

show

Valid (1/3/5) routing results

1. A search done when the user wants to reach the destination at a certain time. Returns one route.

http://api.matka.fi/?from=karvaamokuja&to=kornetintie,helsinki&data_source=navici&time=1025&timemode=2&show=1&user=nano&pass=test

2. A sample search when start location matches multiple locations.

http://api.matka.fi/?from=karvaaa&to=kornetintie,helsinki&data_source=navici&time=1025&timemode=2&show=1&user=nano&pass=test

3 Response XML

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

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

3.3 WALK element

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

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

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

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

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