API Reference


Check out these pages for API documentation and examples.

Bus information London Underground information Train information Public Journey Planner information Private Journey Planner information

Specification

Protocols and Request Methods

All API methods can be accessed either via HTTP or HTTPS.

All API methods are accessed as GET requests.

Response formats

Data is typically accessed in json or jsonp formats, with urls ending with a ".json" extension. For jsonp you would also pass a 'callback' parameter to specify your callback function name (called with the data payload).

Additionally most methods support html as a response format. A formatted HTML view of the data can normally be accessed by swapping the extension to ".html". Where no format extension is specified in the request, html will be used by default.

The HTML representations contain hyperlinks forming a browseable website. This can be a good way to explore the data and discover URL parameters, although the formatting and functionality is stripped down. This is a deliberate design with the aim of providing developers with a Content API

Check the individual documentation for each method to see which formats are supported, and the structure of json responses.

Documentation conventions

  • Curly brackets { } indicate a required item;
  • Square brackets [ ] indicate an optional item.

For example for the endpoint:

http://fcc.transportapi.com/v3/uk/tube[.format]

format is optional

Content API look and feel

Most endpoints in the API have the option of returning HTML. This is the default if no format is specified. HTML transport content may be requested explicitly by adding a html suffix to requests. Various style, navigation, and linking options for the content can be customised using HTTP parameters.

Head and style

By default, a content page will be a full HTML page with head tags, and will reference a stylesheet, but developers may wish to switch off these elements to receive a more raw unstyled HTML fragment

  • include_head=false will return a fragment of HTML with no enclosing HTML or BODY tags, and no head. include_head=true is the default - which returns a full HTML page

  • include_css=false will return a full HTML page with BODY tags and a HEAD, but with no reference to a stylesheet;

Various pages of the content API are grouped under menus to form a full website, but again developers can switch these elements off

  • navigation_menu=false will remove the top level navigation menu;

  • other_modes_menu_link=false will remove the 'All Modes' link in the navigation menu, that allows users to browser to other modes of transport.

The manner in which links (<a href="...">) are generated in the HTML content can be controlled using the link_style parameter

  • link_style=browsable is the default. Relative links are generated, and various parameters are retained from the incoming request. This includes the above head/style/navigation display options and also authentication parameters. The result is that a user can browse around the API content directly. The content API is in effect a conventional browsable website.

  • link_style=none means no links are output. The display text of links are output, but with no wrapping <a> tags.

  • link_style=relative_path results in conventional relative links, but without retaining extra URL parameters.

  • link_style=placr.mobi causes all links to point the placr.mobi, which displays a public facing mobile-ready demonstration website, with API content.

  • link_style=template will result in the string "{BASE}" at the beginning of all URLs. Developers can match on this string and substitute their own URL base (relative or absolute) in its place

Bus information

Functions for accessing bus information, including nearby stations and departures.

Live Bus Departures

Live bus departures data at a specific stop.

http://fcc.transportapi.com/v3/uk/bus/stop/{atcocode}/live[.format]?[group=route/all][&nextbus=no]
  • Supported formats: html (default) or json.
  • atcocode is the bus stop atco code.
  • If group = route, the departures are grouped by route (this is the default).
  • If group = no, then all departures are placed together in one "all" group.
  • If nextbuses = no, we prevent use of NextBuses data.

Response

Json response format is

{"atcocode","smscode","request_time","departures" 
    {
        [
            {"mode","line","direction","operator","aimed_departure_time","expected_departure_time","best_departure_estimate","source"},
            ...
        ],
        ...
    }
}

Where

atcocodebus stop's atcocode
smscodebus stop's sms code
request_timetime the request to the API was made
departuresarray of departures from the stop
modemode of transport (bus)
lineline id
directiondirection
operatorbus operator id
aimed_departure_timetimetabled departure time (if known)
expected_departure_timeLive data. A prediction of when the bus will depart (if a live feed is available)
best_departure_estimateexpected departure time if known, else the timetabled departure time.
sourcesource of the data (e.g. next buses, countdown, timetables).

Live bus data is not available for all stops. This operation will make use of different live data sources including nextbus and TfL countdown, to bring you a consistently formatted response with the best live data available, or fallback to timetable. The results can be ordered by time or grouped by bus route

For bus stops outside of London, the NextBuses datasource will be used. This is a more expensive source and the charge is adjusted to 10 hits per request to reflect this. If you wish to avoid this hit charge and use only the other data sources, add a nextbuses=no parameter.

Example

http://fcc.transportapi.com/v3/uk/bus/stop/490015209D/live.json?group=route
{
    "atcocode":"490015209D",
    "smscode":"73861",
    "request_time":"2013-10-18T11:59:02+01:00",
    "departures":{
        "271":[
            {"mode":"bus",
             "line":"271",
             "direction":"Highgate Vill",
             "operator":"TFL",
             "aimed_departure_time":null,
             "expected_departure_time":"12:02",
             "best_departure_estimate":"12:02",
             "source":"Countdown instant"
             },    
             {"mode":"bus",
              "line":"271",
              "direction":"Highgate Vill",
              "operator":"TFL",
              "aimed_departure_time":null,
              "expected_departure_time":"12:10",
              "best_departure_estimate":"12:10",
              "source":"Countdown instant"
              },
             {"mode":"bus",
              "line":"271",
              "direction":"Highgate Vill",
              "operator":"TFL",
              "aimed_departure_time":null,
              "expected_departure_time":"12:18",
              "best_departure_estimate":"12:18",
              "source":"Countdown instant"
             }
         ],
         "214":[
             {"mode":"bus",
              "line":"214",
              "direction":"Highgate Vill",
              "operator":"TFL",
              "aimed_departure_time":null,
              "expected_departure_time":"12:05",
              "best_departure_estimate":"12:05",
              "source":"Countdown instant"
             },
             {"mode":"bus",
               "line":"214",
               "direction":"Highgate Vill",
               "operator":"TFL",
               "aimed_departure_time":null,
               "expected_departure_time":"12:13",
               "best_departure_estimate":"12:13",
               "source":"Countdown instant"
              },
              {"mode":"bus",
               "line":"214",
               "direction":"Highgate Vill",
               "operator":"TFL",
               "aimed_departure_time":null,
               "expected_departure_time":"12:22",
               "best_departure_estimate":"12:22",
               "source":"Countdown instant"
              }
         ]
    }
}

