Train Tracker API documentation

Introduction

CTA Train Tracker ^SM is a product currently in the beta testing phase. This document covers the arrivals API, currently under release for testing and evaluation by developers who work with CTA data.

For complete information about the API and tips, see the main CTA Train Tracker API page.

Note that, to use this API, you must agree to our Developers License Agreement and Terms of Use. You’ll also need to apply for a key.

This documentation is also available as a PDF

Revised15-May-2018

Table of Contents

• Introduction
  • About this document
  • A few definitions…
  • Train location data coming soon
• Arrivals API
  • Description
  • XML Schema
  • Example
• Follow This Train API
  • Description
  • XML Schema
  • Example
• Locations API
  • Description
  • XML Schema
  • Example
• Appendices
  • A: Route ID Quick Reference
  • B: Station IDs
  • C: Route Direction Code Quick Reference
  • D: Insight into Polishing Your Output from the Experts
  • E: Error Codes

About this document

What this document covers

This document explains how to request information and what information is provided through the single arrivals API. Additional APIs may be released at a later date, and this documentation would then be updated accordingly.

What this document does not cover

This document does not cover information provided through the CTA Customer Alerts API, Google Transit Feed Specification data package nor the CTA Bus Tracker API. Go to our Developer Center for more information on these other data services from CTA.

How information gets into our system

Information in the CTA Train Tracker beta comes from data fed to CTA from its rail infrastructure (unlike buses, our current railcar fleet does not have GPS hardware). This data is then processed by software we use to monitor our rail system which also generates the predictions for train arrivals based on recent train travel times from one point to another. (The software is a product called QuicTrak®.)

Prediction data are combined with other data and polished to help present information in the most meaningful way possible.

Note: QuicTrak is a registered trademark of QEI, Inc.

Some other things you should know

This service is in beta—it may not always be available and may be changed (see DLA for complete details). Here are some notes about what you can expect from the data:

• Predictions for train arrivals are generated as trains move from one section of track to another and for estimated arrivals up to fifteen minutes beyond the train’s current position.
• Predictions may be withheld in circumstances where we expect them to be inaccurate, such as during major work, reroutes or unavoidable service disruptions.
  • Important tip: Use the Customer Alerts API to determine whether or not an event is affecting service and relay to your end-users when some or all predictions may be affected or unavailable due to an event that affects service.
• When no predictions are available for a station, such as because no train has yet departed a terminal, we offer up to one scheduled departure time in place of a live prediction so long as service is scheduled. Terminal departures are always represented as a scheduled departure, as live information is not presently available until a train leaves.
• Arrival predictions are available for locations where trains pick up passengers (predictions for terminal arrivals and exit-only platforms are not presently available in the data).
• Predictions for a specific train run number are not available at this time—only for arrival/departures from stops where passengers are accepted.
• Internal testing has shown train arrival accuracy averages <±1 minute from prediction times. Average actual variance from predictions may vary as traffic conditions change.
• Unscheduled express runs (where a train runs non-stop from one point on a route to another, such as to space out service following an unavoidable delay) are not expressed in CTA Train Tracker at this time.
• The default daily transaction limit for this API is 50,000 transactions. If you need additional transactions, contact webmaster@transitchicago.com with your request. Additionally, there is DoS protection installed on our servers which may trigger a temporary “time-out” if a large number of transactions from a single IP address.

Why we’re providing this API

The hope is that, by publishing this data, it ends up in all sorts of places beyond CTA’s sites and services. By having transit information in as many contexts as people might use it, we can extend our reach and help people make informed decisions which can improve people’s experiences with transit.

If you experience any issues or have any comments regarding this service and related policies, please contact us right away. Your feedback is extremely valuable to us!

Legal notice

By using this API, you agree to our Developer License Agreement and Terms of Use, the latest version of which is included, as of the publication date of this document, in this document’s appendices.

It’s important that you, the developer, understand that this service is provided on an as-is basis and without any guarantees as to availability or accuracy. You must read and agree to the full Developer Terms of Use to use this API.

A few definitions…

There are a few bits of lingo that you’ll find in this document (we’ll try to keep it to a minimum) that we’d like to explain first, so you know what we’re talking about.

