logo
Journey Planner
TRE API API HTTP Get Interface
 

 

HTTP Get interface

 

1 Instructions

1.1 General

TRE API is located in the following address.

http://api.publictransport.tampere.fi/prod/

  • The use of the interface requires a user token and a token passphrase.

  • UTF-8 encoding is used with all requests.

  • Request type is given in URL parameter request=<request type>.

  • Response format can be changed.

    • URL parameter format=[json|xml], default response format is JSON.

    • format=txt prints the response in a more human readable format, can be used for testing the responses.

  • Coordinate system used in request and response can be changed.

    • URL parameters epsg_in=<epsg code> and epsg_out=<epsg code>.

    • Possible values are 2391 (KKJ1), 2392 (KKJ2), 2393 (KKJ3 default), 4326 (WGS84) and 3395 (Mercator).

    • It is also possible to use the names of the coordinate systems (kk1, kkj2, kkj3, wgs84 and mercator) as value of epsg_in and epsg_out.

  • Language used in the response can be changed.

    • URL parameter lang=[fi|sv|en|slangi], fi is default and Currently only one language ‘fi’ is supported.

  • Lists as parameter values are separated with pipes ("|"), e.g. loc_types=street|stop|poi

  • If there are major changes it is possible to use an older version of the API.

    • Versions are labeled with version numbers, such as 1_0_0.

      • E.g. api.publictransport.tampere.fi/1_0_0/?request=...

    • Users are always notified about changes in the API.

    • New features will be available for testing for a limited time.

      • E.g. api.publictransport.tampere.fi/beta/?request=...

    • Production version will be available at api.publictransport.tampere.fi/prod/?request=...

  • In most queries it is possible to limit the values in the response with URL parameter p.

    • E.g. p=110011 (as default the all fields in the response are returned).

    • The order of the response fields is described for every query.

    • New fields will be added to the end of the response.

    • Incomplete limit parameters are filled with zeros.

      • E.g. p=101 is interpreted as 101000 if there are six fields in the response.

    • Queries where limit can be used:

      • Geocode

      • Reverse geocode

      • Stop

      • Stops by area

      • Lines

Current versions of the API (changelog):

  • 1_0_0

  • 1_0_1

  • 1_0_2

  • 1_0_3 (prod)

 

1.2 Capacity restriction

The new version of the API has a new feature that makes it possible to restrict abuse of the system. Too many requests in a short time could flood the service and make it unavailable for other users. Capacity restriction limits the amount of requests per hour. Requests are weighted according to the cost that they have on the system. The weights for different requests are as follows:

  • Geocoding = 1

  • Reverse geocoding = 1

  • Stop = 1

  • Validity = 1

  • Stats = 1

  • Lines = 2

  • Stops by area = 2

  • Routing = 3

  • Cycling route = 3

It is possible to check the remaining capacity with a request (api.publictransport.tampere.fi/prod/?request=stats).

 

2 TRE API modules

Every request to TRE API uses HTTP GET. Every request will need request parameter that contains the type of the request.

Modules of TRE API:

  1. Geocoding (request type geocode)

  2. Reverse geocoding (request type reverse_geocode)

  3. Stop information (request type stop)

  4. Stops in area (request type stops_area)

  5. Line information (request type lines)

  6. Routing between two points (request type route)

  7. Cycling route (request type cycling)

  8. Data validity (request type validity)

  9. User statistics (capacity used and available) (request type stats)

The parameters used for the requests and responses are explained in detail in the following chapters.

 

2.1 Geocoding

Geocoding returns the coordinates and the names of the POIs, stops and addresses. Locations have been classified to different categories.

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

 Parameter

Description

Type

key

Search term

String

 cities

List of city names

Optional. List of strings separated by pipe ("|"). E.g. cities=tampere|pirkkala|ylöjärvi. Default all cities.

loc_types

Location types

Optional. List of location types separated by pipe ("|"). E.g. loc_types=stop|address. Default all location types.

 disable_error_correction

Disable levenshtein error correction

 Not supported.

disable_unique_stop_names

Disable unique stop names in the result.

Optional. 1 = all stops are shown in the result, 0 = only one stop is included in the result for stops with same name. Default 1.

 

Response fields:

Field nr.

Name

 Type

Description

1

locType

String

Type of the location: street, address, poi (point of interest) or stop

2

locTypeId

Number

Location type id of the location (1-9 and 11-17 = poi, 10 = stop, 900 = address)

3

name

String

Name of the location.

4

matchedName

String

Name of the location in that was matched with the search key.

5

lang

String

Language of the matched name of the location.