Timetable bus stop departures

Timetable data at a specific stop. This shows what buses are scheduled to be departing from the specified bus stop in the coming hour. It is like a live departures board, but based on timetable data

http://fcc.transportapi.com/v3/uk/bus/stop/{atcocode}/timetable[.format]?{group=}
http://fcc.transportapi.com/v3/uk/bus/stop/{atcocode}/{date}/{time}/timetable[.format]?{group=}
  • Supported formats: html (default) or json.
  • atcocode is the bus stop atco code.
  • date the date of interest in yyyy-MM-dd format e.g. '2013-08-24'
  • time the time of interest in 24 hour clock with a colon e.g. '06:26'
  • If group = route, the departures are grouped by route (this is the default).
  • If group = no, then all departures are placed together in one "all" group.

Date and time are optional parameters, but currently when these are left out we redirect to a URL with the current date and time. Transport API may decide to redesign this so that it presents current information without redirecting. Your feedback on this is welcome.

Response

Json response format is

{ 
 "atcocode":atcocode,
 "smscode":smscode,
 "request_time":request time,
 "departures":
 {   
    "line number/all":[
        {
           "mode":"mode",
           "line":"line number",
           "direction":"direction",
           "operator":"operator",
           "aimed_departure_time":"aimed departure time",
        "source":"source"
         },
           //...more buses on this line...
     ],
     //..."next line number":[...{...}]
  }
}

Where

atcocodebus stop's atcocode
smscodebus stop's sms code
request_timetime the request to the API was made
departuresarray of departures from the stop
modemode of transport (bus)
lineline id
directiondirection
operatorbus operator id
aimed_departure_timetimetabled departure time
sourcesource of the data. For bus timetables this is generally 'Traveline'.

Example

http://transportapi.com/v3/uk/bus/stop/490001298E/2013-08-08/16:26/timetable.json
{
  "atcocode": "490001298E",
  "smscode": "50055",
  "request_time": "2013-08-08T16:26:00+01:00",
  "departures": {
    "2": [
      {
        "mode": "bus",
        "line": "2",
        "direction": "Marylebone (Marylebone)",
        "operator": "LONDONBUS",
        "aimed_departure_time": "16:31",
        "source": "Traveline"
      },
      {
        "mode": "bus",
        "line": "2",
        "direction": "Marylebone (Marylebone)",
        "operator": "LONDONBUS",
        "aimed_departure_time": "16:38",
        "source": "Traveline"
      }
    ],
    "432": [
      {
        "mode": "bus",
        "line": "432",
        "direction": "Brixton (Brixton)",
        "operator": "LONDONBUS",
        "aimed_departure_time": "16:29",
        "source": "Traveline"
      }
    ]
  }
}

Nearby stops

Find bus stops close to a given (lon,lat), ordered by distance.

http://transportapi.com/v3/uk/bus/stops/near[.format]?{lon=&lat=}[&page=][&rpp=]
  • Supported formats: html (default) and json
  • lat and lon define the point around which you want to search
  • rpp is the number of results per page to return (25 by default, and capped at 25)
  • page is the result page to return (1 by default). rpp and page together are useful for paging through long lists of results.

Example URLs

http://transportapi.com/v3/uk/bus/stops/near.html?lon=-0.102323&lat=51.527789
http://transportapi.com/v3/uk/bus/stops/near.json?lat=51.527789&lon=-0.102323&page=3&rpp=10

Response

Json response format is:

{"minlon","minlat","maxlon","maxlat","searchlon","searchlat",
 "page","rpp","total","request_time","stops":
  [
   {"atcocode","smscode","name","mode","bearing","locality","indicator",
    "longitude","latitude","distance"},
   {...}, ...
  ]
}

Where

min/max lat/lonis the bounding box of the search
search lat/lon is the point used to sort the stops (nearest first)
page and rpp are as described above
total the total number of stops within the bounding box
requesttime when the request was made
stops an array of stops, sorted by distance from _search lat/lon with attributes…
atcocode is the bus stop's atcocode
smscode is the bus stop's sms code
name the name of the stop
mode the mode of transport
bearing the cardinal direction of departures from this stop
locality a stop region description
indicator more stop detail
longitude/latitude the stop location
distance in metres from search lat/lon

Stops within bounding box

Essentially the same as nearby stops, but the search parameters are a bounding box, rather than a single point.

http://transportapi.com/v3/uk/bus/stops/bbox[.format]?{minlon=&minlat=&maxlon=&maxlat=}[&page=][&rpp=]
  • Supported formats: html (default) and json
  • The remaining HTTP parameters have the same meaning as for nearby stops.

Example

http://transportapi.com/v3/uk/bus/stops/bbox.json?minlon=-0.0938&minlat=51.5207&maxlon=-0.074&maxlat=51.5286&page=3&rpp=8

The json response format is identical to nearby stops.

Tube information

Endpoints for train information, including nearby stations, timetabled and live services.

List tube lines

A homepage for the London Underground network, returning a list of tube lines.

http://fcc.transportapi.com/v3/uk/tube[/lines][.format]
  • Supported format currently just html (default)

Examples

http://fcc.transportapi.com/v3/uk/tube.json

Response

{
  "request_time": "2014-12-10 17:42:21 +0000",
  "lines": {
    "bakerloo": {
      "friendly_name": "Bakerloo",
      "status": "Good service"
    },
    "central": {
      "friendly_name": "Central",
      "status": "Good service"
    },
    "circle": {
      "friendly_name": "Circle",
      "status": "Good service"
    },
    "district": {
      "friendly_name": "District",
      "status": "Good service"
    },
    "hammersmith": {
      "friendly_name": "Hammersmith & City",
      "status": "Good service"
    },
    "jubilee": {
      "friendly_name": "Jubilee",
      "status": "Good service"
    },
    "metropolitan": {
      "friendly_name": "Metropolitan",
      "status": "Good service"
    },
    "northern": {
      "friendly_name": "Northern",
      "status": "Good service"
    },
    "piccadilly": {
      "friendly_name": "Piccadilly",
      "status": "Good service"
    },
    "victoria": {
      "friendly_name": "Victoria",
      "status": "Good service"
    },
    "waterlooandcity": {
      "friendly_name": "Waterloo & City",
      "status": "Good service"
    },
    "dlr": {
      "friendly_name": "DLR",
      "status": "Good service"
    }
  },
  "status_refresh_time": "2014-12-10 17:41:09 +0000"
}
http://fcc.transportapi.com/v3/uk/tube.html
http://fcc.transportapi.com/v3/uk/tube/lines

