INRIX IQ logo
Support page documentation page INRIX IQ products page

INRIX documentation

Speeds Data Downloader

Contents

Overview

To get INRIX Roadway Analytics data downloader reports via API, there are 5 steps:

  1. Authentication: Get an auth token.
  2. Region Codes API: Look up INRIX region IDs (country, state, county) needed for region-based requests.
  3. Data Downloader API: Make an async report request, using the auth token. This call returns a report ID only.
  4. Report Status API: Call this to get current processing status of the report ID returned in step 3.
  5. Get the report link, using the report ID returned in step 3.

Step 1: Authentication

All API calls in this document require a valid auth token. See the INRIX authentication guide for details on obtaining and refreshing tokens:

INRIX Authentication Guide

Step 2: Region Codes API

Use these APIs to look up the INRIX region IDs (countryId, stateIds, countyIds) required to populate the regions parameter of the Data Downloader request.

Endpoint https://analytics-segments-api.inrix.com

Get All Countries

Returns a list of all available countries with their INRIX IDs.

GET /v3/countries
Authorization: Bearer <access_token>

Example Response:

{
    "responseId": "2bf238d3-9398-43c7-9095-753b3910fb58",
    "version": 3,
    "locale": "en_US",
    "mapVersion": "2002",
    "countries": [
        { "id": 27, "name": "United States" },
        { "id": 28, "name": "Canada" },
        { "id": 1, "name": "United Kingdom" },
        { "id": 73, "name": "México" }
    ]
}

Get a Single Country

GET /v3/countries/{countryId}
Authorization: Bearer <access_token>

Example: GET /v3/countries/27

{
    "responseId": "c34ec427-dfc2-41b4-96e1-8178ab29ccd1",
    "version": 3,
    "locale": "en_US",
    "countryId": 27,
    "name": "United States"
}

Get All States for a Country

Returns all states/provinces for a given country.

GET /v3/countries/{countryId}/states
Authorization: Bearer <access_token>

Example: GET /v3/countries/27/states

{
    "responseId": "1e343b59-93cf-4956-b957-b79898a991c0",
    "version": 3,
    "locale": "en_US",
    "mapVersion": "2002",
    "countryId": 27,
    "countryName": "United States",
    "states": [
        { "id": 273, "name": "Louisiana" },
        { "id": 265, "name": "Illinois" },
        { "id": 264, "name": "Florida" },
        { "id": 237, "name": "California" }
    ]
}

Get a Single State

GET /v3/countries/{countryId}/states/{stateId}
Authorization: Bearer <access_token>

Example: GET /v3/countries/27/states/273

{
    "responseId": "eabd912c-314e-44c3-b8cd-8b74663e4548",
    "version": 3,
    "locale": "en_US",
    "countryId": 27,
    "stateId": 273,
    "name": "Louisiana"
}

Get All Counties for a State

Returns all counties for a given country/state combination.

GET /v3/countries/{countryId}/states/{stateId}/counties
Authorization: Bearer <access_token>

Example: GET /v3/countries/27/states/273/counties

{
    "responseId": "1ecfd8f4-1f47-4f6a-9012-720b8efe30a4",
    "version": 3,
    "locale": "en_US",
    "mapVersion": "2002",
    "countryId": 27,
    "countryName": "United States",
    "stateName": "Louisiana",
    "stateId": 273,
    "counties": [
        { "id": 32320, "name": "Acadia" },
        { "id": 32321, "name": "Vermilion" },
        { "id": 32331, "name": "East Baton Rouge" }
    ]
}

Get a Single County

GET /v3/countries/{countryId}/states/{stateId}/counties/{countyId}
Authorization: Bearer <access_token>

Example: GET /v3/countries/27/states/273/counties/32320

{
    "responseId": "016d7142-1a71-4a08-8601-1b2af8d2b7e6",
    "version": 3,
    "locale": "en_US",
    "countryId": 27,
    "stateId": 273,
    "countyId": 32320,
    "name": "Acadia"
}

Get Region Boundary