5

city

String

Name of the city the location is in.

6

coords

Coordinate

Coordinates of the location (<x,y>, e.g. 3331406,6823937).

7

details

Array

Detailed information about the location such as houseNumber for addresses, poiClass for POIs and codes,line details for stops.

Below are some search examples:

Sample Request

http://api.publictransport.tampere.fi/prod/?request=geocode&format=xml&key=met

Sample Request with location type

http://api.publictransport.tampere.fi/prod/?request=geocode&format=xml&key=met&loc_types=address

 

2.2 Reverse geocoding

Reverse geocoding searches for a street address, poi or stop closest to a given coordinate. The amount of locations can be limited as well as the radius of the search. Location types can be used to leave out unwanted locations from the result.

 

Parameter

 Description

 Type

 coordinate

 Coordinate

 Coordinates separated by comma (e.g. <x,y>)

 limit

 Limit for the number of locations returned.

 Optional, default 1

 radius

 Radius of the search in meters.

 Optional, default 1000, range 1-1000

 result_contains

 Limit the search to given location types.

 Optional, default all, other values: address, stop and poi.

 

Response fields:

Field nr.

 Name

 Type

 Description

 1

 locType

 String

 Type of the location: street, address, poi (point of interest) or stop

 2

 locTypeId

 Number

 Location type id of the location (1-9 and 11-17 = poi, 10 = stop, 900 = address)

 3

 name

 String

 Name of the location.

 4

 lang

 String

 Language of the name of the location.

 5

 city

 String

 Name of the city the location is in.

 6

 coords

 Coordinate

 Coordinates of the location (<x,y>, e.g. 3331406,6823937).

7

details

Array

Detailed information about the location such as houseNumber for addresses, poiClass for POIs and codes,line details for stops.

 8

 matchedName

 String

 Matched name with search key.

 9

 distance

 Number

 Distance of the location from the requested coordinate.(in meters) 


Sample Request

http://api.publictransport.tampere.fi/prod/?request=reverse_geocode&coordinate=3327335,6825367&limit=30&format=xml

 

2.3 Stops information

Stop request returns information about a given stop identified by its unique code. Information includes names, lines passing the stop, codes, coordinates, accessibility information and departures for a given time range.

 

Parameter

 Description

 Type

 code

 Search term for a stop search.

 Stop's code, stop name or stop address.

 date

 Start date for departure.

 Optional, default current date, YYYYMMDD.

 time

 Start time for departures.

 Optional, default current time, HHMM.

 time_limit

 Time range for returned departures.

 Optional, default 120, max 360 minutes.

 dep_limit

 Limit the number of returned departures.

 Optional, default 10, range 1-20.


Response fields:
 

Field nr.

 Name

 Type

 Description

 1

 code

 Number(4)

 Unique code of the stop, e.g. 4014

 2

 code_short

 Number(4)

 Same as code.

 3

 name_fi

 String

 Name of the stop in Finnish.

 4

 name_sv

 String

 Not supported, empty string returned.

 5

 city_fi

 String

 Name of the city in Finnish.

 6

 city_sv

 String

 Not supported, empty string returned.

 7

 lines

 Array

 Array of lines that pass the stop with their destination, line code and its destination are separated by ": "

 8

coords

 Coordinate

Coordinates of the stop (<x,y>, e.g. 3331406,6823937).

 9

 wgs_coords

 Coordinate

 Longitude and latitude of the stop (WGS84 coordinates, <lon,lat>).

 10

 accessibility

 -

 Not supported, empty string returned.

 11

 departures

 Array

 Next departures leaving from the stop, array of line code, direction, name, departure time and date.

 12

 timetable_link

 String

 Link to the timetable page of the stop.

 13

 omatlahdot_link

 String

 Not supported, empty string returned.

 14

 address_fi

 String

 Not supported, empty string returned.

 15

 address_sv

 String

 Not supported, empty string returned.

 

Sample Request

http://api.publictransport.tampere.fi/prod/?request=stop&code=Vanha&format=xml

 

 

2.3 Stops in area
 

Tampere API can be used to search for stops within a square with a given diameter. Given point is the center of the square. Square’s side is the same as the length of the given diameter in meters..Alternatively it is also used to search for stops within a bbox.

Parameter

 Description

 Type

 center_coordinate

 Coordinate

 Coordinates separated by comma (e.g. <x,y>)

 bbox

 Box coordinates

 Coordinates separated by comma (e.g. <minx,minY,maxX,maxY>)

 limit

 Limit the amount of stops.

 Optional, default 20.

 diameter

 Length of the side of the square.

 Optional, default 1500, max 5000 meters.