Nearby stations

Find stations close to a given (lon,lat), ordered by distance.

http://fcc.transportapi.com/v3/uk/train/stations/near[.format]?{lon=&}{lat=}[&page=][&rpp=]
  • Supported formats: html (default) and json
  • lat and lon define the point around which you want to search;
  • rpp is the number of results per page to return (25 by default, and capped at 25);
  • page is the result page to return (1 by default). rpp and page together are useful for paging through long lists of results.

Example URLs

http://fcc.transportapi.com/v3/uk/train/stations/near.html?lon=-0.102323&lat=51.527789
http://fcc.transportapi.com/v3/uk/train/stations/near.json?lat=51.527789&lon=-0.102323&page=3&rpp=10

Response

JSON response format is:

{"minlon","minlat","maxlon","maxlat","searchlon","searchlat","page","rpp","total","request_time","stations":
    [
      {"station_code","atcocode","tiploc_code","name","mode","longitude","latitude","distance"},
    ...more results... 
    ]
}

Where

min/max lat/lonbounding box of the search
search lat/lonpoint used to sort the stations (nearest first)
page and rppas described above
totaltotal number of stations within the bounding box
request_timewhen the request was made
stationsan array of stations, sorted by distance from search lat/lon with attributes
station_code3-Alpha code for the station. This is a uk-wide coding previously known as 'CRS codes'
atcocodeatcocode for this station, if available
tiploc_codetiploc_code for this station
namename of the station
modemode of transport
longitude/latitudestation location
distancein metres from search lat/lon

Stations within bounding box

Essentially the same as nearby stations, but the search parameters are specifying a bounding box, rather than a single point.

http://fcc.transportapi.com/v3/uk/train/stations/bbox[.format]?{minlon=&}{minlat=&}{maxlon=&}{maxlat=}[&page=][&rpp=]

The remaining HTTP parameters have the same meaning as for nearby stations.

Example

http://fcc.transportapi.com/v3/uk/train/stations/bbox.json?minlon=-1.12323&minlat=50.517789&maxlon=-0.092323&maxlat=51.537789&page=3&rpp=8

The json response format is identical to nearby stations.

Stations served by an operator

Retrieves the stations served by any given operator, as identified by their two digit ATOC code.

This function is processing intensive, and may take 10 seconds to respond. You’re encouraged to cache the results, and reuse them in your app.

http://fcc.transportapi.com/v3/uk/train/operator/{atoc_code}/stations[.format]?[rpp=]
  • Supported formats: html (default) and json
  • rpp is the number of results per page to return
  • There is no cap on the number of results returned by this method, so feel free to set the limit of results you can fit on one page (the rpp) to a big number.
  • The json response format is very similar to nearby stations, except there is no information relating to the bounds of a search box, or the distance of stations from a focal point.

Scheduled station departures

Timetabled departures from a station.

http://fcc.transportapi.com/v3/uk/train/station/{station_code}/[date]/[time]timetable[.format]?[limit=][&origin=][&destination=][&calling_at=][&called_at=]
station_code3-Alpha Code for the station you are interested in. This is a uk-wide coding previously known as 'CRS codes'. You might discover a particular 3-Alpha Code with a call to get nearby stations
dateoptional date in yyyy-mm-dd format (defaults to today’s date if not specified)
timeoptional date in hh:mm format (defaults to current time if not specified)
limitmaximum number of results to return (capped at the maximum)
originoptional filter – only return trains originating from this station (3-Alpha code)
destinationoptional filter – only return trains terminating at this station (3-Alpha code)
calling_atoptional filter – only return trains that will stop at this station (3-Alpha code)
called_atoptional filter – only return trains that have stopped at this station (3-Alpha code)
  • Supported format: just html (default);
  • For the origin / destination / calling_at / called_at parameters, if a station cannot be found associated with the 3-Alpha code, it is ignored.

Example URL

http://fcc.transportapi.com/v3/uk/train/station/ZFD/2014-10-01/08:09/timetable

Live Station departures

Live departures from a station.

http://fcc.transportapi.com/v3/uk/train/station/{station_code}/live[.format]?[limit=]
  • Supported formats: html (default) and json
  • station_code is the 3-Alpha Code for the station you are interested in. This is a uk-wide coding previously known as 'CRS codes'. You might discover a particular 3-Alpha Code with a call to get nearby stations
  • limit the maximum number of results to return (capped at the maximum)

Example

http://fcc.transportapi.com/v3/uk/train/station/SYD/live

The JSON response will look like this:

{
  "station_name": "Sydenham",
  "request_time": "2013-08-06T16:26:31+01:00",
  "station_code": "SYD",
  "departures": {
    "all": [
      {
        "mode": "train",
        "service": "24661000",
        "train_uid": "W73955",
        "origin_name": "London Bridge",
        "destination_name": "Caterham",
        "platform": "2",
        "operator": "SN",
        "aimed_departure_time": "16:22",
        "expected_departure_time": "16:30",
        "best_departure_estimate_mins": 3,
        "aimed_arrival_time": "16:22",
        "expected_arrival_time": "16:30",
        "best_arrival_estimate_mins": 3,
        "status": "LATE",
        "source": "Network Rail"
      }
      //...more results...
    ]
  }
}

Where

