Reittiopas
PHP API

A while ago Helsinki Regional Transport Authority (HSL) opened up their Reittiopas / Journey planner interface for development and test use.

Introduction

Journey planner interface offers access to all modes of public transportation information in Helsinki metropolitan area. Interface contains geocoding, reverse geocoding, routing and stop timetable services.

 

PHP API wraps Reittiopas API's HTTP Get interface to more easy to approach OOP-model. The implementation builds on top of Zend Framework, more precisely on top of Zend_Http_Client.

 

The PHP Api implements all the modules of the current Reittiopas API. Implementation includes geocoding, reverse geocoding, routing and stop timetable modules of Reittiopas API. This implementation accepts coordinates in WGS 84 latitude-longitude (WGS 84 is the reference coordinate system used by the GPS) as well as in finnish KKJ coordinate system. Coordinate system conversion is based on work by Olli Lammi and Matti Aarnio, Viestikallio.

 

Requirements

First you need a developer account to Reittiopas API. You can apply for an account in here. You also need PHP version 5.2.x or greater and Zend Framework 1.7 or greater.

 

Usage

 

Setting up

<?php 

// Point include path to Zend framework and Nordkapp_Service_Reittiopas -classes
set_include_path('../library');
// include service class or use autoloader
require_once 'Nordkapp/Service/Reittiopas.php';
// Use your login + password to initialize service. Constructor also accepts
// third parameter charset (defaults to UTF-8), Reittiopas uses ISO-8859-1 by default
$service = new Nordkapp_Service_Reittiopas($apiUsername, $apiPassword);

Searching for locations

Search returns array of locations. Location can be stop, street or point of interest.

// Search-method returns array of Nordkapp_Service_Reittiopas_Location -objects
if ($locations = $service->search('Kalevankatu 3, Helsinki')) {
	foreach ($locations as $location) {
		// Coordinates in latitude-longitude
		$latLng = $location->getLatLng();
		// Coordinates in KKJ (Nordkapp_Service_Reittiopas_Point)
		$point = $location->getPoint();
		// Location parameters, available parameters depend on location type
		$name = $location->name;
		$number = $location->number;
		$city = $location->city;
		$address = $location->address;
		// type is POI, STREET or STOP
		$type = $location->type; 
		// ...
	}
}

Reverse geocoding

Nordkapp_Service_Reittiopas::getStreetAddress() -method returns nearest address for given coordinate. Method accepts coordinates in KKJ or WGS84 (Nordkapp_Service_Reittiopas_Point or Nordkapp_Service_Reittiopas_LatLng -objects). 

// getStreetAddress-method returns Location-object if found
$latLng = new Nordkapp_Service_Reittiopas_LatLng(60.168178, 24.940232); 
if ($location = $service->getStreetAddress($latLng)) {
	$address = $location->address;
	$number = $location->number;
	$city = $location->city;
	// ...
}

Closest stops

Get closest stops -method return nearest stops in given radius. Method accepts coordinates in KKJ or WGS84 (Nordkapp_Service_Reittiopas_Point or Nordkapp_Service_Reittiopas_LatLng -objects). Method accepts three parameters: coordinate, radius in meters (optional, defaults to 200m) and returnStopNames boolean (optional, defaults to false). Note if the third parameter is true, service makes additional request for each stop to retrieve name and address of the stop. By default Reittiopas API only returns stop codes, coordinates and distances from given position. 

$latLng = new Nordkapp_Service_Reittiopas_LatLng(60.168178, 24.940232); 
// Returns array of Location-objects.
if ($stops = $service->getClosestStops($latLng)) {
	foreach ($stops as $stop) {
		$latLng = $stop->getLatLng();
		$code = $stop->code;
		$distance = $stop->distance;
	} 
}

Stop timetable

Nordkapp_Service_Reittiopas::getStopTimetable() method returns departures from certain stop. Method accepts three parameters: stop code, departure date (YYYYMMDD) and time (HHMM). Departure date and time default to current date/time if parameters are not given. 

if ($data = $service->getStopTimetable('1040443')) {
	// stop name
	$name = $data['name'];
	// stop address
	$address = $data['address'];
	// stop city
	$city = $data['city'];
	foreach ($stop['departures'] as $departure) {
		// departure time HH:MM
		$time = $departure['time'];
		// Line name
		$line = $departure['line'];
		// Line code
		$code = $departure['code'];
		// Line destination
		$destination = $departure['destination'];
	}
}

Routing

Nordkapp_Service_Reittiopas::getRoutes() method returns array of Route-objects from location A to location B. Method accepts three parameters: from and to locations and additional options. Locations can be given as Location, LatLng or Point objects. Additional options array contains date, time, route optimization, transfer margin etc. variables. Options are described in Routing section of Reittiopas documentation.

 

By default method returns next three route options. Route-object contains from and to locations and also route distance and duration parameters. Each route may contain several Route_Part-object. Route parts contain type (walking, line) and parameters in addition to from/to -locations and distance and duration parameters. Each route part is divided into locations; stops for trasport lines, map locations for walking routes. 

// Search for from and to locations
$fromArray = $service->search('Kalevankatu 3, Helsinki');
$toArray = $service->search('Linnanmäki, Helsinki');
if (isset($fromArray[0]) && isset($toArray[0])) {
	$routes = $service->getRoutes($fromArray[0], $toArray[0]);
	if ($routes[0]) {
		$route = $routes[0];
		$from = $route->getFrom();
		$to = $route->getTo();
		echo 'From: ' . $from->name . ' at ';
		echo $from->getDepartureDate('H:i') . "\n";
		echo 'To: ' . $to->name . ' at ' . $to->getArrivalDate('H:i') . "\n";
		echo 'Route length ' . $route->getDistance() . ' meters, duration ';
		echo $route->getDuration() . " minutes.\n";
		// iterate route parts
		foreach ($route as $part) {
			if ($part->isWalking()) {
				// walking
				// ...
			} else {
				// transport line
				$type = $part->type; // helsinki_bus, helsinki_tram, regional,... 
				// ...
			}
			// iterate route part locations/stops
			foreach ($part as $location) {
				$latLng = $location->getLatLng();
				if ($location->type == 'STOP') {
					$stopName = $location->name;
					// ...
				}
			}
		}		
	}
}

 

Download

You can grab the latest version of the Reittiopas PHP API from here. Code is licensed under MIT license.

Reittiopas PHP API 0.8 (released February 7, 2010)

 

For more info contact Aki Happonen (aki at nordkapp.fi).

 

Todo

  • Line code in routing to line "title" (eg. code 1072 => title 72)
  • Option validation
  • Better error handling
  • ...