HTTP Get interface

1 Instructions

1.1 General

Reittiopas API is located in the following address.

http://api.reittiopas.fi/hsl/prod/

The API server has the most recent timetable data provided by HRT. 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 weekly. This does not affect the functioning of the service.

• 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/hsl/prod/?user=<username>&pass=<password>
  • Authentication parameters are excluded from the examples below for the sake of clarity.
• 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 2392 (KKJ2, default), 2391 (KKJ1), 2393 (KKJ3), 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], default value is fi.
  • N.B. mostly only points of interest have their names in all languages, stops and addresses have their names only in Finnish and Swedish.
• Lists as parameter values are separated with pipes ("|"), e.g. transport_types=bus|metro|train.
• 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_1_0.
    • E.g. api.reittiopas.fi/hsl/1_1_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.reittiopas.fi/hsl/beta/?request=...
  • Production version will be available at api.reittiopas.fi/hsl/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_1_1
• 1_1_2
• 1_1_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.reittiopas.fi/hsl/?request=stats).

1.3 Reittiopas API modules

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

Modules of the Reittiopas 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.
 

1.4 Geocoding

Geocoding returns the coordinates and the names of the POIs, stops and addresses. The search uses the same logic as the Reittiopas www-service. 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.

Response fields:

Below are some search examples:

1. A search that returns locations from all categories:
   • api.reittiopas.fi/hsl/prod/?request=geocode&key=tee
2. A search that returns a single stop (as there should be only one result found with the search term):
   • api.reittiopas.fi/hsl/prod/?request=geocode&key=teekkarik
3. If the search term includes a digit, the search is done mainly for streets:
   • api.reittiopas.fi/hsl/prod/?request=geocode&key=tee+3

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

Response fields:

Below are some search examples:

1. A search for the nearest address for the coordinates given:
   • api.reittiopas.fi/hsl/prod/?request=reverse_geocode&coordinate=2546445,6675512

1.6 Stop 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.

Response fields:

Accessibility fields:

Below are some search examples:

1. A search for a stop with a code:
   • api.reittiopas.fi/hsl/prod/?request=stop&code=2222222

1.7 Stops in area

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

Response fields:

Sample request:

api.reittiopas.fi/hsl/prod/?request=stops_area&center_coordinate=2558009,6685216&radius=100

1.8 Line information

Detailed information on lines can be fetched with request type lines. The lines can be searched with JORE codes, short codes, parts line names or transport types. Parameter query must be set in all queries.

Response fields:

Sample request:

api.reittiopas.fi/hsl/prod/?request=lines&query=2102T 1|14|Tapiola&transport_type=1|3

1.9 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 (for example the stop “Sturenkatu” in Helsinki).

Response is an array of routes. Via routes have two parts in the response. Some fields are available only in full or normal level od 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:

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.
   • api.reittiopas.fi/hsl/prod/?request=route&from=2546445,6675512&to=2549445,6675513
2. A search done when the user wants to reach the destination at a certain time.
   • api.reittiopas.fi/hsl/prod/?request=route&from=2546445,6675512&to=2549445,6675513&time=1030&timetype=arrival

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

Response:

1. A sample search that includes only coordinates.
   • api.reittiopas.fi/hsl/prod/?request=cycling&from=2546445,6675512&to=2549445,6675513
2. A search with a tarmac preferring routing profile and two via points.
   • api.reittiopas.fi/hsl/prod/?request=cycling&from=2546445,6675512&to=2549445,6675513&via=2543445,6674512|2548445,6674513&profile=klerotarmac

1.11 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:

1.12 Statistics

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

Response:

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 and points should be parsed from the response. 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 HSL.

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

36 Kirkkonummi internal

38 Sipoo internal

39 Kerava internal

(types 9,10,11,13,14 are not used in the data)

3 Changelog

• Changes in version 1_1_3:

  • Cycling search now includes information about the route’s elevation (shown with parameter elevation=1), overpass/underpass information and paving type (gravel/tarmac). 
  • Results containing stop information now include more information (e.g. stop name and address, short code, coordinates) about the stop (route, lines, geocode, reverse geocode, stop and stops area request types).
  • Stops can be searched with names and stop addresses (request type stop).
  • Trains can be found with route characters with the line search (e.g. query=M for M-train).
  • Format “txt” can be used to show the query results in more human readable format. It can be used for testing the queries in a browser for example. 

• Changes in version 1_1_2:

  • default time used in stop-request was not correctly formed which resulted in strange departures in the response.
  • stop-responses are now only stored in the internal cache of the API for one minute so that old departures in the response are no longer an issue.
  • stop-request accepts short codes for all cities.
  • geocode-response no longer includes house number in the matchedName-field for addresses (this update was done for the name-field previously)
  • geocode-request now accepts “/” in the key-parameter
  • geocode-requests with keys starting with nordic letters (å, ä, ö) are now working correctly.
  • route-response now includes stop codes in the locs-array.
  • excess quotation marks (“) are now stripped from JSON cycling-response.

• Changes in version 1_1_1:

  • All numeric values in the responses no longer have quotation marks (“) around them. 
  • In geocoding response:
    • New field “matchedName” added (this contains the name that the search key matched to, field “name” contains the name in selected language).
    • Field “lang” contains the language of the matched name.
    • Field “name” does not any longer contain the city name. This can be found in the field “city”.
    • Field “details” for stop locations contains field “lines” which from now on has the lines bypassing the stop in an array instead of a string.
  • In reverse geocoding response:
    • Field “details” for stop locations contains field “lines” which from now on has the lines bypassing the stop in an array instead of a string.
  • In stop information response:
    • The departures search has been improved around midnight:
      • In addition to searching for departures after “YYYYMMDD HHMM” also “YYYYMMDD+(1 day) HHMM-(24 hours)” and “YYYYMMDD-(1 day) HHMM+(24 hours)” will be searched.
      • This will return departures for a search “20110202 2401“ also starting from “20110203 0001” and departures for search “20110203 0001” also starting from “20110202 2401”.
      • In addition to fields “code” and “time” also “date” of the departure is included in the departures array.
    • Field “lines” from now on has the lines bypassing the stop in an array instead of a string.
    • Coordinates are now in one field “coords” (format “X,Y”) and WGS84 coordinates in field “wgs_coords” (format “longitude,latitude”).
    • Field “timetable_link” with a link to a timetable page has been added.
    • Field “omatlahdot_link” with a link to Omat lähdöt service has been added.
  • In stops area response:
    • Coordinates are now in one field “coords” (format “X,Y”).
    • Field “city” has been added.