modealways "train" for this method
servicetrain service number from timetables, can be used to make a timetable lookup e.g.
fcc.transportapi.com/v3/uk/train/service/22214000/timetable
origin_namestart station for the service
destination_nameend station for the service
platformplatform, null in some cases where the feed does not provide it
operatortrain operator code e.g. LO for London Overground
aimed_departure_timetimetabled departure e.g. "12:00"
expected_departure_timeexpected live departure time
best_departure_estimate_minsnumber of minutes until the expected departure (integer)
aimed_arrival_timetimetabled arrival time
expected_arrival_timeexpected live arrival time
best_arrival_estimate_minsnumber of minutes until the expected live arrival (integer)
statusmovement status. This can be EARLY, LATE, ON TIME, NO REPORT, ARRIVED
sourceinformation source e.g. "Network Rail"

The 'best_departure_estimate_mins / best_arrival_estimate_mins' value is derived from the live data unless this is absent (no 'expected' values), in which case it is the time to timetabled departure. If this value is a minus number, this is an indication that there have been no further updates on train position: it could be broken down, cancelled or sitting outside the station not triggering an update event.

In some cases the 'status' value may equal "ARRIVED", which can help decode this behaviour. In this case you might want to display 'delayed' or 'due' in the user interface, as appropriate. This value can also be used to work out the request time by differencing the later of the aimed or expected times and the 'best estimate'.

Note that a train showing "No report" close to the departure time may indicate that the train starts at this location.

Live station arrivals

Live arrivals at a station.

http://fcc.transportapi.com/v3/uk/train/station/{station_code}/live_arrivals[.format]?[limit=]

Essentially the same as Live Station Departures but with train arrivals information.

The available request parameters and JSON response structure are identical to those of Live Station Departures

Scheduled Service

The next scheduled train service.

http://fcc.transportapi.com/v3/uk/train/service/{service_code}/[date]/[time]/timetable[.format]?[station_code=]
  • Supported format: html (default) and json;
  • service_code is the Identifier for this scheduled train service;
  • station_code is the optional 3-Alpha Code for the station you are interested in. It will default to the origin station if not specified. 3-Alpha codes are a uk-wide coding previously known as 'CRS codes'. You might discover a particular 3-Alpha Code with a call to get nearby stations
  • date an optional date in yyyy-mm-dd format (defaults to today’s date if not specified);
  • time an optional date in hh:mm format (defaults to current time if not specified).

Example URL

http://fcc.transportapi.com/v3/uk/train/service/22721000/2015-01-27/13:24/timetable?station_code=lut

Performance

Performance data at a particular platform, or a network-wide list. This provides our performance measurement for every platform on the tube network, or for a single specified platform. By default you will see the readings from the current time (last 15 minutes) but by specifying a timestamp or time range this gives access to our archive of performance data for the tube reaching back several years.

http://transportapi.com/v3/uk/tube/all/performance[.format]?[timestamp=DD-MM-YYTHH:mmZ]
http://transportapi.com/v3/uk/tube/{line}/{station_code}/{platform_number}/performance[.format]?[timestamp=...]
  • Supported format is either json or csv
  • line is the tube line.
  • station_code is the 3 letter London Underground station code.
  • platform_number the platform;
  • timestamp optional parameter specifies a date and time in the past e.g. "2007-04-05T14:30Z" (ISO 8601 format)
  • timestamp_start and timestamp_end parameters can be specified instead, to request a range of times (within limits)

Examples

http://transportapi.com/v3/uk/tube/bakerloo/EMB/6/performance.json

If you leave out any timestamp parameters, you will receive the most current performance samples (last 15 minutes). If you specify a timespan (with timestamp_start & timestamp_end parameters) you will not be permitted request more than 6 weeks of data for an individual platform. For the whole network you may only request up to 2 hours of data. All sample times are quantised to 15 minute buckets, and any timestamp parameters will be rounded to give the closest sample time.

Example json response for a network-wide request at a specified timestamp:

{
  "sample_time": {
    "sample_date": "2012-12-24",
    "time_of_day": "19:30",
    "day_type": "working"
  },
  "samples": [
    {
      "primary_code": "TFL:KGN:P1",
      "average_headway_minutes": 6.3,
      "average_time_to_1st_minutes": 3.3
    },
    {
      "primary_code": "TFL:ERB:P1",
      "average_headway_minutes": 5.8,
      "average_time_to_1st_minutes": 2.2
    },
    {
      "primary_code": "TFL:ERB:P2",
      "average_headway_minutes": 3.9,
      "average_time_to_1st_minutes": 2.2
    },
    {
      "primary_code": "TFL:ELE:P3",
      "average_headway_minutes": 4,
      "average_time_to_1st_minutes": 2
    },
    {
      "primary_code": "TFL:ELE:P4",
      "average_headway_minutes": 4.8,
      "average_time_to_1st_minutes": 1.6
    },
    {
      "primary_code": "TFL:EMB:P5",
      "average_headway_minutes": 2,
      "average_time_to_1st_minutes": 2.2
    }
    //...
  ]
}

Where

sample_datedate of the sample
time_of_daytime of the sample bucket (after rounding to 15 minutes)
day_typeone of 'working', 'saturday' or 'sunday'
primary_codecombination of station code and platform number for this platform
average_headway_minutesperformance data. It is an average of the headway (time between trains) over the 15 minute period
average_time_to_1st_minutesa more basic measurement of the first (closest) train times averaged over the 15 minutes period

The same fields can be returned a more compact comma-separated output. Simply add .csv instead of .json on the end of the URL

Network performance by station

Performance data summarised at the station level for all tube stations on the network, allowing you to (for example) create an overview map shading the stations by current performance (this powers tube-radar.com)

http://transportapi.com/v3/uk/tube/stations/performance[.format]?[include_station_fields=true]
  • Supported format html (default) or json
  • include_station_fields=true outputs more reference data (This is generally unchanging, and is otherwise available via a 'stations' call)
  • include_colour=true DEPRECATED - outputs peformance indicator colours as used on tube-radar.com - It is better for clients to implement their own display logic. Control your own colouring based on the headway performance metric
  • include_headway_metric=false DEPRECATED - switch off headway metric output. You would only do this if working from the colour output

Stations along a line

List the stations along a tube line.

http://transportapi.com/v3/uk/tube/{line}[.format]
  • Supported format just html (default);
  • line is the tube line.

