> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/data/traffic/llms.txt) # 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](https://wiki.openstreetmap.org/wiki/Node) or [OpenLR strings](https://github.com/tomtom-international/openlr), 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](https://wiki.openstreetmap.org/wiki/Zoom_levels). 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](https://labs.mapbox.com/what-the-tile/). ## 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](https://www.gnu.org/software/gzip/) CSV files, divided into separate files by *Z7 quadkey* and *time zone* using the following naming schema: ``` s3:///typical-speeds///-.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](https://www.iana.org/time-zones). 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:///live-speeds/latest/.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.