• Customer Alert – An entry in our Customer Alerts database which describes a condition that can affect someone’s trip on CTA; see Customer Alerts API for comprehensive alert information, including a special flag for train alerts that indicates whether or not an event may cause Train Tracker to behave less-reliably than normal.
   
• Google Transit Feed Specification (GTFS) – This is a “common format for public transportation schedules and associated geographic information.” GTFS is used by hundreds of transit agencies to feed service information to Google™. A GTFS package is generated, as needed, by transit agencies and can be distributed as a simple .zip file with several comma-delimited text files inside. You can read more about GTFS on Google Code. For consistency, the same route IDs and stop IDs are used throughout the Bus Tracker system, the Alerts system as are specified in the CTA GTFS feed (with a few special exceptions—see appendix).
   
• Delay – In the context of this document, a delayed train is one that has not moved from one track circuit to another for an abnormally long period of time.
   
• Terminal – A point of departure or terminus on a train route.

Train location data coming soon

We’re working on releasing an API into train location data (like what powers our beta map).

We understand that this is an exciting new feature lots of you have been waiting for, but we just need a little time to finish the development on the API bits. We're sorry we don't have this yet, but we appreciate your patience while we put together something that'll be stable and supported.

Arrivals API

Description

This API produces a list of arrival predictions for all platforms at a given train station in a well-formed XML document. Registration and receipt of an API key is required for use of this API.

Each separate prediction describes a single train, when it’s expected to arrive, and various bits of information that explain where it’s expected to arrive and certain attributes about the train.

Base URL

http://lapi.transitchicago.com/api/1.0/ttarrivals.aspx

Parameters

Use URL query string method.

Response fields:

Sample Request URL:

http://lapi.transitchicago.com/api/1.0/ttarrivals.aspx?key=a8456dcbhf8475683cf7818bca81&mapid=40380&max=5  

Remarks:

Stop IDs:
Use stop information in GTFS Stops table for associated geolocation of stops listed here. For purposes of this API, use the parent station ID (4xxxx range of stop ID numbers) to specify a station.

Destination station ID #s:
IDs in destSt refer to the ultimate destination of a train per the information about each train that’s on the move.

These destination station ID #s are only available once a train has departed (on schedule-based predictions, this element will show “0”) and doesn’t necessarily match with what will be indicated on a train’s destination sign (particularly on routes that operate around the whole Loop).

Once a train leaves Midway, its ultimate destination station’s ID is “Midway” because the train will make all stops to the Loop, go around it, and come back to Midway. This allows you to write your own logic on what to show, but we’ve already gone and done the work for you.

The destNm element is the public, friendly-name that should match the destination sign of approaching trains. For example, predictions a train heading toward the Loop on the Orange Line, using this element, will return “Loop” in a result set at Roosevelt, but that same train, even while still Loop-bound, will be listed as being to “Midway” for Harold Washington Library/State-Van Buren, because our system knows that once it gets to Library, it’ll now be considered a Midway-bound train.

Lat/lon/heading: This information is available only for trains that are in-service (i.e., have left their terminals). Some entries are based on our written schedule, as a courtesy, for when live information isn’t available. Schedule-based entries in a response will simply have an empty lat, lon and heading element as location info isn’t available.

Calculating a number of minutes: See Appendix D for extended notes on this subject.

