Let's take a road trip transit journey to Valhalla, NY using Mapzen Turn-by-Turn and Transitland


Photos by Heidi Knisely

Back in February, Transitland opened up to contributions of transit data from around the world. Today we are ready announce that Mapzen Turn-by-Turn now uses data from Transitland to plan journeys on subways, buses, trains, and ferries in San Francisco and New York City. Together, Transitland and Mapzen Turn-by-Turn form the foundation of Mapzen Mobility, our new initiative to improve multimodal transportation through open data.

“Multimodal” refers to routing via walking and public transit in Mapzen Turn-by-Turn, using time-based schedules of the public transportation. We can walk to a station, utilize public transportation, disembark and walk to our final destination. By default, we try to use rail before buses and attempt to avoid transfers. However, these values can all be tweaked to your liking. Sign up for an API key and dig into our documentation to learn about the API request format.

But first let’s take a look and see what we can do! Going from Staten Island to Valhalla, NY is a long but fun trip since it contains ferry, subway, and rail maneuvers.

In the narration, we provide written departure and arrival time instructions for each transit portion of our trip.

ferry Enter the St. George Ferry Terminal station. 17 m
ferry Depart: 9:30 PM from St. George Ferry Terminal.

Take the Staten Island Ferry. (1 stop)

Arrive: 9:55 PM at Whitehall Ferry Terminal.
8.111 km
ferry Exit the Whitehall Ferry Terminal station. 30 m
pedestrian collapsing walking maneuvers
subway Enter the Bowling Green station. 22 m
subway Depart: 10:04 PM from Bowling Green.

Take the 4 toward WOODLAWN. (8 stops)

Arrive: 10:26 PM at 125 St.
12.86 km
subway Exit the 125 St station. 31 m
pedestrian Walk northwest on East 125th Street. 142 m
rail Enter the Harlem-125th St. station. 29 m
rail Depart: 10:32 PM from Harlem-125th St.

Take the Harlem toward Southeast. (3 stops)

Arrive: 11:03 PM at Valhalla.
33.316 km
rail Exit the Valhalla station. 28 m

(Normally the walking portions of the route would be included, but we’re focusing on the transit maneuvers for now.)

Use Options

As stated earlier, we can tweak our API defaults (use_bus, use_rail, and use_transfers). The defaults are use_bus = 0.3, use_rail = 0.6, and use_transfers = 0.3.

  • use_bus User’s desire to use buses. Range of values from 0 (try to avoid buses) to 1 (strong preference for riding buses).
  • use_rail User’s desire to use rail/subway/metro. Range of values from 0 (try to avoid rail) to 1 (strong preference for riding rail).
  • use_transfers User’s desire to favor transfers. Range of values from 0 (try to avoid transfers) to 1 (totally comfortable with transfers).

Note that these paramaters can be changed in the URL in the Mapzen Turn-by-Turn Transit demo.

Date and Time Options

For multimodal routes, we default to the current time, though we can specify a departure date and time. (Note that this is in the timezone of the origin location.)


  • type
    • 0 — Current depart time
    • 1 — Specified depart time
  • value
    • The date and time to depart. ISO 8601 format (YYYY-MM-DDThh:mm). For example “2016-03-29T08:06”

Say you are in San Francisco around 4th & Townsend and want to go to Beach Street by Fishermans Wharf. Also, you want to depart on March 29 at 6:30 AM (2016-03-29T06:30) favoring buses; use_bus is now set at 0.5 and use_rail set at 0.3.

Notice in the results that we take the bus in the morning at 6:35 AM and and avoid the rail lines.

pedestrian Walk southwest on Berry Street. 116 m
pedestrian Turn right onto 4th Street/Fourth Street. 210 m
pedestrian Turn right onto Townsend Street. 25 m
bus Depart: 6:35 AM from TOWNSEND ST & 4TH ST.

Take the 30 toward the Marina District. (18 stops)

Arrive: 6:56 AM at Columbus Ave & North Point St.
4.158 km
pedestrian Walk northwest on Columbus Avenue. 55 m
pedestrian Turn right onto Leavenworth Street.
184 m
pedestrian You have arrived at your destination.

How did we do it…in a nutshell:

Currently, once a week Turn by Turn’s transit_fetcher grabs transit routes, stops, schedule stop pairs (departures), operators, and route stop patterns (shapes) using the Transitland Datastore API. It saves the data to temporary transit data tiles in protocol buffer format. During the normal data update that creates routing graph tiles, a transit_builder process creates transit nodes and edges that are connected to nodes in the existing graph. Transitland associates transit stops to OpenStreetMap ways using Mapzen Turn-by-Turn’s locate method. This is done whenever transit stops are created or updated in the Transitland Datastore. In addition to modifying the routing graph, transit departures, routes, and stop information are stored within the routing tiles.

When you run a multimodal route at a specific date and time and encounter a transit node that contains schedule information, we try to obtain a departure from that node at the date and time you encountered that particular node. If a departure is found, we will “walk” the transit edges and nodes applying time costs and penalties along the way for transfers. This is repeated until the best, multimodal path is returned.

Coming soon to a city near you

Mapzen’s motto is “start where you are”, so if you see ways to improve our multimodal routing please let us know. Also, have a look at our documentation to see the structure of the API request and response and sign up for a free developer key to start using Mapzen Turn-by-Turn.

If you’re not in the SF Bay Area, the NYC metro region, or Rome, we hope to reach your part of the world with Mapzen Turn-by-Turn routing soon. Please help expand Transitland’s coverage by contributing feeds to the Feed Registry. In the coming months, we’ll be ingesting even more of these feeds into Turn-by-Turn. To see which transit operators are routable, follow this link to a filtered view of the Feed Registry. As always, should you have any questions, write to us at hello@mapzen.com.