Transport Server.

home

:

Developer information

Connecting to the services

The Transport Server services accessed as a REST service. Each service is accessible through the URL:

http://www.cl.cam.ac.uk/research/dtg/transport/SERVICE_NAME

where 'SERVICE_NAME' is replaced with the service name, given below. The services should be accessed through HTTP GET, and parameters passed in the query string.

API key

To allow us to control access to Transport Server during these early stages, you will request an API key to access the services. See here for information on acquiring a key.

What you can do with Transport Server

Transport Server allows developers to:

How the data is structured

Every point at which you may board public transport in the UK is loaded into Transport Server. This means that in many cases what a passenger will see as one logical bus stop is often represented by many entities in our database (two points across the road from each other, or one point for each bay in a bus station).

To combat this problem all bus stops, where data was available, have been grouped into stop gGroups. This is the entity a passenger knows as a 'bus stop', with the individual boarding stop points within a stop group being a distinction only your application should make internally.

FindStopGroups

URL: .../FindStopGroups

What does it do?

Returns all stop groups matching the given criteria.

Parameters

Two modes of query: either search for stops near a certain point or return stops within a bounding box.

Find stop groups near a given point:

key
Your API key (required)
method
Set to 'near' for this mode (required)
lat
Latitude of given point (required)
long
Longitude of given point (required)
numresults
How many results to return (optional, default = 20)
radius
A nominal radius to search within from the given point. A value of 10,000 is roughly 10km although since all calculations are on a lat/long grid inaccuracy will occur - we suggest you overstate your radius somewhat (but don't set this to incredibly high values - the radius culling is essential to making your query fast!) (optional, default = 10,000 ~ 10km search radius)

Example:

FindStopGroups?key=KEY&method=near&lat=52.2&long=0.09&numresults=30&radius=5000

Find stop groups within a bounding box: Note: a maximum of 10,000 stops groups will be returned by this method. If you require wider coverage, please break up your query

key
Your API key (required)
method
Set to 'within' for this mode (required)
left / top / right / bottom
latitude (top, bottom) and longitude (left, right) values which define the bounding box within which you want to search for stop groups. (required)

Example (all bus stops in the village of Coton):

FindStopGroups?key=KEY&method=within&left=0.051241&bottom=52.204910&right=0.073557&top=52.212537

Sample XML response

<response>
  <groups>
    <group>
      <ref>050GLN005008</ref>
      <name>The Ridgeway</name>

      <lat>52.0947230781</lat>
      <long>0.2944719285</long>
      <dist>907.97751117876408</dist>
    </group>

    ...

  </groups>
</response>

The response is fairly self-explanatory with each group listed with it's group reference, name, positional information and distance in metres from the point that was passed (if method was set to 'near').

ListStopPoints

URL: .../ListStopPoints

What does it do?

Takes a group reference and lists all stops that belong within this group. For example, a group may contain just one stop, two stops if the group represents a pair of stops either side of a road, or many stops if the group represents an feature such as a bus station.

Parameters

key
Your API key (required)
groupref
The group reference for the stop group in question (required)
Example (Drummer St Bus Station, Cambridge): 
ListStopPoints?key=KEY&groupref=050GCC000000

Sample XML response

<response>
  <stops>
    <stop haslivedata="true">
      <atco>0500CCITY419</atco>
      <naptan>cmbdgdma</naptan>

      <location>
        <lat>52.2014817002</lat>
        <long>0.1185535098</long>
        <street>Trumpington Street</street>

        <landmark>Pembroke Street</landmark>
        <indicator>near</indicator>
      </location>
      <naming>
        <common>Pembroke Street</common>

        <short>Pembroke Street</short>
      </naming>
      <direction>SE</direction>
    </stop>

    ...

  </stops>
</response>
haslivedata
whether the stop has live arrival information available
atco
the ATCO code for the stop - a nationwide unique ID for this stop
naptan
the NaPTAN code for the stop - unique ID for the stop however some stops don't have a NaPTAN code. This is often quoted as the 'SMS code' for the stop.
location
lat/long
position of the individual stop
street
the street the stop is on
landmark
a landmark that can be used to locate the stop
indicator
how the stop relates to the landmark
naming
common
the standard name for the stop
short
a shorter name for the stop - sometimes not available
direction
the direction the stop faces

GetArrivals

URL: .../GetArrivals

What does it do?

Takes the ATCO code for a stop and returns a list of bus services due to arrive at that stop.

Parameters

key
Your API key (required)
atco
ATCO code for the stop in question (required)
numarrivals
The maximum number of arrivals to return (fewer may be returned if those are all that are available) (optional, default value = 5)
Example: 
GetArrivals?key=KEY&atco=0500CCITY111

Sample XML response

<response>
    <arrivals count="5">
      <arrival>
        <service>99</service>
        <destination>City & The Grafton</destination>

        <time>
          <millis>1250260560580</millis>
          <textual>8 mins</textual>
          <isdue>false</isdue>

          <islive>false</islive>
        </time>
      </arrival>

    ...

    </arrivals>
</response>
count
how many arrivals were returned
service
the service number for this particular arrival
destination
the ultimate destination for the bus
time
millis
UNIX timestamp (milliseconds since 1970) representing when the bus is estimated to arrive
textual
textual representation of the bus arrival time
isdue
whether the bus is now due (will arrive imminently)
islive
whether this timing information was provided by live data ('true') or timetable data ('false')

LookupStop

URL: .../LookupStop

What does it do?

Takes the ATCO / NaPTAN code for a stop and returns extended stop info.

Parameters

key
Your API key (required)
atco
ATCO code for the stop in question (required if naptan not specified)
naptan
NaPTAN code for the stop in question (required if atco not specified)
Example: 
LookupStop?key=KEY&naptan=cmbdajdm
	
or
	
LookupStop?key=KEY&atco=0500CCITY111

Sample XML response

<response>
  <stop haslivedata="true">
    <atco>0500CCITY419</atco>
    <naptan>cmbdgdma</naptan>
    <location>

      <lat>52.2014817002</lat>
      <long>0.1185535098</long>
      <street>Trumpington Street</street>
      <landmark>Pembroke Street</landmark>

      <indicator>near</indicator>
    </location>
    <naming>
      <common>Pembroke Street</common>
      <short>Pembroke Street</short>

    </naming>
    <direction>SE</direction>
  </stop>
</response>

see ListStopPoints