XML Schema

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <xs:element name="ctatt">
   <xs:complexType>
     <xs:sequence>
       <xs:element name="tmst" type="xs:string" />
       <xs:element name="errCd" type="xs:unsignedByte" />
       <xs:element name="errNm" />
       <xs:element maxOccurs="unbounded" name="eta">
         <xs:complexType>
           <xs:sequence>
             <xs:element name="staId" type="xs:unsignedShort" />
             <xs:element name="stpId" type="xs:unsignedShort" />
             <xs:element name="staNm" type="xs:string" />
             <xs:element name="stpDe" type="xs:string" />
             <xs:element name="rn" type="xs:unsignedShort" />
             <xs:element name="rt" type="xs:string" />
             <xs:element name="destSt" type="xs:unsignedShort" />
             <xs:element name="destNm" type="xs:string" />
             <xs:element name="trDr" type="xs:unsignedByte" />
             <xs:element name="prdt" type="xs:string" />
             <xs:element name="arrT" type="xs:string" />
             <xs:element name="isApp" type="xs:unsignedByte" />
             <xs:element name="isSch" type="xs:unsignedByte" />
             <xs:element name="isDly" type="xs:unsignedByte" />
             <xs:element name="isFlt" type="xs:unsignedByte" />
             <xs:element name="flags" type="xs:string" />
             <xs:element name="lat" type="xs:decimal" />
             <xs:element name="lon" type="xs:decimal" />
             <xs:element name="heading" type="xs:unsignedShort" />
           </xs:sequence>
         </xs:complexType>
       </xs:element>
     </xs:sequence>
   </xs:complexType>
 </xs:element>
</xs:schema>

Example

What this request is asking for:
A maximum of one arrival prediction result from the station with the ID #40360. It also passes the API key for authorization (required).

XML Request:
http://lapi.transitchicago.com/api/1.0/ttarrivals.aspx?key=a8456dcbhf8475683cf7818bca81&max=1&mapid=40360 

XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<ctatt>
  <tmst>20110618 23:26:50</tmst>
  <errCd>0</errCd>
  <errNm/>
  <eta>
    <staId>40360</staId>
    <stpId>30070</stpId>
    <staNm>Southport</staNm>
    <stpDe>Service toward Kimball</stpDe>
    <rn>419</rn>
    <rt>Brn</rt>
    <destSt>30249</destSt>
    <destNm>Kimball</destNm>
    <trDr>1</trDr>
    <prdt>20110618 23:26:12</prdt>
    <arrT>20110618 23:28:12</arrT>
    <isApp>0</isApp>
    <isSch>0</isSch>
    <isDly>0</isDly>
    <isFlt>0</isFlt>
    <flags/>
    <lat>41.97776</lat>
    <lon>-87.77567</lon>
    <heading> 299</heading>
  </eta>
</ctatt>

Follow This Train API

Description

This API produces a list of arrival predictions for a given train at all subsequent stations for which that train is estimated to arrive, up to 20 minutes in the future or to the end of its trip.

Each separate prediction describes a single train, when it’s expected to arrive, and various bits of information that explain where it’s expected to arrive and certain attributes about the train.

Base URL

lapi.transitchicago.com/api/1.0/ttfollow.aspx

Parameters

Use URL query string method.

Response fields:

Sample Request URL:

Remarks:

Stop IDs: Use stop information in GTFS Stops table for associated geolocation of stops listed here. For purposes of this API, use the parent station ID (4xxxx range of stop ID numbers) to specify a station.

Destination station ID #s: in destSt refer to the ultimate destination of a train per the information about each train that’s on the move.

These destination station ID #s are only available once a train has departed (on schedule-based predictions, this element will show “0”) and doesn’t necessarily match with what will be indicated on a train’s destination sign (particularly on routes that operate around the whole Loop).

Once a train leaves Midway, its ultimate destination station’s ID is “Midway” because the train will make all stops to the Loop, go around it, and come back to Midway. This allows you to write your own logic on what to show, but we’ve already gone and done the work for you.

The destNm element is the public, friendly-name that should match the destination sign of approaching trains. For example, predictions a train heading toward the Loop on the Orange Line, using this element, will return “Loop” in a result set at Roosevelt, but that same train, even while still Loop-bound, will be listed as being to “Midway” for Harold Washington Library/State-Van Buren, because our system knows that once it gets to Library, it’ll now be considered a Midway-bound train.

Calculating a number of minutes: See Appendix D for extended notes on this subject.

XML Schema

Example

What this request is asking for:
Upcoming arrivals for a specific run (123, a Blue Line train in the XML example, or 830, a Red Line train, in the JSON example). It also passes the API key for authorization (required).

