Accessing NextMuni vehicle prediction data

SFMTA home > Transit > Website > sfmta.com Labs > Accessing NextMuni vehicle prediction data

Note: This page contains instructions for accessing real-time transit data concerning vehicle arrival predictions. Route and schedule data, which represents intended service, is also available.

Instructions for accessing NextMuni XML data

Updated March 5, 2010 to clarify instructions for the vehicleLocations command.

Download printable version of these instructions (accessible PDF)

Included are steps for accessing and utilizing San Francisco Municipal Transportation Agency (SFMTA) information supplied within NextBus’s Extensible Markup Language (XML) feed. The XML feed data is accessed using Web addresses (URLs) with parameters specified in the query string. This document provides the URLs that can be used and examples of the XML that is returned

Before proceeding you should be familiar with XML and URL strings or representational state transfer (REST) web services.

For a brief introduction to XML please visit the sites listed below:

w3schools.com introduction to XML
CodeGuru.com introduction to XML

For a brief introduction to RESTful web services please visit the site listed below:

InfoQ.com introduction to REST

Terms & Conditions

Access to the SFMTA’s NextMuni XML data feed is granted on the following conditions:

The SFMTA provides access to the NextMuni data as a public service. Access to the data feed does not constitute a grant of a license or a grant of any rights whatsoever to the data feed. The data provided via the XML data feed are public records, but the feed is not.
A user accesses the data feed and utilizes the data at its own risk. The SFMTA disclaims any and all liability arising from or related to a user's access to the data feed or use of the data.
The SFMTA reserves the right to suspend the XML data feed, modify the feed or modify elements of the feed at any time in the SFMTA’s sole and absolute discretion.
The SFMTA will not provide any technical support of any kind to users.
No user may execute polling commands more often than every 10 seconds. A user that polls more often than that or otherwise overtaxes the SFMTA’s system may be suspended or terminated from the data feed.

Comments and suggestions regarding the data feed may be sent to: SFMTAdata@sfmta.com

Stability of XML Feed

It is intended that the commands and the resulting XML data change as little as possible in the future. There will be situations, though, when the feed will need to change. For example, the SFMTA might add other XML elements and properties. This should not affect a proper XML client because any new elements should simply be ignored by system.

Commands

The commands can be broken into several categories. There are configuration requests, prediction requests, a vehicle location request and an arrival/departure times request. The arrival/depature request is not intended for the public. The format of the URL command is:

webservices.nextbus.com/service/publicXMLFeed?command=commandName&a=sf-muni&additionParams...

Error Messages

Commands can return an Error XML object if there is some type of problem, e.g., the system has not been initialized yet or bad parameters were used in the URL. When an Error XML object is returned, it has an attribute called shouldRetry. If the error was returned only because the server was initializing, then shouldRetry will be set to true. For this case, the application should try the URL again after waiting 10 seconds. If the shouldRetry attribute is set to false, there is an error due to the URL and simply retrying the URL again will not fix the problem.

An error message looks like:

   <body>

     <Error shouldRetry="true">

       Agency server cannot accept client while status is: agency

       name = sf-muni,status = UNINITIALIZED, client count = 0, last

       even = 0 seconds ago Could not get route list for agency tag "sf-muni".

       Either the route tag is bad or the system is initializing.

      </Error>

   </body>

Configuration Requests

Note: For all commands below an agency tag, “a” should be included in the query string and set to sf-muni (i.e., a=sf-muni).

Command "routeList"

To obtain a list of routes for an agency, use the "routeList" command. The agency is specified by the "a" parameter in the query string. The tag for the agency as obtained from the agencyList command should be used.

The format of the command is:

webservices.nextbus.com/service/publicXMLFeed?command=routeList&a=sf-muni

The resulting XML will be in the following form (note: the shortTitle element is provided only if it is different than the standard title element. If no shortTitle element is provided, simply use the standard title element). For the example URL:

webservices.nextbus.com/service/publicXMLFeed?command=routeList&a=sf-muni

The resulting XML is in the form:

   <body>

     <route tag="1" title="1 - California" shortTitle="1-Calif/>

     <route tag="3" title="3 - Jackson" shortTitle="3-Jacksn"/>

     <route tag="4" title="4 - Sutter" shortTitle="4-Sutter"/>

     <route tag="5" title="5 - Fulton" shortTitle="5-Fulton"/>

     <route tag="6" title="6 - Parnassus" shortTitle="6-Parnas"/>

     <route tag="7" title="7 - Haight" shortTitle="7-Haight"/>

     <route tag="14" title="14 - Mission" shortTitle="14-Missn"/>

     <route tag="21" title="21 - Hayes" shortTitle="21-Hayes"/>

   </body>