Response fields:

Field nr.

 Name

 Type

 Description

 1

 code

 Number(4)

 Unique code of the stop, e.g. 4016.

 2

 name

 String

 Name of the stop.

 3

 city

 String

 City the stop is located in.

 4

 coords

 Coordinate

 Coordinates of the stop (<x,y>, e.g. 3331406,6823937).

 5

 dist

 Number

 Distance of the stop to the center coordinate.

 6

 codeShort

 Number(4)

 Same as code.

 7

 address

 String

 Stop's address.

 Sample Request with center coordinate

http://api.publictransport.tampere.fi/prod/?request=stops_area&center_coordinate=3331810,6823852&diameter=1500&format=xml

 

Sample Request with bbox

http://api.publictransport.tampere.fi/prod/?request=stops_area&bbox=3328253,6823773,3331775,6826815&format=xml

 

2.4 Line information

Information on lines can be fetched with request type lines. The lines can be searched with codes, line names or transport types.

Request Parameters:

Query

 

List of strings

List of query strings separated by pipe ("|"). Strings may be short code or string that will be searched from the name of the line

E.g. query=16 2|Korkinmäki

Transport_type

List of numbers

Optional, List of transport type ids. Default will be 1 (bus)

E.g. transport_type=1

 

Response Parameters:

 

 

Field nr.

Name

Type

Description

1

code

String(7)

Long Code of the line, e.g. 31 1

2

code_short

String

Short code of the line (shown on the bus, e.g. 31)

3

transport_type_id

Number

Transport type of the line. See above (parameter transport_type) for explanation of the codes.

4

line_start

String

Name of the start stop.

5

line_end

String

Name of the end stop.

6

name

String

Name of the line.

7

timetable_url

String

URL of the timetable page for the line.

8

line_shape

List of coordinates

The shape of the line's route as a list of coordinates.

9

line_stops

Array

Array of stops the line passes.

9.1

code

Number(4)

Unique code of the stop, e.g. 4016.

9.2

codeShort

Number(4)

Stop's short code.

9.3

time

Number

Estimated time in minutes it takes for the bus to reach the stop.

9.4

address

String

Not supported, empty string returned.

9.5

name

String

Stop's name.

9.6

coords

Coordinate pair (x,y)

Coordinates of the stop.

9.7

city_name

String

City that the stop is located in.


 

Sample Request

http://api.publictransport.tampere.fi/prod/?request=lines&query=17|Korkinm%C3%A4ki%20-%20Pyynikintori


 

2.5 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 stops with the same name that are located far away from each other

Request Parameters:

Paramter

Type

Description

From

Coordinate

Coordinates separated by comma (e.g. <x,y>).

Via

Coordinate

Optional, coordinates separated by comma (e.g. <x,y>).

To

Coordinate

Coordinates separated by comma (e.g. <x,y>).

Date

Number (8).

Optional, default current date, YYYYMMDD.

Time

Number(4)

Optional, default current time, HHMM.

timetype

String

Time of the request is for "arrival" or "departure". Optional, default "departure".

via_time

Number

Minimum time spent at a via_point in minutes.

Zone

String

 

Optional, default “tampere”. Only one ticket zone is applicable.

transport_types

List of strings separated by pipe ("|")

 

Transport types included in the request.

Optional, default "bus".

mode_cost_<transport_type_id>

Number

Mode costs for different transport types.

Optional. These settings override previous values set with transport_types-parameter.

 

Default mode cost value is ‘1’.

 

optimize

String

Routing profile:

  • default: wait cost=1.0, walk cost=1.2, change cost=6

  • fastest: wait cost=1.0, walk cost=1.0, change cost=0

  • least_transfers:wait cost=1.0, walk cost=1.5, change cost=20

  • least_walking:wait cost=1.0, walk cost=5.0, change cost=6

Optional, default "default" profile.

change_margin

Number

The minimum number of minutes between changes. Optional, default 3, range 0-10.

change_cost

Number

Penalty for a change, user is rather N minutes later at the destination than changes to another vehicle. Optional, default 5, range 1-99.

This parameter overrides the setting from optimize.

wait_cost

Number

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

This parameter overrides optimize parameter

walk_cost

Number

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

This parameter overrides optimize parameter

walk_speed

Number

Walking speed. Optional, default 70 m/min, range 1-500.

Detail

String

Detail level of the response. Optional, default "normal", possible values:

  • "limited" = only legs are returned

  • "normal" = intermediate stops are included

  • "full" = route shape coordinates are included

