Data format
Mapbox Traffic Data consists of two different types of files:
Typical
: TheTypical
traffic data file contains speeds that show normal traffic conditions throughout the week. TheTypical
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
: TheLive
traffic data file contains speeds that have been directly observed in the 15 minutes before data generation. TheLive
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_node | osm_end_node | speed_1 | speed_2 | ... | speed_2016 |
---|---|---|---|---|---|
113054533 | 113096757 | 54 | 54 | ... | 57 |
170190194 | 170190194 | 93 | 93 | ... | 98 |
172637811 | 172637810 | 70 | 64 | ... | 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_node | osm_end_node | speed |
---|---|---|
113054533 | 113096757 | 54 |
170190194 | 4525170049 | 93 |
172637810 | 172637809 | 70 |
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.