Command "routeConfig"

To obtain a list of routes for an agency, use the "routeConfig" command. The agency is specified by the "a" parameter in the query string. The tag for the agency as obtained from the agencyList command should be used. The route is optionally specified by the "r" parameter. The tag for the route is obtained using the routeList command. If the "r" parameter is not specified, XML data for all routes for the agency is returned.

The format of the command is:

webservices.nextbus.com/service/publicXMLFeed?command=routeConfig&a=sf-muni&r=<route tag>

The resulting XML will be in the following form (note: the shortTitle element for the stops is provided only if it is different than the standard title element. If no shortTitle element is provided, simply use the standard title element). For the example URL:

webservices.nextbus.com/service/publicXMLFeed?command=routeConfig&a=sf-muni&r=N

The resulting XML is in the form:

   <body>

     <route tag="N" routeCode="27" title="N - Judah" color="003399" oppositeColor="ffffff">

       <stop tag="KINGd4S0" title="King St and 4th St" shortTitle="King & 4th" lat="37.776036" lon="-122.394355" stopId="1"/>

       <stop tag="KINGd2S0" title="King St and 2nd St" shortTitle="King & 2nd" lat="37.7796152" lon="-122.3898067" stopId="2"/>

       <stop tag="EMBRBRAN" title="Embarcadero and Brannan St" shortTitle="Embarcadero & Brannan" lat="37.7844455" lon="-122.3880081" stopId="3"/>

       <stop tag="EMBRFOLS" title="Embarcadero and Folsom St" shortTitle="Embarcadero & Folsom" lat="37.7905742" lon="-122.3896326" stopId="4"/>

...

       <direction tag="out" title="Outbound" useForUI="true">

         <stop tag="KINGd4S0"/>

         <stop tag="KINGd2S0"/>

         <stop tag="EMBRBRAN"/>

         <stop tag="EMBRFOLS"/>

         <stop tag="CVCENTF"/>

       </direction>

       <direction tag="in" title="Inbound" useForUI="true">

         <stop tag="CVCENTF"/>

         <stop tag="EMBRFOLS"/>

         <stop tag="EMBRBRAN"/>

         <stop tag="KINGd2S0"/>

         <stop tag="KINGd4S0"/>

       </direction>

       <direction tag="in_short" title="Inbound Short Run" useForUI="false">

         <stop tag="CVCENTF"/>

         <stop tag="EMBRFOLS"/>

         <stop tag="EMBRBRAN"/>

       </direction>

...

       <path>

         <point lat="37.7695171" lon="-122.4287571"/>

         <point lat="37.7695099" lon="-122.42887"/>

       </path>

       <path>

         <point lat="37.77551" lon="-122.39513"/>

         <point lat="37.77449" lon="-122.39642"/>

         <point lat="37.77413" lon="-122.39687"/>

         <point lat="37.77385" lon="-122.39721"/>

         <point lat="37.7737399" lon="-122.39734"/>

         <point lat="37.77366" lon="-122.39744"/>

         <point lat="37.77358" lon="-122.39754"/>

         <point lat="37.77346" lon="-122.39766"/>

         <point lat="37.77338" lon="-122.39772"/>

         <point lat="37.77329" lon="-122.39778"/>

         <point lat="37.77317" lon="-122.39784"/>

       </path>

       <path>

         <point lat="37.76025" lon="-122.50927"/>

         <point lat="37.76023" lon="-122.50928"/>

         <point lat="37.76017" lon="-122.50928"/>

         <point lat="37.7601299" lon="-122.50927"/>

         <point lat="37.76008" lon="-122.50924"/>

         <point lat="37.76006" lon="-122.50921"/>

         <point lat="37.7600399" lon="-122.50916"/>

         <point lat="37.76003" lon="-122.50912"/>

         <point lat="37.7600399" lon="-122.50906"/>

         <point lat="37.76005" lon="-122.50902"/>

         <point lat="37.76008" lon="-122.50898"/>

         <point lat="37.76017" lon="-122.50885"/>

       </path>

...

     </route>

   </body>

Prediction Requests

Prediction requests are used to obtain arrival/departure predictions for a stop or a set of stops.

Command "predictions"

To obtain predictions associated with a stop, use the "predictions" command. The agency is specified by the "a" parameter in the query string. The tag for the agency as obtained from the agencyList command should be used.

