Data Download Service
The data download service is used for querying available data and downloading the data as needed. The data should be sharing static data that is either common to all customers or generated for specific customers. Map release data is the first to be supported. And it can be extended to support other product deliverables that are static in nature. Generally, all data are organized in a hierarchy based on their nature. The top level is always the product the file belongs to, and then followed by necessary sub levels, down to each individual data file. For example, HERE map data are organized in a hierarchy like:
- Top level Product: Map Release
- Sub level Datasets: XDReplaced, OSMConflation, TMCRemoved, XDRemoved, OpenLRDictionaryFiles, GeoJSON, TMCAdded, Shapefiles, TMCReplaced, XDAdded
- Lowest level: Data files under each dataset.
All APIs requires authentication. You need to get the auth token from INRIX User Account System before you make service API call.
The service production endpoint, which should only be used with real data, is: https://mapdata.inrix.io
For testing purposes the “qa” endpoint is available: https://mapdata.qa.inrix.io
Instead of using service APIs for data downloading, a portal (https://iq.inrix.com) is provided.
Below are the service URLs:
QA: https://map-data-downloader.qa.inrix.com
Prod: https://map-data-downloader.inrix.com
Programmatically Access Data
To programmatically access any INRIX data files provided by data download service, please follow the below flow diagram. There are a couple of things to do to get the right file you want:
- Obtain the INRIX UAS token
- Use your UAS (User Authentication Service) credentials to get an INRIX UAS token.
- This token can be either an app token or a user token.
- Ensure that your application or user account has the appropriate permissions to access the data. The service will verify your token’s permissions and determine whether you are authorized to access the requested data.
- Verify Data Availability
- Check if the desired data is available on the service.
- Each data file is identified by a unique ID, file name, and other attributes such as product, version, dataset, country, state, etc.
- Start by searching for the file using attributes like product, version, and dataset.
- Once you identify the correct product and version, locate the specific data file.
- The INRIX sales team can assist you in identifying the correct product you’ve purchased. For instance, OSM-based volume profiles data files might belong to the product “OSM” and the dataset “VolumeProfilesParquet” if you’re looking for files in parquet format.
- Download the data file
- After identifying the correct file using its unique ID, proceed with downloading the data file via the appropriate API.
The following image is the general flow that should be adopted when downloading the data file.
Sample API flow to download the Volume Profile
-
Identify the product and dataset the file belongs to
GET https://mapdata.inrix.io/v1/datasummary/products?accesstoken={INRIX UAS token}
The response includes many products. And you will find volume profile related products like below
{
“dataProduct”: “OSM”,
“versions”: [
{
“version”: “20231201”,
“datasets”: [
“VolumeProfilesParquet”,
“Shapefiles”,
“GeoJSON”
]
},
{
“version”: “20221201”,
“datasets”: [
“Shapefiles”,
“VolumeProfiles”,
“GeoJSON”,
“VolumeProfilesParquet”
]
}
]
},
{
“dataProduct”: “MapRelease”,
“versions”: [
{
“version”: “23.2”,
“datasets”: [
“OpenLRDictionaryFiles”,
“SpeedProfiles”,
“Shapefiles”,
“VolumeProfilesParquet”,
“GeoJSON”,
“XDRemoved”,
“OSMConflation”,
“XDAdded”,
“SpeedShapes”
]
},
{
“version”: “22.2”,
“datasets”: [
“Shapefiles”,
“SpeedShapes”,
“VolumeProfilesParquet”,
“GeoJSON”,
“SpeedProfiles”,
“OpenLRDictionaryFiles”,
“XDRemoved”,
“VolumeProfiles”,
“OSMConflation”,
“XDAdded”
]
}
]
} -
Then the call to check available files under the expected product, version, and dataset. https://mapdata.inrix.io/v1/datasummary/bycountry?dataproduct={product name}&version={version}&accesstoken={INRIX UAS token}
The response includes all available files under the product, version, and dataset. For example,
{
“isoCode”: “USA”,
“version”: “20231201”,
“dataProduct”: “OSM”,
“datasets”: [
{
“name”: “VolumeProfilesParquet”,
“fileCount”: 98,
“files”: [
{
“id”: “15e83f48-60ba-4635-88a6-9d9ab087cb9e”,
“fileName”: “INRIX_OSM_VOLUME_2023_VIRGINIA.2.snappy.parquet”
},
{
“id”: “a0c46e0e-a491-4245-adb2-34374ef6137c”,
“fileName”: “INRIX_OSM_VOLUME_2023_MINNESOTA.0.snappy.parquet”
},
{
“id”: “ff698afe-55b2-451e-8510-ff0c0edbd643”,
“fileName”: “INRIX_OSM_VOLUME_2023_MINNESOTA.1.snappy.parquet”
},
{
“id”: “d40a72df-4290-424d-8b19-6b65a7132ca2”,
“fileName”: “INRIX_OSM_VOLUME_2023_MISSOURI.0.snappy.parquet”
},
…
]
}
]
} -
Call data download API to start the download process POST https://mapdata.inrix.io/v1/datadownload?accesstoken={UAS token}
Postbody:
{
“dataFileIds”:[
“976452ab-397a-46cb-b1a0-359fba04bda1” //id in the response of the above API
]
}
The response will tell you if the download task is accepted or not. For example, an accepted response looks like:
{
“result”: {
“taskId”: “10b0c499-42db-4169-8f79-f216b055b5d2”,
“status”: “QUEUED”
},
“copyright”: “Copyright INRIX Inc.”,
“createdDate”: “2024-08-26T19:45:19.641867Z”,
“responseId”: “34bdbc4c-5356-42b9-aeac-79a0aaa083b9”
} -
Call data download API to get the data file package on S3. https://mapdata.inrix.io/v1/datadownload/10b0c499-42db-4169-8f79-f216b055b5d2?accesstoken={UAS token}
The response includes the status of the task and the package link if it is finished. For example, a finished response looks like:
{
“result”: {
“taskId”: “90b0c499-42db-4169-8f79-f216b055b5d2”,
“downloadUrl”: “https://dataservicedelivery.s3.us-west-2.amazonaws.com/90b0c499-42db-4169-8f79-f216b055b5d2/USA_WI_OSM_20221201_segments_geojson.zip?X-Ad66036ce08909b9a3”,
“status”: “FINISHED”
},
“copyright”: “Copyright INRIX Inc.”,
“createdDate”: “2024-08-26T19:47:27.845772Z”,
“responseId”: “65d9b4a3-a0fc-4c5b-8bfd-ea610552d773”
}
Once finished you can then use the URL to download the zip file containing the data like you download a normal S3 file.
/v1/datasummary/products
GET get the overall supported products' information
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datasummary/products?accessToken={UAStoken}
Responses
200 Success
{
"result": [
{
"dataProduct": "Traffic",
"versions": [
{
"version": "20.1",
"datasets": [
"Speed"
]
},
{
"version": "19.2",
"datasets": [
"Routing"
]
}
]
},
{
"dataProduct": "MapRelease",
"versions": [
{
"version": "20.1",
"datasets": [
"GeoJSON",
"OpenLRDictionaryFiles",
"Shapefiles"
]
}
]
}
],
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datasummary/bycountry
GET get the product summary organized by country for a given product version
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
| dataProduct | Query | String | the name of the product from v1/datasummary/products API |
| version | Query | String | the version of the product from v1/datasummary/products API |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datasummary/bycountry?accessToken={UAStoken}
Responses
200 Success
{
"result": [
{
"isoCode": "DNK",
"version": "20.1",
"dataProduct": "MapRelease",
"datasets": [
{
"name": "TMCAdded",
"fileCount": 1,
"files": [
"DENMARK.csv"
]
},
{
"name": "XDRemoved",
"fileCount": 1,
"files": [
"DENMARK.csv"
]
},
{
"name": "OpenLRDictionaryFiles",
"fileCount": 2,
"files": [
"DNK_GeoId-58_OLRDictionary.gz",
"DNK_GeoId-57_OLRDictionary.gz"
]
}
]
},
{
"isoCode": "CHE",
"version": "20.1",
"dataProduct": "MapRelease",
"datasets": [
{
"name": "TMCAdded",
"fileCount": 1,
"files": [
"SWITZERLAND.csv"
]
}
]
},
],
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datasummary/bydataset
GET get the product summary organized by dataset for a given product version
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
| dataProduct | Query | String | the name of the product from v1/datasummary/products API |
| version | Query | String | the version of the product from v1/datasummary/products API |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datasummary/bydataset?accessToken={UAStoken}
Responses
200 Success
{
"result": [
{
"dataset": "XDAdded",
"version": "20.1",
"dataProduct": "MapRelease",
"countries": [
{
"isoCode": "DNK",
"fileCount": 1,
"files": [
"DENMARK.csv"
]
},
{
"isoCode": "CHE",
"fileCount": 1,
"files": [
"SWITZERLAND.csv"
]
},
{
"name": "OpenLRDictionaryFiles",
"fileCount": 2,
"files": [
"DNK_GeoId-58_OLRDictionary.gz",
"DNK_GeoId-57_OLRDictionary.gz"
]
}
]
},
{
"dataset": "Shapefiles",
"version": "20.1",
"dataProduct": "MapRelease",
"countries": [
{
"isoCode": "DNK",
"fileCount": 1,
"files": [
"Denmark_shapefile.zip"
]
},
{
"isoCode": "GBR",
"fileCount": 7,
"files": [
"UK_All_shapefile.zip",
"UK_Scotland_shapefile.zip",
"UK_Northern_Ireland_shapefile.zip",
"UK_Wales_shapefile.zip",
"UK_Jersey_shapefile.zip",
"UK_Guernsey_shapefile.zip",
"UK_England_shapefile.zip"
]
}
]
}
],
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datadownload
POST submit a data download request based on the provided search criteria, such as data product, dataset, version, countrycode, datafile id, geoid and statecode, etc. The query works depends on the combination of these criteria
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
| dataproduct | Query | String | the name of the data product the data files belong to. It is required if data file id is not provided |
| dataset | Body | String | the name of the dataset the data files belong to. It is required if data file id or geoid is not provided |
| version | Body | String | the version of the product. It is required if data file id is not provided |
| geoids | Body | Array of | the list of geoid to which the data file belongs |
| countrycode | Body | String | the iso-3 code of the country the data files belong to. It is required if data file id or geoid is not provided |
| statecode | Body | String | the 2-letter code of the state or province the data files belong to if it is available |
| datafileids | Body | Array of | a list of the data file ids. This parameter does not require any other parameters |
Requests
Example Submit a download request to ask for all files given country AUT, version 20.1 and dataset OpenLRDictionaryFiles
Queryhttps://mapdata.inrix.io/v1/datadownload?accessToken={UAStoken}
Body{
"dataset": "OpenLRDictionaryFiles",
"version": "20.1",
"countrycode": "AUT"
}Responses
200 Success
{
"result": {
"taskId": "b17523d5-6349-45cd-b039-d4266735b514",
"status": "QUEUED"
},
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datadownload/{taskid}
GET check the status of the submitted download task.
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datadownload/b17523d5-6349-45cd-b039-d4266735b514?accessToken={UAStoken}
Responses
200 Success
{
"result": {
"taskId": "b17523d5-6349-45cd-b039-d4266735b514",
"downloadUrl":"a pre-signed url"
"status": "FINISHED"
},
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datafiles
GET query the detail of the data files based on the provided search criteria, such as data product, dataset, version, countrycode, datafile id, geoid and statecode, etc.
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
| dataproduct | Query | String | the name of the data product the data files belong to |
| dataset | Query | String | the name of the dataset the data files belong to |
| version | Query | String | the version of the product |
| geoid | Query | Array of | the geoid the data file belongs to |
| countrycode | Query | String | the iso-3 code of the country the data files belong to |
| statecode | Query | String | the 2-letter code of the state or province the data files belong to if it is available |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datafiles?dataset=OpenLRDictionaryFiles&version=20.1&countrycode=AUT&accessToken={UAStoken}
Responses
200 Success
{
"result": [
{
"id": "46bccec6-e55d-4289-9d8e-d3f6fdeaa5dd",
"fileName": "AUT_GeoId-22_OLRDictionary.gz",
"countryCode": "AUT",
"geoId": "22",
"dataset": "OpenLRDictionaryFiles",
"version": "20.1",
"generatedTime": "2020-02-28T23:04:17",
"fileSizeInKB": 4512.415,
"dataProduct": "MapRelease"
},
{
"id": "638b079e-44eb-4040-a424-569c9537d6ef",
"fileName": "AUT_GeoId-24_OLRDictionary.gz",
"countryCode": "AUT",
"geoId": "24",
"dataset": "OpenLRDictionaryFiles",
"version": "20.1",
"generatedTime": "2020-02-28T23:04:21",
"fileSizeInKB": 2466.777,
"dataProduct": "MapRelease"
}
],
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datageographies/countries
GET query the available countries that are covered by any data file for the given product and version.
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
| version | Query | String | the version of the product |
| dataproduct | Query | String | the iso-3 code of the country the data files belong to |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datageographies/countries?version=20.1&dataproduct=MapRelease&accessToken={UAStoken}
Responses
200 Success
{
"result": [
{
"isoCode": "DNK",
"name": "Denmark",
"dataProduct": "MapRelease"
},
{
"isoCode": "NZL",
"name": "New Zealand",
"dataProduct": "MapRelease"
}
],
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}/v1/datageographies/geoids
GET query the available geoids that are covered by any data file for the given product and version.
Parameters
= required| Name | Located In | Type | Description |
|---|---|---|---|
| Bearer Token | Header | String | a valid UAS token from https://uas-api.inrix.com |
| accessToken | Query | String | a valid UAS token from https://uas-api.inrix.com |
| version | Query | String | the version of the product |
| dataproduct | Query | String | the iso-3 code of the country the data files belong to |
Requests
Example
Queryhttps://mapdata.inrix.io/v1/datageographies/geoids?version=20.1&dataproduct=MapRelease&accessToken={UAStoken}
Responses
200 Success
{
"result": [
{
"isoCode": "DNK",
"name": "Denmark",
"geoIds": [
{
"geoId": "57"
},
{
"geoId": "58"
}
],
"dataProduct": "MapRelease"
},
{
"isoCode": "NZL",
"name": "New Zealand",
"geoIds": [
{
"geoId": "1985"
},
{
"geoId": "1986"
}
],
"dataProduct": "MapRelease"
}
],
"copyright": "Copyright INRIX Inc.",
"createdDate": "2020-08-09T07:51:38.62Z",
"responseId": "42845c9d-5af2-4ae3-a5b8-171a87b50194"
}