<?xml version="1.0" encoding="utf-8" ?>
<ctatt>
  <tmst>20130515 14:11:17</tmst>
  <errCd>0</errCd> 
  <errNm />
  <position>
    <lat>41.97776</lat>
    <lon>-87.77567</lon>
    <heading>299</heading>
  </position>
  <eta>
    <staId>40010</staId>
    <stpId>30001</stpId>
    <staNm>Austin</staNm>
    <stpDe>Austin to O'Hare</stpDe>
    <rn>123</rn>
    <rt>Blue Line</rt>
    <destSt>30171</destSt>
    <destNm>O'Hare</destNm>
    <trDr>1</trDr>
    <prdt>20130515 14:10:23</prdt>
    <arrT>20130515 14:11:23</arrT>
    <isApp>1</isApp>
    <isSch>0</isSch>
    <isDly>0</isDly>
    <isFlt>0</isFlt>
    <flags/> 
  </eta>
  <eta>
    <staId>40970</staId>
    <stpId>30187</stpId>
    <staNm>Cicero</staNm>
    <stpDe>Cicero to O'Hare</stpDe>
    <rn>123</rn>
    <rt>Blue Line</rt>
    <destSt>30171</destSt>
    <destNm>O'Hare</destNm>
    <trDr>1</trDr>
    <prdt>20130515 14:10:23</prdt>
    <arrT>20130515 14:15:23</arrT>
    <isApp>0</isApp>
    <isSch>0</isSch>
    <isDly>0</isDly>
    <isFlt>0</isFlt>
    <flags/> 
  </eta>
</ctatt>

Locations API

Description

Each separate entry describes a single train and provides coordinate, geospatial heading, certain train attributes and next stop information.

Base URL

lapi.transitchicago.com/api/1.0/ttpositions.aspx

Parameters:

Use URL query string method.

XML Schema

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="ctatt">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="tmst" type="xs:string" />
                <xs:element name="errCd" type="xs:unsignedByte" />
                <xs:element name="errNm" />
                <xs:element maxOccurs="unbounded" name="route">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element maxOccurs="unbounded" name="train">
                                <xs:complexType>
                                    <xs:sequence>
                                        <xs:element name="rn" type="xs:unsignedShort" />
                                        <xs:element name="destSt" type="xs:unsignedShort" />
                                        <xs:element name="destNm" type="xs:string" />
                                        <xs:element name="trDr" type="xs:unsignedByte" />
                                        <xs:element name="nextStaId" type="xs:unsignedShort" />
                                        <xs:element name="nextStpId" type="xs:unsignedShort" />
                                        <xs:element name="nextStaNm" type="xs:string" />
                                        <xs:element name="prdt" type="xs:string" />
                                        <xs:element name="arrT" type="xs:string" />
                                        <xs:element name="isApp" type="xs:unsignedByte" />
                                        <xs:element name="isDly" type="xs:unsignedByte" />
                                        <xs:element name="flags" type="xs:string" />
                                        <xs:element name="lat" type="xs:decimal" />
                                        <xs:element name="lon" type="xs:decimal" />
                                        <xs:element name="heading" type="xs:unsignedShort" />
                                    </xs:sequence>
                                </xs:complexType>
                            </xs:element>
                        </xs:sequence>
                        <xs:attribute name="name" type="xs:string" use="required" />
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

Example:

}

Appendices

Appendix A: Route ID Quick Reference

CTA ‘L’

‘L’ routes (rapid transit train services) are identified as follows:

• Red = Red Line (Howard-95th/Dan Ryan service)
• Blue = Blue Line (O’Hare-Forest Park service)
• Brn = Brown Line (Kimball-Loop service)
• G = Green Line (Harlem/Lake-Ashland/63rd-Cottage Grove service)
• Org = Orange Line (Midway-Loop service)
• P = Purple Line (Linden-Howard shuttle service)
• Pink = Pink Line (54th/Cermak-Loop service)
• Y = Yellow Line (Skokie-Howard [Skokie Swift] shuttle service)

Note: In the separate Customer Alerts API, alerts that apply specifically to the Purple Line Express (but not Purple Line Local/Shuttle service north of Howard) will use the additional route designator “Pexp”. When integrating Customer Alert information into your code project, be sure to account that alerts applying to the Purple Line may have either route designator “P” or “Pexp” (or both).