There are two ways to specify the stop: 1) using a stopId or 2) by specifying the route, direction and stop tags. The "stopId" is specified in the form "stopId=0001". The route is specified by the "r" parameter. The direction tag is only needed if you want directions for only particular trip patterns. But usually you can simply not specify the direction tag and get predictions for all trip patterns. The tag for the route is obtained using the routeList command. The stop is specified by the "s" parameter. The tag for the stop is obtained using the routeConfig command. One can also specify the useShortTitles=true parameter so that shorter names for the agency, route, direction and stop are returned if shorter names are available. Shorter names can be useful for smaller displays such as with wireless devices.

For small agencies that have a special agreement with NextBus, the "predictions" command can also be called with just the "a" parameter. This will cause predictions for every stop for the agency to be returned.

The predictions are returned in both seconds and minutes. The minute value is what should currently be displayed. The second value can be used to determine when the minute value will change requiring an update. Predictions should only be displayed in minutes, rounding down the number of seconds. If a stop is a departure then the additional tag isDeparture="true" is provided as part of the prediction.

The stop for which predictions will be returned can be specified using either a unique numerical stop ID that corresponds to the physical stop or by a route tag, direction tag and stop tag. The stop ID and route, direction and stop tags can all be determined using the command "routeConfig".

The format of the command for obtaining predictions for a particular stop using a stop tag is as follows. Note: for some large agencies such as sf-muni there are multiple trip patterns/directions that serve the stop. In order to get predictions for all trip patterns that serve the stop you should not specify the direction.

webservices.nextbus.com/service/publicXMLFeed?command=predictions&a=sf-muni&r=<route tag>&d=<direction tag>&s=<stop tag>

The two URLs to obtain predictions for a physical stop identified by a numerical stop ID are shown below. The first example does not specify a route tag so predictions for all routes that serve the stop will be returned. If predictions are desired for only a single route then the optional routeTag should be specified in the URL as shown in the second example.

1) webservices.nextbus.com/service/publicXMLFeed?command=predictions&a=sf-muni&stopId=<stop id>

2) webservices.nextbus.com/service/publicXMLFeed?command=predictions&a=sf-muni&stopId=<stop id>&routeTag=<route tag>

Note: Can also use the query string option useShortTitles=true to have the XML feed return short titles intended for display devices with small screens.

An example of obtaining predictions by specifying a route, direction and stop tag is shown below.

webservices.nextbus.com/service/publicXMLFeed?command=predictions&a=sf-muni&r=N&s=5205&useShortTitles=true

The resulting XML is in the form:

   <body>

     <predictions agencyTitle="San Francisco Muni, CA" routeTag="N" routeCode="1" routeTitle="N - Judah" stopTitle="Civic Center Station Outbound">

       <direction title="Outbound toward Ocean Beach" >

         <prediction seconds="563" minutes="9" epochTime="1229637162309" isDeparture="false" dirTag="N__OB2" block="9703" />

         <prediction seconds="1250" minutes="20" epochTime="1229638264817" isDeparture="false" dirTag="N__OB2" block="9702" />

       </direction>

       <direction title="Outbound to 34th Ave" >

         <prediction seconds="123" minutes="2" epochTime="1229637162309" isDeparture="true" dirTag="N__OB1" block="9708" />

         <prediction seconds="621" minutes="10" epochTime="1229637162309" isDeparture="true" dirTag="N__OB1" block="9707" />

       </direction>

       <message text="No Muni metro service btwn Caltrain/Embarc. &amp; Castro after 10pm Mon-Fri. Bus service provided."/>

     </predictions>

   </body>

Note: the predictions are grouped by direction. For situations where buses on a line have different destinations because some turn back earlier than others, the predictions presented to the user can provide this important piece of information.

Command "predictionsForMultiStops"

To obtain predictions associated with multiple stops, use the "predictionsForMultiStops" command. The agency is specified by the "a" parameter in the query string. The tag for the agency as obtained from the agencyList command should be used. The stops are specified by using the "stops" parameter multiple times. Each stop is separated by the "|" character and each stop is represented by a route, direction and stop identifier, concatenated together. One can also specify the useShortTitles=true parameter so that shorter names for the agency, route, direction and stop are returned if shorter names are available. Shorter names can be useful for smaller displays such as with wireless devices.

Predictions should only be displayed in minutes, rounding down the number of seconds.

The format of the command for obtaining predictions for a list of stops is (where a stop specified is a route tag and a stop tag separated by the "|" character):

webservices.nextbus.com/service/publicXMLFeed?command=predictions&a=sf-muni&stops=<stop 1>&stops=<stop 2>&stops=<stop 3>