Returns the geographic boundary and envelope for a region, along with the XD ID segment count.

POST /v3/boundary
Authorization: Bearer <access_token>
Content-Type: application/json
Parameter Required Default Description
mapVersion No latest Map version string
publicSegmentType Yes   Segment type (e.g., "XD")
countryId Yes   INRIX country ID
stateIds No   Array of state IDs
countyIds No   Array of county IDs
frcs No   Functional Road Class filter
directionSuffixes No   Direction filter

Example: Get boundary and XD ID count for Louisiana FRC 3 roads

{
    "mapVersion": "2001",
    "publicSegmentType": "XD",
    "countryId": 27,
    "stateIds": [273],
    "frcs": [3]
}

Response:

{
    "responseId": "db5a90e9-7491-44ef-8cb9-dfc25ff0fda6",
    "version": 3,
    "mapVersion": "2001",
    "count": 11134,
    "regionBoundaries": [
        {
            "countryId": 27,
            "stateId": 273,
            "countyId": null,
            "boundaryString": "{\"type\":\"MultiPolygon\",\"coordinates\":...}",
            "envelopeString": "{\"type\":\"Polygon\",\"coordinates\":...}"
        }
    ]
}

Step 3: Data Downloader API

This API is used to create a report. The report is queued up for processing and is delivered asynchronously.

Endpoint: https://roadway-analytics-api.inrix.com/v1/data-downloader

New Report Request

There are three report request modes:

Mode Field Description
Region regions Specify geographic regions using INRIX country/state/county IDs
XD Segments xdSegIds Provide a list of XD segment IDs directly
Polygon locations Define a GeoJSON polygon to select all segments within the area

A new report can be created by providing the following parameters:

Parameter Type Required Description
mapVersion string No The map version for the segments. INRIX updates the map version twice per year (March and September). Defaults to the latest map version if omitted.
userName string No A name, in the format First Last, for the user.
xdSegIds int[] Conditional An array of integers representing the XD segment IDs.
regions object[] Conditional An array of region objects. See Reference: Regions Object Definition.
locations object[] Conditional An array of location objects containing GeoJSON polygon geometry. See Reference: Locations Object Definition. Max 1 polygon per request.
granularity int No One of 1, 5, 15, or 60. Defaults to 60 if omitted.
unit string Yes METRIC or IMPERIAL.
fields string[] No Columns to include in the report (see below). Defaults to ["SOE_SPEED"].
dateRanges object[] Yes Array of objects with start, end (ISO 8601 YYYY-MM-DD), and optional daysOfWeek.
daysOfWeek int[] No Array of integers, Monday (1) through Sunday (7). Max length 7, each element unique.
timeRanges object[] No Array of objects with start and end times (HH:MM format). If omitted, the entire day is assumed.
timezone string Yes INRIX timezone string (e.g., EST5EDT, PST8PDT, America/Los_Angeles).
useRealSpeed boolean No If true, only speeds with score of 30 are returned. Default: false.
emailAddresses string[] No Email addresses to receive the completed report.
includeClosures boolean No Whether to include closure data.

Available fields values:

Note: XDSEGID and LOCAL_DATE_TIME are always included in the output data.

Example Request — Data Download for Region

POST https://roadway-analytics-api.inrix.com/v1/data-downloader
Content-Type: application/json
Authorization: Bearer [access_token_here]

{
   "unit": "IMPERIAL",
   "fields": ["LOCAL_DATE_TIME", "XDSEGID", "SPEED", "NAS_SPEED", "CVALUE", "CLOSURE"],
   "regions": [
      {
         "name": "California-Ventura",
         "stateIds": [237],
         "countryId": 27,
         "countyIds": [30158],
         "postalCodes": null,
         "roadClasses": [1, 2]
      }
   ],
   "timezone": "PST8PDT",
   "xdSegIds": null,
   "corridors": null,
   "dateRanges": [
      {
         "end": "2019-03-01",
         "start": "2019-01-01",
         "daysOfWeek": null
      }
   ],
   "mapVersion": "2302",
   "reportType": "DATA_DOWNLOAD",
   "timeRanges": [],
   "granularity": 1,
   "useRealSpeed": false,
   "emailAddresses": ["ra-user@example.com"],
   "includeClosures": true
}