Example

http://transportapi.com/v3/uk/tube/bakerloo.html

Platform Departures

Live departures from a specific station platform.

http://transportapi.com/v3/uk/tube/{line}/{station_code}/{platform_number}/live[.format]
  • Supported format just html (default);
  • line is the tube line;
  • station_code is the 3 letter London Underground station code;
  • platform_number the platform;

Example

http://transportapi.com/v3/uk/tube/bakerloo/EMB/6/live.html

Radar chart for a station platform

A radar diagram showing the last 24hrs performance for a station platform

http://transportapi.com/v3/uk/tube/{line}/{station_code}/{platform_number}/radar[.format]
  • Supported format just html (default)
  • line is the tube line;
  • station_code is the 3 letter London Underground station code;
  • platform_number the platform;

Example

http://transportapi.com/v3/uk/tube/bakerloo/EMB/6/radar.html

Train Information

Endpoints for train information, including nearby stations, timetabled and live services.

Nearby stations

Find stations close to a given (lon,lat), ordered by distance.

http://fcc.transportapi.com/v3/uk/train/stations/near[.format]?{lon=&}{lat=}[&page=][&rpp=]
  • Supported formats: html (default) and json
  • lat and lon define the point around which you want to search;
  • rpp is the number of results per page to return (25 by default, and capped at 25);
  • page is the result page to return (1 by default). rpp and page together are useful for paging through long lists of results.

Example URLs

http://fcc.transportapi.com/v3/uk/train/stations/near.html?lon=-0.102323&lat=51.527789
http://fcc.transportapi.com/v3/uk/train/stations/near.json?lat=51.527789&lon=-0.102323&page=3&rpp=10

Response

JSON response format is:

{"minlon","minlat","maxlon","maxlat","searchlon","searchlat","page","rpp","total","request_time","stations":
    [
      {"station_code","atcocode","tiploc_code","name","mode","longitude","latitude","distance"},
    //...more results... 
    ]
}

Where

min/max lat/lonbounding box of the search
search lat/lonpoint used to sort the stations (nearest first)
page
rppas described above
totaltotal number of stations within the bounding box
request_timewhen the request was made
stationsan array of stations, sorted by distance from search lat/lon with attributes
station_codethe 3-Alpha code for the station. This is a uk-wide coding previously known as 'CRS codes'
atcocodeatcocode for this station, if available
tiploc_codetiploc_code for this station
namename of the station
modemode of transport
longitude/latitudestation location
distancein metres from search lat/lon

Stations within bounding box

Essentially the same as nearby stations, but the search parameters are specifying a bounding box, rather than a single point.

http://fcc.transportapi.com/v3/uk/train/stations/bbox[.format]?{minlon=&}{minlat=&}{maxlon=&}{maxlat=}[&page=][&rpp=]

The remaining HTTP parameters have the same meaning as for nearby stations.

Example

http://fcc.transportapi.com/v3/uk/train/stations/bbox.json?minlon=-1.12323&minlat=50.517789&maxlon=-0.092323&maxlat=51.537789&page=3&rpp=8

The json response format is identical to nearby stations.

Stations served by an operator

Retrieves the stations served by any given operator, as identified by their two digit ATOC code.

This function is processing intensive, and may take 10 seconds to respond. You’re encouraged to cache the results, and reuse them in your app.

http://fcc.transportapi.com/v3/uk/train/operator/{atoc_code}/stations[.format]?[rpp=]
  • Supported formats: html (default) and json
  • rpp is the number of results per page to return

There is no cap on the number of results returned by this method, so feel free to set the limit of results you can fit on one page (the rpp) to a big number.

The json response format is very similar to nearby stations, except there is no information relating to the bounds of a search box, or the distance of stations from a focal point.

Scheduled Station Departures

Timetabled departures from a station.

http://fcc.transportapi.com/v3/uk/train/station/{station_code}/[date]/[time]timetable[.format]?[limit=][&origin=][&destination=][&calling_at=][&called_at=]
  • Supported formats: html (default) and json

Other parameters:

stationcode is the 3-Alpha Code for the station you are interested in. This is a uk-wide coding previously known as 'CRS codes'. You might discover a particular 3-Apha Code with a call to get nearby stations
date an optional date in _yyyy-mm-dd format (defaults to today's date if not specified)
time an optional date in hh:mm format (defaults to current time if not specified)
limit the maximum number of results to return (capped at the maximum)
origin optional filter - only return trains originating from this station (3-Alpha code)
destination optional filter - only return trains terminating at this station (3-Alpha code)
calling_at optional filter - only return trains that will stop at this station (3-Alpha code)
called_at optional filter - only return trains that have stopped at this station (3-Alpha code)

For the origin / destination / calling_at / called_at parameters, if a station cannot be found associated with the 3-Alpha code, it is ignored.

Example URL

http://fcc.transportapi.com/v3/uk/train/station/ZFD/2014-10-01/08:09/timetable

Live Station Departures

Live departures from a station.

http://fcc.transportapi.com/v3/uk/train/station/{station_code}/live[.format]?[limit=]
  • Supported formats: html (default) and json
  • station_code is the 3-Alpha Code for the station you are interested in. This is a uk-wide coding previously known as 'CRS codes'. You might discover a particular 3-Alpha Code with a call to get nearby stations
  • limit the maximum number of results to return (capped at the maximum)

Example

http://fcc.transportapi.com/v3/uk/train/station/SYD/live

The JSON response will look like this:

{"station_name":"Sydenham","request_time":"2013-08-06T16:26:31+01:00","station_code":"SYD",
  "departures":{
    "all":[
      {"mode":"train", "service":"24661000", "train_uid":"W73955",
       "origin_name":"London Bridge", "destination_name":"Caterham",
       "platform":"2", "operator":"SN",
       "aimed_departure_time":"16:22", "expected_departure_time":"16:30",
       "best_departure_estimate_mins":3, "aimed_arrival_time":"16:22",
       "expected_arrival_time":"16:30", "best_arrival_estimate_mins":3,
       "status":"LATE", "source":"Network Rail"},
       //...more results...
    ]
  }
}

Where

modealways "train" for this method
servicetrain service number from timetables, can be used to make a timetable lookup e.g.
fcc.transportapi.com/v3/uk/train/service/22214000/timetable
origin_namestart station for the service
destination_nameend station for the service
platformplatform, null in some cases where the feed does not provide it
operatortrain operator code e.g. LO for London Overground
aimed_departure_timetimetabled departure e.g. "12:00"
expected_departure_timeexpected live departure time
best_departure_estimate_minsnumber of minutes until the expected departure (integer)
aimed_arrival_timetimetabled arrival time
expected_arrival_timeexpected live arrival time
best_arrival_estimate_minsnumber of minutes until the expected live arrival (integer)
statusmovement status. This can be EARLY, LATE, ON TIME, NO REPORT, ARRIVED
sourceinformation source e.g. "Network Rail"

The 'best_departure_estimate_mins / best_arrival_estimate_mins' value is derived from the live data unless this is absent (no 'expected' values), in which case it is the time to timetabled departure. If this value is a minus number, this is an indication that there have been no further updates on train position: it could be broken down, cancelled or sitting outside the station not triggering an update event.

In some cases the 'status' value may equal "ARRIVED", which can help decode this behaviour. In this case you might want to display 'delayed' or 'due' in the user interface, as appropriate. This value can also be used to work out the request time by differencing the later of the aimed or expected times and the 'best estimate'.

Note that a train showing "No report" close to the departure time may indicate that the train starts at this location.

Live Station Arrivals

Live arrivals at a station.

http://fcc.transportapi.com/v3/uk/train/station/{station_code}/live_arrivals[.format]?[limit=]

Essentially the same as Live Station Departures but with train arrivals information.

The available request parameters and JSON response structure are identical to those of Live Station Departures

Scheduled Service

The next scheduled train service.

http://fcc.transportapi.com/v3/uk/train/service/{service_code}/[date]/[time]/timetable[.format]?[station_code=]
  • Supported format: html (default) and json;
  • service_code is the Identifier for this scheduled train service;
  • station_code is the optional 3-Alpha Code for the station you are interested in. It will default to the origin station if not specified. 3-Alpha codes are a uk-wide coding previously known as 'CRS codes'. You might discover a particular 3-Alpha Code with a call to get nearby stations
  • date an optional date in yyyy-mm-dd format (defaults to today’s date if not specified);
  • time an optional date in hh:mm format (defaults to current time if not specified).

Example URL

http://fcc.transportapi.com/v3/uk/train/service/22721000/2015-01-27/13:24/timetable?station_code=lut

Public Journey Planning

Plan a route between two points on public transport, returning a multi-modal journey plan.

Plan journey by public transport

The request involves specifying the "from" and "to" points in one of several different ways (types)

http://fcc.transportapi.com/v3/uk/public/journey/from/{from_type}:{from_text}/to/{to_type}:{to_text}[.format]
  • "format": json, xml, or html. (The html format is a useful way to understand the results, but it is a crude raw view of the routes which is under development and likely to change)
  • from_type : specifies how to interpret the {from_text} appearing after the colon. Either 'stop', 'postcode', 'lonlat', or 'stopID'
  • from_text : text string giving the location to begin a journey from. The format of this text depends which from_type you are using. Normal URL encoding should be applied. Spaces can be substituted with "+" or "%20"
  • to_type : specifies how to interpret the {to_text} appearing after the colon. Either 'stop', 'postcode', 'lonlat', or 'stopID'
  • to_text : text string giving the location to plan a journey to. The format of this text depends which to_type you are using (as with from)
postcodemust be valid postcode within the active region, with the space substituted e.g. "postcode:EC2A+4JE".
stopwill try to match your text against any train station names or bus stop name e.g. "stop:Euston". See note on 'text matching' below.
lonlatNumeric coordinates. Longitude and Latitude pair in WGS84 with a comma separating e.g. "lonlat:-0.13182,51.52788"
stopIDIs a special numerical code taken from an 'options' response when 'stop' text is ambiguous e.g. "stopID:1000256". See note on 'text matching' below.

Additional parameters

Desired departure date and time can be specified with a longer format URL involving 'at'. With the above shorter form this is taken as the current time (depart right now) Returned routes will commence their first route part on or after the specified time:

http://fcc.transportapi.com/v3/uk/public/journey/from/{from}/to/{to}/at/{date}/{time}[.format]

Alternatively you can use a 'by' in the URL, to request journeys which arrive by the specified date & time. Returned routes will conclude their final route part on or before the specified time:

http://fcc.transportapi.com/v3/uk/public/journey/from/{from}/to/{to}/by/{date}/{time}[.format]
  • date - a date in yyyy-mm-dd format
  • time - a time in hh:mm format

The following optional URL parameters can be added after the '?' in the URL

  • region=tfl/southeast - Specify the active region, and which back-end system we require journey plans from. Default is 'tfl'. The region parameter is in fact a specifier of back-end provider for journey planning. 'tfl' (Transport For London) will only work in and around London, and some interchange destinations around the country. 'southeast' (Traveline Southeast) now covers the whole UK, but the queries run more slowly, and the name matching can be more ambiguous.

  • modes={include_modes} or not_modes={exclude_modes} - Specify which transport modes to travel by. This can be specified as a list of modes starting from no modes and saying which modes to add, using the modes parameter. Alternatively starting from the set of all modes, specify which modes to not use with the not_modes parameter. The modes are specified as a hyphen separated list e.g. 'not_modes=bus-train-boat'. The set of possible modes is: 'bus', 'train', 'tube', and 'boat'

Text matching (when specifying 'stop' text for your 'from' or 'to' point) is implemented by our regional journey planning suppliers, and will not give a direct match for some input texts, due to the imprecise nature of the geocoding process. The matching result will come in one of three possible forms:

  • A direct journey plan,
  • A "not found" error,
  • or "options" response allowing you to present possible matches to the end user (to disambiguate an ambiguous text input) For example "Wembley Central" is unambiguous (matches a tube station), and goes into a direct journey plan, however just "Wembley" is ambiguous and results in several options.

When handling these options, each one is supplied as a text title, but also a numeric 'stopID'. This can be used to select a choice unambiguously. For example you might present a drop-down box of different options. If the user did indeed mean to specify the 'Wembley Central' tube station, then (after they select this in a the drop-down) you would specify "stopID:1000256" in a subsequent request.

Note that these numeric stopIDs are used by TfL and TravelLine Southeast to identify stops, but are not available in a reference file, and are only discoverable (and intended to be used) when you receive back an 'options' response after attempting to match an ambiguous 'stop' text.

Response

The response is a set of alternative routes, each containing a set of routeParts for legs of the journey on each mode of transport. Each routePart has fields giving the timing information. For example the following URL:

http://fcc.transportapi.com/v3/uk/public/journey/from/postcode:EC2A+4JE/to/stop:Canary+wharf/at/2013-10-18/15:29.json?not_modes=train

...results in the following response:

{
  "request_time": "2013-12-09T16:42:59+00:00",
  "source": "TfL journey planning API",
  "acknowledgements": "Transport for London",
  "routes": [
    {
      "duration": "00:57:00",
      "route_parts": [
        {
          "mode": "foot",
          "from_point_name": "EC2A 4JE",
          "to_point_name": "Liverpool Street",
          "destination": "",
          "line_name": "",
          "duration": "00:14:00",
          "departure_time": "12:55",
          "arrival_time": "12:55",
          "coordinates": [
            [
              -0.08366,
              51.52239
            ],
            [
              -0.08323,
              51.52235
            ],
            [
              -0.08291,
              51.51741
            ],
            [
              -0.0822,
              51.51806
            ]
            //...more coordinates ...
          ]
        },
        {
          "mode": "tube",
          "from_point_name": "Liverpool Street",
          "to_point_name": "Oxford Circus",
          "destination": "West Ruislip",
          "line_name": "Central",
          "duration": "00:09:00",
          "departure_time": "12:55",
          "arrival_time": "13:09",
          "coordinates": [
           //...more coordinates...
          ]
        },
        {
          "mode": "tube",
          "from_point_name": "Oxford Circus",
          "to_point_name": "Wembley Central",
          "destination": "Harrow & Wealdstone",
          "line_name": "Bakerloo",
          "duration": "00:28:00",
          "departure_time": "12:55",
          "arrival_time": "13:24",
          "coordinates": [
          //...more coordinates...
          ]
        }
      ],
      "departure_time": "12:55",
      "arrival_time": "13:24"
    },
    {
      "duration": "00:56:00",
      "route_parts": [
      //...more route parts with coords... 
      ],
      "departure_time": "13:15",
      "arrival_time": "13:42"
    }
   //...more routes (alternatives)...
  ]
}

Where the fields (and structures) have the following meanings:

request_timetime request was made
sourceshort datasource description
acknowledgementsjourney planning provider
routesan array of alternative routes
route_partsan array of journey legs. Passengers need to change to a new transport mode or new vehicle, e.g. from one train to another at a station, between each of the route_parts
    modeThe transport mode type "foot", "tube", "dlr", "bus", "tram", "train", "overground", "boat", "wait" or "unknown". The "wait" mode indicates significant length of time waiting. The "unknown" mode type is for obscure transport modes which do not fit into the common types.
    from_point_nameshort textual name (e.g. station name) where this journey leg starts
    to_point_nameshort textual name (e.g. station name) where this journey leg ends
    destinationWhere the vehicle is heading to. This can be displayed to help passengers tell which train/bus to catch. It is the terminating destination which is often shown on the front of vehicles. The station/stop mentioned here may form part of the route, or the passenger may need to get off earlier (at the station/stop given in the to_point_name)
    durationfor entire journey, in hh:mm:ss format
    departure_timefor this route_part hh:mm format. This may be the same or a few minutes after the arrival_time of the previous route part (a short wait)
    arrival_timefor this route_part hh:mm format
    coordinatesA set of coordinates for the route part, allowing the route to be plotted as a polyline on a map. For json responses this data is formatted as [lon,lat] pairs following the geoJSON format. For xml responses this data is formatted as lon,lat pairs with newlines between them following the KML format.

Private Journey Planning

Plan journey by car

Plan a journey by car between two locations.

The request involves specifying the "from" and "to" points in one of several different ways.

http://fcc.transportapi.com/v3/uk/car/journey/from/{postcode/lonlat}:{from_text}/to/{postcode/lonlat}:{to_text}[.format]
  • format: json, xml, or html (The html format is a useful way to understand the results, but it is a crude raw view of the journeys which is under development and likely to change)
  • postcode/lonlat : specifies how to interpret the {from_text} appearing after the colon.
  • from_text and to_text strings give the location either as a postcode, or longitude,latitude coordinates.

    postcode: must be valid postcode within the UK, and can have the space substituted with "+" or "%20". e.g. "postcode:EC2A+4JE".

    lonlat: must be a "longitude,latitude" pair with a comma between them e.g. "-5.711345,50.065700". The location must lie within the UK

Examples

http://fcc.transportapi.com/v3/uk/car/journey/from/postcode:TR197AA/to/postcode:KW14YR.jsonhttp://fcc.transportapi.com/v3/uk/car/journey/from/lonlat:-5.711345,50.065700/to/lonlat:-3.068553,58.637299.xml

Response

The response is a route (currently only one route) which contains a set of directions for your cycle/car journey.

request_timetime request was made
status_messagereports whether a route was found
routesan array of alternative routes (currently a maximum of one route is returned)
modecurrently only car supported
from_point_nametextual description of start point
to_point_nametextual description of endpoint
durationfor entire journey, in hh:mm:ss format
total_distancefor entire journey, in metres
instructionsan array of driving instructions, one for each section of the journey. Each individual instruction includes: text a textual description for this journey section
    texta textual description for this journey section
    distancein metres
    durationin hh:mm:ss format
    distance_desce.g. 26m, or 12.3km
coordinatesthe route geometry. A linestring represented as an array of lon, lat coordinates
sourceacknowledging OSRM as routing engine
acknowledgementsto source data and routing engine/td>

Plan journey by cycle

Plan a journey by bicycle between two locations.

http://fcc.transportapi.com/v3/uk/cycle/journey/from/{postcode/lonlat}:{from_text}/to/{postcode/lonlat}:{to_text}[.format]

All parameters are as above, except the Cycle journey plans are provided by cyclestreets.net which is powered with OpenStreetMap data.

Widgets

"Widgets" offer a very simple cut-and-paste approach to get a small panel of transport information appearing alongside your other web content.

The widget feature is under development, with many more features and much more flexibility in the pipeline, but for now we are offering one type of widget content: "Local transport summary", and two different approaches for widget embedding: simple iframe, or passthrough HTML. The iframe approach is the easiest. Passthrough HTML requires server-side scripting

iframe

The iframe approach is the easiest, but has some disadvantages in terms of control and flexibility. Simply add the following simple HTML fragment onto your website:

<iframe src="http://transportapi.com/v3/uk/all/summary.html?mode=iframe300x300&lat=51.4411&lon=-0.074587&minlon=-0.115786&minlat=51.432&radius=1000&maxlon=-0.033388&maxlat=51.4502&place=Dulwich&api_key={YOUR KEY}&app_id={YOUR APP ID}" width="300" height="300" style="border:1px lightgrey solid; border-radius:8px;"> <p>Your browser does not support iframes.</p> </iframe>

The 'mode=iframe300x300' parameter is a "hint" to the TransportAPI about sizing and formatting of content elements, but the content is not guaranteed to (and does not always) fit within these bounds, meaning the iframe may display scrollbars. The 300x300 dimension is currently the only dimension catered for, although if you set different dimension on your iframe, it will still work, just with the risk of scrollbars appearing more often or other formatting glitches. Note that this parameter is the only indication to TransportAPI, that it is serving a widget. It is otherwise treated as a normal HTML endpoint request. With this mode, a small credit link is served, and the links are set to open tapi.mobi in a new window (equivalent to link_style=tapi.mobi). This behaviour may change in future.

Passthrough HTML

The passthrough HTML approach works best if your web server supports PHP. TransportAPI supplies PHP code which builds up the appropriate URL for fetching widget content from the API, performs the HTTP request, and passes the HTML through. This code can be modified to make use of the FCC TransportAPI instance. The set-up steps are as follows:

  • Download the TransportAPI PHP class file from http://fcc.transportapi.com/v3/resources/TransportAPI.php
  • Modify the code to use FCC instead of TransportAPI. Put fcc. at the front of API URLs, and remove the app_id and api_key params.
  • Upload TransportAPI.php to your webserver placed directly alongside your website code i.e. the php file in which you will be embedding the widget (If this is not a PHP file then this approach will not work)
  • Edit your website code (perhaps by downloading and the re-uploading using FTP) You will need to make the following changes:

    Within the section of your HTML include the transportapi CSS by adding the follow line:

    <link rel="stylesheet" type="text/css" href="http://transportapi.com/v3/resources/transportapi.css" />
    

    Within the body section of your HTML, arranged in position on the page (wherever you want the widget to appear) add the following.

    <?php
    include_once('./TransportAPI.php');
    $transportAPI = new TransportAPI("none","none");
    
    $lat = 51.522178;
    $lon = -0.083402;
    $radius = 1000;
    $minlat=51.51929;
    $minlon=-0.08823;
    $maxlat=51.52655;
    $maxlon=-0.07841;
    $place="Shoreditch";
    
    print "<div class=\"transportwidget\">";
    print $transportAPI->localSummaryWidget($lat, $lon, $radius,
    $minlat, $minlon, $maxlat, $maxlon,
    $place );
    print "</div>\n";
    ?>
    

Inside TransportAPI.php you'll find the generated URL to fetch content from the TransportAPI. The 'mode=passthru300x300' parameter is a "hint" to the transportapi about sizing and formatting. This is very similar to the iframe300x300 parameter described above.

Local transport summary

'Local transport summary' is the only style of widget content available so far. The above code samples show this endpoint as an example. Here we explain the parameters in more detail

Use this to bring in a general summary of transport options centred around a specified location. This is ideal for local town/village websites.

Add the following simple HTML fragment, and modify the {parameters} where indicated:

<iframe src="http://fcc.transportapi.com/v3/uk/all/summary.html?mode=iframe300x300[&lat={lat}&lon={lon}&radius={radius}][&minlon={minlot}&minlat={minlat}&maxlon={maxlon}&maxlat={maxlat}][&place={place}]&api_key={api_key}&app_id={app_id}" width="300" height="300" style="border:1px lightgrey solid; border-radius:8px;"> <p>Your browser does not support iframes.</p> </iframe>

Example

<iframe src="http://fcc.transportapi.com/v3/uk/all/summary.html?mode=iframe300x300&lat=51.4411&lon=-0.074587&minlon=-0.115786&minlat=51.432&radius=1000&maxlon=-0.033388&maxlat=51.4502&place=Dulwich&api_key={YOUR KEY}&app_id={YOUR APP ID}" width="300" height="300" style="border:1px lightgrey solid; border-radius:8px;"> <p>Your browser does not support iframes.</p> </iframe>

Where the parameters within the src URL have the following meanings:

mode=iframe300x300instructs transportapi to create content suitable for an iframe widget of size 300x300 pixels
latlatitude for the centrepoint of your desired focal area
lonlongitude for the centrepoint of your desired focal area
radiusindicates how large your desired focal area is in metres
minlat,minlon,maxlat and maxlontogether provide a bounding box for your desired focal area
placename of your desired focal area

The idea behind this widget will always be to present a useful summary of transport options within a focal area. Currently this features bus routes and nearby train stations, but we intend to develop this to offer differing displays, including dynamic content and performance information. The overall aim is to provide a transport summary will remain the same.

There are several parameters for specifying your focal area. You can optionally provide, lat/lon and radius and/or bounding box and/or the name of the place. These act as fallback options. The name of the place may in future be used to perform a geocoding look-up of a polygon representing a neighbourhood name (currently ignored) this would be used in preference to a bounding box, which in turn would be used in preference to a radius and centrepoint. The centrepoint may always be useful however, for ordering matches by distance.