For the example URL:

webservices.nextbus.com/service/publicXMLFeed?command=predictionsForMultiStops&a=sf-muni&stops=N|null|6997&stops=N|null|3909

The resulting XML will be in the form:

   <body>

     <direction title="Outbound toward Ocean Beach">

       <predictions stopTitle="Civic Center Station Outbound" routeCode="1" routeTitle="N - Judah">

         <prediction seconds="218" minutes="3" epochTime="1229637162309" isDeparture="false" />

         <prediction seconds="976" minutes="16" epochTime="122963716923" isDeparture="false" />

       </predictions>

     </direction>

     <direction title="Outbound toward Ocean Beach">

       <predictions stopTitle="Carl St and Cole St" routeCode="1" routeTitle="N - Judah">

         <prediction seconds="763" minutes="12" epochTime="1229637123422" isDeparture="false" />

         <prediction seconds="1281" minutes="21" epochTime="1229637168293" isDeparture="false" />

         <prediction seconds="1521" minutes="25" epochTime="1229637302334" isDeparture="false" />

         <prediction seconds="2027" minutes="33" epochTime="1229637430203" isDeparture="false" />

         <prediction seconds="2747" minutes="45" epochTime="1229637502034" isDeparture="false" />

       </predictions>

     </direction>

   </body>

Vehicle Location Requests

Vehicle locations are used to draw vehicles on a map or to simply store them in a database. The vehicle locations must not be polled more than once every 10 seconds.

Command "vehicleLocations"

To obtain a list of current vehicle locations for vehicles whose locations have changed since a specified time, use the "vehicleLocations" command.. The tag for the agency as obtained from the agencyList command should be used. The route is specified by the "r" parameter. The tag for the route is obtained using the routeList command.

The 't' parameter specifies the previous time that is to be compared to the current time; the value for 't' would normally be the time parameter value of the lastTime node that was returned as part of the result of your program's immediately previous request of the vehicleLocations command. The time is specified in milliseconds (msec) since the epoch. If you specify a time of 0, then lastTime is taken to mean 15 minutes before the command request.

The format of the command for obtaining vehicle location is:

webservices.nextbus.com/service/publicXMLFeed?command=vehicleLocations&a=sf-muni&r=<route tag>&t=<epoch time in msec>

For the example URL:

webservices.nextbus.com/service/publicXMLFeed?command=vehicleLocations&a=sf-muni&r=N&t=1144953500233

The resulting XML is in the form:

   <body>

     <vehicle id="1453" routeTag="N" dirTag="out" lat="37.7664199" lon="-122.44896" secsSinceReport="29" predictable="true" heading="276"/>

     <vehicle id="1549" routeTag="N" dirTag="in" lat="37.77631" lon="-122.3941" secsSinceReport="3" predictable="true" heading="45"/>

     <vehicle id="1517" routeTag="N" dirTag="in_short" lat="37.76035" lon="-122.50794" secsSinceReport="69" predictable="true" heading="267"/>

     <vehicle id="1547" routeTag="N" dirTag="out" lat="37.76952" lon="-122.43174" secsSinceReport="28" predictable="true" heading="85"/>

     <vehicle id="1404" routeTag="N" dirTag="out" lat="37.76003" lon="-122.50919" secsSinceReport="9" predictable="true" heading="117"/>

     <vehicle id="1400" routeTag="N" dirTag="in" lat="37.76415" lon="-122.46409" secsSinceReport="50" predictable="true" heading="266"/>

     <lastTime time="1144953510433"/>

   </body>

and the next vehicleLocations command your program would issue would be the following:

webservices.nextbus.com/service/publicXMLFeed?command=vehicleLocations&a=sf-muni&r=N&t=1144953510433

Explore:

Legal Info
Site Accessibility
Site Map
sfmta.com Labs
Topics

Search for

Transit only
entire site

Share/follow:
Shortcut to this page:
- www.sfmta.com/
  nextmunidata
Transit links:
- Top
- Updates
- Routes & Schedules
- Maps
- Fares & Sales
- Customer Info
- Fleet Info
- Meetings
- Projects & Planning
- Reports/About
- >> Contact Transit
Sitewide links:
- SFMTA Home
- Site Map
- Legal
- About sfmta.com
- Contact Us
- Dial 311 (24/7)
- 511 Transit
- SF City & County website
Visit the 311 Self-service portal


Transit Bike Livable Streets Taxi Walk Parking Traffic About Us

Legal Info Site Accessibility Site Map sfmta.com Labs Topics