Open data
 
Open data API HTTP Get Interface
 

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. The timetable data is updated weekly. This does not affect the functioning of the service.

  • The use of the interface requires a usertoken and a 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 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, use the links below to access version specific instructions):

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 version specific instructions.