Appendix B: Station IDs

Each bus or train stop on the CTA system, as you’ll see if you look at the “stops” table in our Google Transit Feed Specification feed, has its own unique identifier. This helps to power trip planners such as the Google Maps transit directions capability in identifying individual locations and paths where vehicles make stops along a route in each direction.
 

Note, however, that in the GTFS data, most train stations have three entries in the stops table—one in each direction, with a third entry that covers the entire station facility, known as the “parent stop.” We’ve numbered our stops differently, using the following convention:

0-29999                  = Bus stops
30000-39999          = Train stops
40000-49999          = Train stations (parent stops)

The API accepts and responds with both train stop IDs and station IDs to allow you maximum flexibility in how you build your application.

More help

Example from GTFS

For example, Southport, on the Brown Line has three entries in our GTFS table (only relevant rows shown here):

stop_id,stop_code,stop_name,stop_lat,stop_lon,location_type,parent_station,wheelchair_boarding
30070,,"Southport",41.943744,-87.663619,0,40360,1
30071,,"Southport",41.943744,-87.663619,0,40360,1
40360,,"Southport",41.943744,-87.663619,1,,1 

The first two represent specific stops in GTFS—one for each direction from the Southport station (toward Loop or toward Kimball).

The third entry is the associated parent station GTFS, which represents the entire station facility known as “Southport” inside of which these separate “stops” are grouped.

Note that while Southport’s parent entry and individual stop entries all have the same basic attributes, this may vary in some stations for map clarity and to assist trip planners (particularly where bus stops also reference a parent station at a larger transfer facility like the transit center at Jefferson Park).

How these look in the API

In the Arrivals API, for example, responses for Southport might include either:

<staId>40360</staId>
<stpId>30071</stpId>
<staNm>Southport</staNm>
<stpDe>Service toward Loop</stpDe>

Or

<staId>40360</staId>
<stpId>30070</stpId>
<staNm>Southport</staNm>
<stpDe>Service toward Kimball</stpDe>

This allows you to reference GTFS for a variety of things, and also provides you additional descriptive information which helps you explain results to your customers, depending on how you wish to present them.

Parent Stop ID Quick Reference

This is a list of the parent stops and their associated ID# in GTFS.

A complete list of CTA 'L' stops is also available from the City of Chicago's Data Portal, which offers API's to download these lists in machine-readable formats.

Individual Stop IDs Quick Reference

This is a list of the parent stops and their associated ID# in GTFS.

A complete list of CTA 'L' stops is also available from the City of Chicago's Data Portal, which offers API's to download these lists in machine-readable formats.

Appendix C: Route Direction Code Quick Reference

In the Arrivals API response, you’ll see a train direction (“trDr”) element. These values represent what you might describe as an “operational” direction—it’s not expressive of the physical direction of a train at its current location so much as the big-picture route direction (even though it often coincides).

How a train’s direction is defined here loosely translates to a “northbound” (trDr=1) or “southbound” (trDr=5) direction, it can be a little tricky to imagine how that applies to routes such as the Blue Line.

Also, note that this value represents the current operational direction of the train as of when the prediction was generated, not which operational direction it’ll have once it reaches a given station that it’s predicted to reach. For example, an Orange Line train that’s at Halsted on its way to the Loop will be shown as such, even for predictions at Harold Washington Library-State/Van Buren by which time it’ll have changed to being a train to Midway the moment it enters the Loop.

Here’s a quick reference to help you understand what these values mean, on a per-route basis:

Red Line
1 = Howard-bound
5 = 95th/Dan Ryan-bound

Blue Line
1 = O’Hare-bound
5 = Forest Park-bound

Brown Line
1 = Kimball-bound
5 = Loop-bound

Green Line
1 = Harlem/Lake-bound
5 = Ashland/63rd- or Cottage Grove-bound (toward 63rd St destinations)

Orange Line
1 = Loop-bound
5 = Midway-bound

Purple Line
1 = Linden-bound
5 = Howard- or Loop-bound

Pink Line
1 = Loop-bound
5 = 54th/Cermak-bound

