• Quote
• Contact Us
• FAQ

API Documentation

More help can also be found on the mailing list. The examples and documentation assume a basic working knowledge of variously, image magick, ruby, Javascript, JSON, unix and XML.

Create an account

The first step is to get a login and API key, so create an account to get started.

Data

Data available for each courier is

• type - one of van, large van, motorbike, large motorbike or pushbike
• id - unique amongst a type
• latitude, longitude - vehicles position in WGS84
• timestamp - time at which the location was given
• heading - compass bearing
• speed - speed in meters/sec

Javascript API

The Javascript API emits JSON and then a callback to your application. The form of a API is

http://api.ecourier.co.uk/jsapi/API_VERSION/API_KEY/courier/FUNCTION

0.1 is the current API version, subject to change. Your API key is found under your api account page, and the call made here is to find the current position of the couriers. In order to work you must set up a referrer for your site, again this can be found under your account page. This referrer is the location of the http site where you will be making API requests. The emitted code looks like the example below:

couriers = [ { 'id' : '02', 'type' : 'van',
              'lng' : -0.1942283333, 04, 
              'timestamp' : 'Mon Jan 23 18:37:32 +0000 2006',
              'heading' : 76.12, 'speed' : 0.0 }
             [..]
           ];
handle();

This sets a couriers object as an array of courier objects which have various properties. It then calls handle() as a callback for your code to deal with the data. If the key or referrer are not found a javascript alert() will be called with an appropriate error. For example if no referrer is given then the following is emitted:

alert('eCourier error: no referrer found');

XML API

The XML API is similar to the javascript one, but it emits XML and requires a password for authentication rather than http referrer. The URLs are of the form

http://api.ecourier.co.uk/xmlapi/API_VERSION/API_KEY/PASSWORD/courier/FUNCTION

Again, the current API version is 0.1. The API_KEY is found in your account settings and the PASSWORD is your login password which you should keep secret. Like the javascript API there are two functions. The data is given in the form

<?xml version="0.1" encoding="UTF-8"?>
  <couriers version="0.1">
  <courier id="02" type="van"
  longitude="-0.1942283333" latitude="51.51204"
  timestamp="2006-01-23T18:37:32+00:00" heading="76.12" speed="0.0"/>
  [..]
</couriers>

with a courier node per data instance. You should not rely on all attributes being available as your user account may be restricted from retrieving certain information. Note that there will not normally be a line break within the courier node, this is just to fit it on the page.

Functions

Currently there are two functions which allow you access to the courier data:

• current - Gives you the current location of all couriers. May be time-delayed based on your user account.
• time_range/start_time/end_time/ - Gives you the location of all couriers within a time range up to a maximum of 5,000 data points. This may be extended by giving a ?page=n on to the URL where n in an integer. Each page gives a successive 5,000 data points.