Show

Number

Number of routes in the response. Optional, default 3, max 5.

 

Response Parameters:

Response is an array of routes. Via routes have two parts in the response. Some fields are available only in full or normal level detail. Below are descriptions for the different fields that the routes (or in case of a via routing, parts of routes) have in the response:

 

Field nr.

Key

Description

String

1

Length

Number

Length of the route in meters

2

duration

Number

Duration of the route in seconds.

3

Legs

Array

Array of legs of the route

3.1

Length

Number

Length of the leg in meters

3.2

duration

Number

Duration of the leg in seconds

3.3

Type

String/Number

Type of the leg:

  • walk

  • transport type id (see parameter mode_cost above for explanation of the ids)

3.4

Code

String

Line code.

3.5

Locs

Array

Array of locations on the leg (limited detail only lists start and end locations).

3.6

Shape

List

Shape (list of coordinates) of the leg (only in full detail)..

3.5.1

Coord

Coordinate

Coordinate of the location

3.5.2

arrTime

Number

Arrival time to the location, format YYYYMMDDHHMM.

3.5.3

depTime

Number

Departure time from the location, format YYYYMMDDHHMM.

3.5.4

Name

String

Name of the location.

3.5.5

Code

Number(4)

Unique code of the stop, e.g. 4014

3.5.6

shortCode

Number(4)

Stop's short code.

3.5.7

stopAddress

String

Not supported, empty string returned.

 

Sample Request:

http://api.publictransport.tampere.fi/prod/?request=route&from=3331356,6822448&to=3331134,6822410&date=20130803&time=0930&optimize=least_transfers&change_margin=8&show=5&detail=full&format=xml

 

2.7 Cycling route

Route search for cycling from coordinate to coordinate. It is possible to use different routing profiles to prefer different types of cycling paths and shortest route.

Request:

Parameter

Description

Type

From

Start point coordinate

Coordinates separated by comma (e.g. <x,y>).

To

Destination point coordinate

Coordinates separated by comma (e.g. <x,y>).

Via

List of via point coordinates

List of coordinates separated by comma (e.g. <x,y>). List members are separated by pipes ("|"). Optional, maximum number of via points is 5.

Profile


String

Optional. Routing profile.

 

kleroweighted = default profile

klerotarmac = prefers cycle paths with tarmac

klerosand = prefers gravel paths

kleroshortest = prefers shortest route

 

elevation

0 or 1.

Optional, default value 0. If 1, elevation information of the route will be shown in the result.

 

Response:

Field nr.

Name

Type

Description

1

length

Number

Length of the whole route in meters.

2

path

List

List of parts of the route.

2.1

length

Number

Length of the part in meters.

2.2

name

String

Name of the area the part of the route is in.

2.3

type

String

Paving type of the part of the route:

  • gravel

  • tarmac

  • unknown

 

2.4

points

List

List of coordinates <x,y> the part of the route consists of. If elevation is shown format is <x,y,z>

2.5

passtype

String

Not supported, empty string returned.


 

Sample Request:

http://api.publictransport.tampere.fi/prod/?request=cycling&from=3331356,6822448&to=3331134,6822410&format=xml


 

2.8 Validity

It is possible to check the date range of valid data that is in use in the API. No additional url-parameters are needed (just request=validity and authentication).

Response:

 

Field nr.

 Name

 Type

 Description

 1

 from

 Date

 Date from which the data is valid.

 2

 to

 Date

 Date to which the data is valid.


 

2.9 Statistics

Used and available capacity can be checked with a request. No additional parameters are needed (apart from request=stats and authentication).

Response:

Field nr.

 Name

 Type

 Description

 1

 max

 Number

 Maximum capacity.

 2

 used

 Number

 Used capacity.


 

3 Changelog

  • Changes in version 1_0_3:

    • Default response format is now JSON instead of text.

  • Changes in version 1_0_2:

    • All stops' code and shortCode fields include now prefix zeros if stop code is less than four numbers long (e.g. stop code 40 is 0040).

  • Changes in version 1_0_1: 

    • Changed boundary coordinates (bbox) to following format bbox <minX,minY,maxY,maxY>.
    • Filtering with URL parameter p doesn't skip empty fields anymore.
    • Lines array of stop response doesn't have same line twice anymore.
    • Lines response doesn't have same line twice anymore.
    • Direction information and line name has been added to departure array in stop response.
    • Departures array of stop response doesn't have arriving busses on line end stops.
    • Lines search can be filtered also with direction information (e.g. request=lines&query= 16 1).
    • Timetable link in stop response has been fixed.