ROADAHEAD API
RoadAhead's platform helps navigate roads safely by providing roadwork and obstacle intelligence in real-time. Autonomous vehicles and mapping applications are just few use cases that can use RoadAhead API.
RoadAhead API provides all roadwork locations within USA and their permit data through a single GET request. You can filter and sort roadworks data for ex. by city, country, navigation safety score and more parameters.
API ENDPOINT
AUTHORIZATION
RoadAhead API requires Authorization: Bearer your_bearer_token header with each request. You can find your bearer token on API page in your dashboard.
GET /roadworks
Sending GET request with Authorization: Bearer your_bearer_token header to https://api.roadahead.ai/v1/roadworks would return a response with paginated list of all roadworks available in RoadAhead's API. Each page has 25 results by default.
Example curl request
curl 'https://api.roadahead.ai/v1/roadworks' \
--header 'Authorization: Bearer your_token'
Example Javascript (browser) request
function fetchRoadworksData(token) {
const apiUrl = 'https://api.roadahead.ai/v1/roadworks';
return fetch(apiUrl, {
headers: {
Authorization: `Bearer ${token}`
}
})
.then(response => {
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.json();
})
.then(data => {
console.log('Data:', data);
return data;
})
.catch(error => {
console.error('Error:', error);
throw error;
});
}
// Replace 'your_token' with your actual API token
// API token is available at https://dash.roadahead.ai/api
const authToken = 'your_token';
fetchRoadworksData(authToken)
.then(() => {
console.log('Data fetched successfully.');
})
.catch(() => {
console.error('Failed to fetch data.');
});
Example response
{
"data": [
{
"id": 1,
"attributes": {
"roadworkPermitId": "23EXC-03889",
"createdAt": "2023-08-24T02:08:54.914Z",
"updatedAt": "2023-08-24T02:08:54.914Z",
"address": "multiple",
"zipCode": "multiple",
"state": "CA",
"city": "San Francisco",
"startDateTime": "2023-09-04T07:00:00.000Z",
"endDateTime": "2023-11-02T07:00:00.000Z",
"roadworkDescription": "Pacific Gas & Electric is granted this permit.",
"navSafetyScore": 5,
"roadworkType": "Excavation",
"roadworkSpace": 0.1,
"startLongitude": -122.4382899,
"endLongitude": -122.4381389,
"startLatitude": 37.7606978,
"endLatitude": 37.7590985,
"fromStreet": "18th St",
"toStreet": "19th St",
"crossStreet": "Eureka St",
"permitUrl": "https://bsmnt.sfdpw.org/pics/23EXC-03889/23EXC-03889_08-18-2023.pdf"
}
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1000
}
}
}
DATA GUIDE (roadworks)
| Key | Description |
|---|---|
roadworkPermitId
|
Unique id of approved roadwork permit from city or county. Roadahead API uses it to identify all roadworks. |
roadworkDescription
|
A short description of nature of roadwork. |
navSafetyScore
|
Navigation safety score assigned by RoadAhead using distance, duration and traffic conditions around the roadwork. If navSafetyScore is greater than 6, it means that roadwork area is safe to navigate, and below 6 is unsafe. |
roadworkType
|
Type of roadwork assigned by city or county. Ex. types are Excavation, StorCont (storage container) and more. RoadAhead will publish list of roadwork types soon. |
roadworkSpace
|
Distance in miles that's occupied by the roadwork in affected area. |
startLongitude
|
Starting longitude of the roadwork. A roadwork always has a start to end longitude and latitude. |
endLongitude
|
Ending longitude of the roadwork. |
startLatitude
|
Starting latitude of the roadwork. |
endLatitude
|
Ending latitude of the roadwork. |
fromStreet
|
Starting street of the area affected by the roadwork. fromStreet can be used with crossStreet to get address details from any geocoding API for ex. Google's geocoding API. |
toStreet
|
Ending street of the area affected by the roadwork. toStreet can be used with crossStreet to get details from any geocoding API for ex. Google's geocoding API. |
crossStreet
|
Cross street of the area affected by the roadwork. Cross street connects toStreet and fromStreet. crossStreet can be used with fromStreet and endStreet to get details from any geocoding API for ex. Google's geocoding API. |
startDateTime
|
Starting date and time of roadwork. |
endDateTime
|
Ending date and time of roadwork. |
FILTERS
API call for https://api.roadahead.ai/v1/roadworks can accept a ?filters[key][$operator]=value parameter. The following operators are available:
| Operator | Description |
|---|---|
$eq | Equal |
$eqi | Equal (case-insensitive) |
$ne | Not equal |
$nei | Not equal (case-insensitive) |
$lt | Less than |
$lte | Less than or equal to |
$gt | Greater than |
$gte | Greater than or equal to |
$in | Included in an array |
$notIn | Not included in an array |
$contains | Contains |
$notContains | Does not contain |
$containsi | Contains (case-insensitive) |
$notContainsi | Does not contain (case-insensitive) |
$null | Is null |
$notNull | Is not null |
$between | Is between |
$startsWith | Starts with |
$startsWithi | Starts with (case-insensitive) |
$endsWith | Ends with |
$endsWithi | Ends with (case-insensitive) |
$or | Joins the filters in an "or" expression |
$and | Joins the filters in an "and" expression |
$not | Joins the filters in an "not" expression |
| Example Calls | Description |
|---|---|
|
|
Queries roadworks that are in future or equals to provided date/time. It can be used with any date/time, score or a number field in roadworks object for ex. startDateTime, navigationSafetyScore endDateTime, createdAt, updatedAt. |
|
|
Queries roadworks that are in past or equals to provided date/time. It can be used with any date/time, score or a number field in roadworks object for ex. startDateTime, navigationSafetyScore endDateTime, createdAt, updatedAt. |
|
|
Queries roadworks that are equals to provided date/time. It can be used with any date/time, score or a number field in roadworks object for ex. startDateTime, navigationSafetyScore endDateTime, createdAt, updatedAt. |
SORTING & PAGINATION
| Example Calls | Description |
|---|---|
| This would return sorted results by the specified field. You can either sort asc (ascending) or desc (descending). It can be used with any date/time, score or a number field in roadworks object for ex. startDateTime, navigationSafetyScore endDateTime, createdAt, updatedAt. | |
https://api.roadahead.ai/v1?sort[0]=start_datetime:asc&sort[1]=navSafetyScore:desc
|
You can also sort on multiple values using this format. It can be used with any date/time, score or a number field in roadworks object for ex. startDateTime, navigationSafetyScore endDateTime, createdAt, updatedAt. |
https://api.roadahead.ai/v1?pagination[page]=1&pagination[pageSize]=10
|
Returns only 10 entries on page 1. |
https://api.roadahead.ai/v1?pagination[start]=0&pagination[limit]=10
|
Return only the first 10 entries using offset. |
Pagination by offset
To paginate results by page, use the following parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
pagination[start] | Integer | Start value (i.e. first entry to return) | 0 |
pagination[limit] | Integer | Number of entries to return | 25 |
pagination[withCount] | Boolean | Toggles displaying the total number of entries to the response | true |
Pagination by page
To paginate results by offset, use the following parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
pagination[page] | Integer | Page number | 1 |
pagination[pageSize] | Integer | Page size | 25 |
pagination[withCount] | Boolean | Adds the total numbers of entries and the number of pages to the response | True |