Example Response — Data Download for Region

{
  "reportId": "dbdf11c0-a81f-4e6b-8845-772671d74dbb",
  "progress": "0% completed",
  "state": "QUEUED",
  "submittedOn": "2017-09-20T01:05:39.678Z",
  "type": "DATA_DOWNLOAD",
  "errorCode": 0
}

Example Request — Data Download for List of XD Segments

POST https://roadway-analytics-api.inrix.com/v1/data-downloader
Content-Type: application/json
Authorization: Bearer [access_token_here]

{
   "unit": "IMPERIAL",
   "fields": ["LOCAL_DATE_TIME", "XDSEGID", "UTC_DATE_TIME", "SPEED", "NAS_SPEED",
              "REF_SPEED", "TRAVEL_TIME", "CVALUE", "SCORE"],
   "xdSegIds": [1282809716, 1282817650],
   "timezone": "America/Phoenix",
   "dateRanges": [
      {
         "end": "2017-10-01",
         "start": "2017-10-02",
         "daysOfWeek": [1, 2, 3, 4, 5, 6, 7]
      }
   ],
   "mapVersion": "2302",
   "reportType": "DATA_DOWNLOAD",
   "granularity": 1,
   "emailAddresses": ["ra-user@example.com"]
}

Example Response — Data Download for List of XD Segments

{
  "reportId": "dbdf11c0-a81f-4e6b-8845-772671d74dbb",
  "progress": "0% completed",
  "state": "QUEUED",
  "submittedOn": "2017-09-20T01:05:39.678Z",
  "type": "DATA_DOWNLOAD",
  "errorCode": 0
}

Polygon Mode

Overview

The polygon mode uses the locations field in the Data Downloader API request, enabling users to define an area of interest using GeoJSON Polygon geometry rather than specifying individual XD segment IDs or INRIX region hierarchies. The system resolves all XD segments that fall within the polygon boundary and generates the report for those segments.

How It Works

  1. Request Submission — Send a POST to /v1/data-downloader with a locations array containing one Location object. Each Location contains a GeoJSON geometry (type Polygon) and an optional roadClasses (Functional Road Classes) filter.

  2. Validation — The request is validated for:
    • Max polygon count: Only 1 polygon is allowed per request.
    • Point count check: Total polygon vertex count must not exceed 6,000 points.
    • Area size check: The polygon area must not exceed 6,000 square miles.
    • Segment coverage check: The polygon must contain at least one XD segment.

  3. Row Count Estimation — The estimated row count for the polygon area is calculated and checked against the maximum records limit, alongside any regions, corridors, and xdSegIds in the same request.

  4. Report Generation — Once validated, the report is queued for asynchronous processing.

Limits

Rule Limit
Max polygons per request 1
Max total vertex count 6,000 points
Max polygon area 6,000 sq mi
Polygon must contain segments ≥ 1 segment

Example Request — Data Download for Polygon

POST https://roadway-analytics-api.inrix.com/v1/data-downloader
Content-Type: application/json
Authorization: Bearer [access_token_here]

{
   "unit": "IMPERIAL",
   "fields": ["LOCAL_DATE_TIME", "XDSEGID", "SPEED", "NAS_SPEED", "CVALUE"],
   "locations": [
      {
         "geometry": {
            "type": "Polygon",
            "coordinates": [
               [
                  [-122.4194, 37.7749],
                  [-122.4194, 37.8049],
                  [-122.3894, 37.8049],
                  [-122.3894, 37.7749],
                  [-122.4194, 37.7749]
               ]
            ]
         },
         "roadClasses": [1, 2, 3]
      }
   ],
   "timezone": "America/Los_Angeles",
   "dateRanges": [
      {
         "start": "2026-01-01",
         "end": "2026-01-31",
         "daysOfWeek": [1, 2, 3, 4, 5]
      }
   ],
   "granularity": 15,
   "useRealSpeed": false,
   "emailAddresses": ["ra-user@example.com"],
   "includeClosures": true
}

