Skip to main content

Data format

Mapbox Traffic Data consists of two different types of files:

  • Typical: The Typical traffic data file contains speeds that show normal traffic conditions throughout the week. The Typical traffic data set is an estimate for traffic speeds at a specific location, at a specific time, based on historical observations. This data shows traffic expectations during a normal week.
  • Live: The Live traffic data file contains speeds that have been directly observed in the 15 minutes before data generation. The Live traffic data set is most useful if there is unexpected traffic — for instance, during severe weather events or accidents.

Speeds are associated with either pairs of adjacent OpenStreetMap node IDs or OpenLR strings, depending on customer preference. Each pair of OpenStreetMap IDs marks the start and end of the road segment. OpenLR strings are base64-encoded binary representations of the OpenLR location reference for the road segment, which usually only includes the location reference points at the start and end of the way. Intermediate location reference points are included for roads longer than 15 kilometers. All speeds are in kilometers per hour.

Quadkeys

Data is stored in files specific to a Zoom 7 quadkey, as described in the OpenStreetMap zoom levels specification. Each Zoom 7 tile is large enough to capture a major metropolitan area, small US state, or small European country. You can view tiles using the What the Tile interactive tool.

Data updates

Mapbox Traffic Data files are updated on a regular cadence:

  • Typical traffic is updated monthly. Each month, you should overwrite the results of the previous month with the new data.
  • Live traffic is updated every five minutes, based on data that is less than 15 minutes old.

Typical data file

Typical predictions are stored for every five-minute period of a typical week. For every road segment, there will be 2,016 typical speed predictions (7 days × 24 hours × 12 five-minute periods).

Typical file S3 naming schema

Typical speed data is stored as gzipped CSV files, divided into separate files by Z7 quadkey and time zone using the following naming schema:

s3://<bucket_name>/typical-speeds/<Z7_quadkey>/<time_zone>/<Z7_quadkey>-<time_zone>.csv.gz

For example, if your company username was ABC, and you were using Typical traffic data for the New York area, the filename would be:

s3://mapbox-traffic-data-abc-shared/typical-speeds/0320101/America-New_York/0320101-America-New_York.csv.gz

The time_zone for each file is defined by the IANA time zone database. Note that the slashes (/) used by IANA are replaced with dashes (-) in Traffic Data filenames. In the example filename above, the IANA timezone America/New_York becomes America-New_York.

Typical file contents

In their uncompressed form, each CSV file contains one line per road segment: segment_identifier,speed_1,speed_2,…,speed_2016

  • segment_identifier: Either a comma-separated pair of OpenStreetMap node IDs or an OpenLR string.
  • speed_1,speed_2,…,speed_2016: 2,016 comma-separated integer speeds in kilometers per hour, starting at 0:00 Sunday in the file’s time zone. Each value shows the usual speed during a five-minute period of a typical week within that road segment.

The following example uses OpenStreetMap node IDs as segment identifiers:

osm_start_nodeosm_end_nodespeed_1speed_2...speed_2016
1130545331130967575454...57
1701901941701901949393...98
1726378111726378107064...66

Alternatively, the files with OpenLR segment identifiers will have a single column for the OpenLR string instead of the osm_start_node and osm_end_node columns.

The headers in this example are for demonstration purposes. The Typical files that you download will not have headers.

Find a specific time in the Typical file

To find a speed for a specific five-minute increment, you must count the segment identifier columns and the number of five-minute increments between Sunday at 00:00 and the time for which you are looking.

For example, if you were looking for the typical speed for a segment between 9:00 and 9:05 AM on Monday in a file with OpenStreetMap nodes, you would add the two columns for the nodes and the 396 five-minute intervals between Sunday at 0:00 AM and Monday at 9:00 AM, leading you to took at the 399th column for this data.

Data considerations for the Typical file

  • Not all segments in a tile have an estimated speed.
  • Segments without enough data for an accurate prediction are omitted.
  • Segments that overlap a time zone boundary or Z7 tile boundary may appear in two files.
  • Speed estimates correspond only to the traffic that matches the ordering of the segment identifier. Node pairs that carry bidirectional traffic will have up to two different rows in each file, each row corresponding to the ordering of the node pair.
    • For example, if you have a two-way road with a segment between nodes "123" and "456", the estimates may be different when traveling from "123" to "456" than they are when traveling from "456" to "123".

Typical file size

The compressed file size varies depending on the density of the area covered by the tile. A dense urban tile can be approximately 2 GB. Most tiles are much smaller than this.

Live data file

Live traffic speeds are generated in real time based on speeds that have been directly observed in the 15 minutes before data generation. The Live traffic data file is updated every five minutes.

Since Live data is not available for all roads, we recommend falling back to Typical speeds when Live data is not available. Offline routing, planning, and simulation should only use Typical speeds.

Live file S3 naming schema

Live traffic data files are delivered to a shared S3 as one file per Z7 quadkey.

s3://<bucket_name>/live-speeds/latest/<Z7_quadkey>.csv

Live file contents

We deliver our most recent Live traffic estimates for a Z7 quadkey as an uncompressed CSV file.

The Live CSV file contains one line per road segment, each with two or three columns. Each line contains: segment_identifier,speed

  • segment_identifier: Either a comma-separated pair of OpenStreetMap node IDs or an OpenLR string.
  • speed: The estimated road segment speed, in kilometers per hour.

The following example uses OpenStreetMap node IDs as segment identifiers:

osm_start_nodeosm_end_nodespeed
11305453311309675754
170190194452517004993
17263781017263780970

Alternatively, the files with OpenLR segment identifiers will have a single column for the OpenLR string instead of the osm_start_node and osm_end_node columns.

The headers in this example are for demonstration purposes. The Live file that you download will not have headers.

Data considerations for the Live file

  • The Live file only provides speeds for segments for which the volume and quality of data allow a high confidence estimate.
  • Segments that overlap a time zone boundary or Z7 tile boundary may appear in two files.
  • Speed estimates correspond only to the traffic that matches the ordering of the segment identifier. Node pairs that carry bidirectional traffic will have up to two different rows in each file, each row corresponding to the ordering of the node pair.
    • For example, if you have a two-way road with a segment between nodes "123" and "456", the estimates may be different when traveling from "123" to "456" than they are when traveling from "456" to "123".

Live file size

The CSV file size for Live data is 5 MB per tile on average, which covers only roads with live traffic estimates. The file size will vary based on how populous a tile is, as well as the time of day. For example, the file for New York City's tile during rush hour could be 12 to 15 MB.

An empty file indicates that Mapbox telemetry volumes are too low to estimate a speed for any road segment in the region at the current time.

Was this page helpful?