Yellow Line
1 = Skokie-bound
5 = Howard-bound

Appendix D: Insight into Polishing Your Output from the Experts

While the raw information alone is powerful, it’s helpful to interpret results and present them in such a way that can make them more meaningful for your customers.

Delays

The CTA Train Tracker service looks at how long it’s been since a train has moved from one track circuit to the next and identifies delays if a train appears to not be moving.

The “isDly” element is an expression of whether or not we’ve detected the likelihood that a train is delayed. If the value of isDly = 1, then consider indicating that the train is delayed rather than simply representing the last prediction, which might be growing stale (which you could compare timestamps to determine, independently).

Schedule faults

The isFlt element in the results indicates what we call a “schedule fault” in the context of Train Tracker. A fault on an ETA that is schedule-based (isSch=1) indicates that the scheduled arrival time given might not be feasible to serve due to the lack of a scheduled departure having occurred. Our system is designed to do some math in order to calculate whether or not a scheduled arrival is feasible based on minimum travel times from a terminal to where the arrival is being estimated for.

Note that this doesn’t necessarily mean that there are delays or that service is not good at the time—it only means that a train didn’t leave when the planned schedule had provisioned. Transit systems are complex and delays are sometimes unavoidable; our transportation managers use a variety of strategies, including making on-the-go schedule modifications, to maintain service levels (particularly during peak periods when trains leave every few minutes) and provide the best possible service. This is normal and provides a better service to our customers.

Events that affect prediction quality

Some construction or unplanned events that affect service (particularly if they cause trains to be routed differently than normal) can affect the quality of predictions in Train Tracker. While we work to improve back-end exception handling, we can alert users that the quality of predictions may be affected by a current event (or altogether unavailable). In certain situations where we know the information may be unreliable, we may temporarily stop offering predictions for all or portions of a route, which will also be reflected in the API. Our Customer Alerts API Alerts Feed contains a special “Train Tracker impact” flag (element “ttim”) to indicate when works are affecting prediction quality.

Calculating a number of minutes until arrival from this data

To calculate the number of minutes until arrival (so you can say “4 min” instead of 2:35 p.m., for example, we recommend comparing arrT to prdt – this will give you the number of minutes we calculated from when a train last moved into a new track circuit until when it should get to a station.

The reason for this is because the arrival time value is actually based on how long it should take to get from where the train was when its location was last updated in our prediction database, weighted in such a way to improve prediction accuracy, which happens on a frequent cycle.

The reason we represent this information in date-time form is for added flexibility in defining your own logic, as it allows you to show clock times or make computations as you feel is best for your code project, and can be more meaningful if your app doesn’t update very frequently.

Thus, it gives you the control to compare arrT to prdt if you do have the capability to update frequently, but, if not, you might then also consider other, more advanced scenarios, where you weight that comparison against the age of your last update. (It’s your app, so it’s really all up to you!)

Additionally, note that output for the arrT element, at least at this stage in the beta (we are open to your feedback as developers), is a minimum of 60 seconds from most recent prediction generation (trains disappear from result sets once they actually reach the station).

Due Trains

We show “due” or “approaching” on trains which are expected to arrive shortly because “1 min” is a very short period of time, and encourage you to consider doing the same.

Accessibility

We work very hard to design our Web services to be fully accessible to people with a wide range of levels of ability, including people with limited or no vision, limited mobility, cognitive disabilities and more.

While it’s up to you how to implement our data in your product and to what lengths you go to cater to audiences who are less able to interact with technology than others, we strongly encourage you to take into consideration accessibility implications on whatever platform you write for and to make sure your incorporation of public transit information helps the whole public, to the best of your ability.

We encourage you to catch up on accessibility standards such as those laid out in the Federal Section 508 guidelines, the Illinois Information Technology Accessibility Act (IITAA), as well as staying up on modern Web or software accessibility best practices. It’ll lead to better products for you and everyone who might benefit from them.

Appendix E: Error Codes

Error codes are given in the event an unexpected request was made or if an error in processing occurred. A good response comes with an error code of 0.

Arrivals API Error Codes

Follower API Error Codes

Locations API Error Codes