Notes:

  • The geometry object follows the GeoJSON Polygon specification. The coordinate ring must be closed (first and last coordinates must be identical).
  • roadClasses (FRCs) is optional; if omitted, all road classes within the polygon are included.
  • mapVersion may be omitted — it defaults to the latest available map version.
  • The locations field is mutually independent of regions and xdSegIds, though using multiple selection modes in a single request is technically supported (segment counts from all modes are aggregated for the row limit check).

Example Response

{
  "reportId": "a6d8ae67-24ff-452d-aaad-8e10e16c54e3",
  "progress": "0% completed",
  "state": "QUEUED",
  "submittedOn": "2026-01-15T10:30:00.000Z",
  "type": "DATA_DOWNLOAD",
  "errorCode": 0
}

Validate-Only Endpoint

A validation-only endpoint is also available to pre-validate a polygon request without actually creating a report:

POST https://roadway-analytics-api.inrix.com/v1/data-downloader/validate
Content-Type: application/json
Authorization: Bearer [access_token_here]

The request body is identical to a regular report creation request. Returns 200 OK if validation passes, or the appropriate error response if validation fails.

Step 4: Get Report Status

Once a report ID is generated, use this API to get current report processing status.

Example Request — Report Status

GET https://roadway-analytics-api.inrix.com/v1/report/status/{reportId}
Authorization: Bearer [access_token_here]

Example Response — Report Status

{
   "reportId": "141b1db5-5b29-4fa7-9849-305d1ae49995",
   "progress": "0% completed",
   "state": "IN_PROGRESS",
   "submittedOn": "2017-10-03T17:30:56.692Z",
   "type": "DATA_DOWNLOAD",
   "errorCode": 0
}

Step 5: Get Report Data

Once a report has been completely processed, use this API to get the report download link(s). If called for reports that have not been completed, it will return an error.

Example Request — Get Report Data Link(s)

GET https://roadway-analytics-api.inrix.com/v1/data-downloader/{reportId}
Authorization: Bearer [access_token_here]

Example Response — Get Report Data Link(s)

{
  "reportId": "a6d8ae67-24ff-452d-aaad-8e10e16c54e3",
  "urls": [
    "https://inrix-roadwayanalytics.s3.us-west-2.amazonaws.com/datadownloader/reports/.../report_part_1.zip?..."
  ]
}

Reference: Regions Object Definition

A region object contains the following fields:

Field Type Required Description
name string Yes User-given name for the region
countryId int Yes Internal INRIX ID for the country
stateIds int[] No INRIX IDs for states within the country
countyIds int[] No INRIX IDs for counties within the states
postalCodes string[] No Postal codes to filter by
roadClasses int[] No FRC (Functional Road Class) filter

Example

{
   "regions": [
      {
         "name": "OH",
         "countryId": 27,
         "stateIds": [236],
         "countyIds": [30151],
         "postalCodes": ["85001"],
         "roadClasses": [1, 2, 3, 4, 5]
      }
   ]
}

Reference: Locations Object Definition (Polygon Support)

A location object specifies an area of interest using GeoJSON polygon geometry. The system resolves all XD segments within the polygon boundary for the report.

Field Type Required Description
geometry GeoJSON Polygon Yes A GeoJSON Polygon object with type and coordinates fields. The coordinate ring must be closed.
roadClasses int[] No FRC (Functional Road Class) filter. If omitted, all road classes within the polygon are included.

Constraints

Example

{
   "locations": [
      {
         "geometry": {
            "type": "Polygon",
            "coordinates": [
               [
                  [-122.2283935546875, 47.466512753542865],
                  [-122.22066879272461, 47.466512753542865],
                  [-122.22066879272461, 47.46848551035858],
                  [-122.2283935546875, 47.46848551035858],
                  [-122.2283935546875, 47.466512753542865]
               ]
            ]
         },
         "roadClasses": [1, 2, 3]
      }
   ]
}