Developers · Full API reference

Network Diagnostics API reference

Read your road network's condition programmatically: PCI and IRI scoring, condition distribution, deterioration forecasts, benchmark comparisons, geolocated defects, and GIS export. Every endpoint, parameter and response shape. New here? Start with the API overview.

BASE URL https://api.roadscoutai.com/v1AUTH: BEARER JWT · PER ORGANIZATIONJSON · READ-ONLY

Quick start

Authenticate and pull your network condition in three steps.

SEC. 01 / QUICK START

Get an access token

Every request needs a Bearer token issued by RoadScout Auth. Sign in with your RoadScout account credentials to obtain a JWT, then send it in the Authorization header.

Point at the base URL

All endpoints live under https://api.roadscoutai.com/v1. The API is versioned via the /v1 path prefix and is entirely read-only.

Pull your network summary

Call /analytics/summary for headline condition KPIs across your whole network: network PCI, average IRI, kilometres surveyed and defect totals.

TERMINALSTEP 03

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.roadscoutai.com/v1/analytics/summary"

Access model

All endpoints require a valid Bearer token.

SEC. 02 / AUTH

RoadScout uses JWT bearer tokens issued by RoadScout Auth. Authenticate with your RoadScout account to receive an ID token, then send it on every request in the Authorization header.

Requests without a valid token receive 401 Unauthorized.

Each token is scoped to your organization: you only ever see your own network's condition and defect data. API access ships with the Integration Plus module.

AUTHORIZATION HEADER

Authorization: Bearer eyJraWQiOiJ...

Code examples

Common patterns, in your language of choice.

SEC. 03 / EXAMPLES

Pavement Condition Index for an area

CURL

# Network and per-segment PCI
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.roadscoutai.com/v1/analytics/pci?bbox=-26.3,27.9,-26.1,28.1"

PYTHON

import requests

headers = {"Authorization": "Bearer YOUR_TOKEN"}
resp = requests.get(
    "https://api.roadscoutai.com/v1/analytics/pci",
    headers=headers,
    params={"bbox": "-26.3,27.9,-26.1,28.1"},
)
network_pci = resp.json()["networkPci"]

NODE.JS

const params = new URLSearchParams({
  bbox: "-26.3,27.9,-26.1,28.1",
});

const resp = await fetch(
  `https://api.roadscoutai.com/v1/analytics/pci?${params}`,
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
const { networkPci } = await resp.json();

Find high-severity potholes

CURL

# High-severity potholes in an area
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.roadscoutai.com/v1/events?type=POTHOLE&severity=HIGH&min_conf=0.7"

PYTHON

import requests

headers = {"Authorization": "Bearer YOUR_TOKEN"}
resp = requests.get(
    "https://api.roadscoutai.com/v1/events",
    headers=headers,
    params={
        "type": "POTHOLE",
        "severity": "HIGH",
        "min_conf": 0.7,
    },
)
potholes = resp.json()["items"]

NODE.JS

const params = new URLSearchParams({
  type: "POTHOLE",
  severity: "HIGH",
  min_conf: "0.7",
});

const resp = await fetch(
  `https://api.roadscoutai.com/v1/events?${params}`,
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
const { items } = await resp.json();

Reference

Four read-only resource groups.

Network analytics, segments, defects, and GIS export. All paths are relative to https://api.roadscoutai.com/v1; every endpoint is GET and returns JSON.

SEC. 04 / REFERENCE

Analytics

GROUP 01 / 04 · 6 ENDPOINTS

Network-level diagnostics: pavement condition (PCI), roughness (IRI), condition distribution, deterioration forecasts, and benchmark comparisons across your whole road network.

GET/analytics/summary

Network condition summary

Headline KPIs for the whole surveyed network: network PCI, average IRI, kilometres surveyed, segment count, defect totals, and a condition-distribution snapshot.

QUERY PARAMETERS
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
carriageway_type	string	Filter by carriageway configuration (see Enumerations).e.g. DUAL
from	string (date)	Start of date range (ISO 8601).
to	string (date)	End of date range (ISO 8601).

GET /analytics/summary200 OK · APPLICATION/JSON

{
  "networkPci": 63,
  "networkConditionRating": "FAIR",
  "averageIri": 3.8,
  "averageIriBand": "FAIR",
  "kmSurveyed": 412.6,
  "segmentCount": 1043,
  "defects": {
    "total": 2871,
    "potholes": 1188,
    "byType": { "POTHOLE": 1188, "CRACK": 942, "PATCH": 401, "CORRUGATION": 340 }
  },
  "highSeverity": 612,
  "conditionDistribution": {
    "GOOD": 0.08, "SATISFACTORY": 0.23, "FAIR": 0.42, "POOR": 0.21, "VERY_POOR": 0.06
  }
}

GET/analytics/pci

Pavement Condition Index (PCI)

Network and per-segment PCI on a 0-100 scale derived from AI-detected defect types, densities, and severities, banded per ASTM D6433 (see Condition scales).

QUERY PARAMETERS
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
carriageway_type	string	Filter by carriageway configuration (see Enumerations).e.g. DUAL
from	string (date)	Start of date range (ISO 8601).
to	string (date)	End of date range (ISO 8601).

GET /analytics/pci200 OK · APPLICATION/JSON

{
  "networkPci": 63,
  "networkConditionRating": "FAIR",
  "segments": [
    {
      "segmentId": "seg_00a1",
      "pci": 82,
      "conditionRating": "SATISFACTORY",
      "surfaceType": "ASPHALT_CONCRETE",
      "carriagewayType": "DUAL",
      "lengthKm": 0.4
    },
    {
      "segmentId": "seg_00a2",
      "pci": 47,
      "conditionRating": "POOR",
      "surfaceType": "GRAVEL",
      "carriagewayType": "SINGLE",
      "lengthKm": 0.6
    }
  ]
}

GET/analytics/iri

International Roughness Index (IRI)

Network and per-segment IRI in m/km, estimated from 25 Hz IMU accelerometer data and calibrated to World Bank / ARRB bands (see Condition scales). Estimate pending true quarter-car calibration.

QUERY PARAMETERS
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
carriageway_type	string	Filter by carriageway configuration (see Enumerations).e.g. DUAL
from	string (date)	Start of date range (ISO 8601).
to	string (date)	End of date range (ISO 8601).

GET /analytics/iri200 OK · APPLICATION/JSON

{
  "averageIri": 3.8,
  "averageIriBand": "FAIR",
  "segments": [
    {
      "segmentId": "seg_00a1",
      "iri": 2.1,
      "iriBand": "GOOD",
      "surfaceType": "ASPHALT_CONCRETE",
      "carriagewayType": "DUAL",
      "lengthKm": 0.4
    },
    {
      "segmentId": "seg_00a2",
      "iri": 5.4,
      "iriBand": "POOR",
      "surfaceType": "GRAVEL",
      "carriagewayType": "SINGLE",
      "lengthKm": 0.6
    }
  ]
}

GET/analytics/condition-distribution

Network condition distribution

Share of network length in each condition band, reported by PCI band (ASTM D6433), IRI band, and TMH visual condition (see Condition scales). Values are fractions of total surveyed length.

QUERY PARAMETERS
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
carriageway_type	string	Filter by carriageway configuration (see Enumerations).e.g. DUAL

GET /analytics/condition-distribution200 OK · APPLICATION/JSON

{
  "kmSurveyed": 412.6,
  "byPci": {
    "GOOD": 0.08, "SATISFACTORY": 0.23, "FAIR": 0.42, "POOR": 0.16,
    "VERY_POOR": 0.06, "SERIOUS": 0.04, "FAILED": 0.01
  },
  "byIri": {
    "EXCELLENT": 0.05, "GOOD": 0.26, "FAIR": 0.40, "POOR": 0.22, "VERY_POOR": 0.07
  },
  "byVisualCondition": {
    "VERY_GOOD": 0.06, "GOOD": 0.25, "FAIR": 0.40, "POOR": 0.22, "VERY_POOR": 0.07
  }
}

GET/analytics/deterioration-forecast

Deterioration forecast

Projected PCI and IRI over a future horizon, for capital planning and budget prioritisation. Forecasts are per-year and can be scoped by area or surface type.

QUERY PARAMETERS
horizon_years	integer	Number of years to project (default 5).e.g. 5
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1

GET /analytics/deterioration-forecast200 OK · APPLICATION/JSON

{
  "horizonYears": 5,
  "baseYear": 2026,
  "projection": [
    { "year": 2026, "networkPci": 63, "averageIri": 3.8 },
    { "year": 2027, "networkPci": 59, "averageIri": 4.1 },
    { "year": 2028, "networkPci": 55, "averageIri": 4.5 },
    { "year": 2029, "networkPci": 51, "averageIri": 4.9 },
    { "year": 2030, "networkPci": 47, "averageIri": 5.3 }
  ]
}

GET/analytics/benchmark

Benchmark comparison

Compares your network against reference benchmarks (e.g. World Bank / ARRB IRI bands and peer networks), returning percentile rank and the gap to each reference.

QUERY PARAMETERS
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE

GET /analytics/benchmark200 OK · APPLICATION/JSON

{
  "networkPci": 63,
  "averageIri": 3.8,
  "benchmarks": [
    {
      "name": "Peer networks (regional)",
      "metric": "PCI",
      "value": 71,
      "delta": -8,
      "percentile": 38
    },
    {
      "name": "World Bank good-practice",
      "metric": "IRI",
      "value": 2.7,
      "delta": 1.1,
      "percentile": 41
    }
  ]
}

Segments

GROUP 02 / 04 · 2 ENDPOINTS

The road network is split into addressable segments: the unit of network analysis. Each segment carries a PCI condition rating, TMH visual condition, IRI, surface and carriageway type, distress tags, and geometry.

GET/segments

List network segments

Returns a paginated list of road segments with their condition scores and classification.

QUERY PARAMETERS
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
carriageway_type	string	Filter by carriageway configuration (see Enumerations).e.g. DUAL
condition	string	Filter by PCI condition rating (see Enumerations).e.g. POOR
min_pci	integer	Minimum PCI (0-100).e.g. 0
max_pci	integer	Maximum PCI (0-100).e.g. 55
page	integer	Page number (1-based).e.g. 1
limit	integer	Results per page (max 100).e.g. 50

GET /segments200 OK · APPLICATION/JSON

{
  "items": [
    {
      "segmentId": "seg_00a2",
      "surfaceType": "GRAVEL",
      "carriagewayType": "SINGLE",
      "pci": 47,
      "conditionRating": "POOR",
      "visualCondition": "POOR",
      "distressTags": ["POTHOLES", "CORRUGATION"],
      "iri": 5.4,
      "iriBand": "POOR",
      "lengthKm": 0.6,
      "centroid": { "lat": -26.2041, "lon": 28.0473 }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1043, "totalPages": 21 }
}

GET/segments/{segmentId}

Get segment detail

Returns full detail for a segment: condition scores, defect counts by type, geometry (polyline), and score trend over time.

PATH PARAMETERS
segmentIdrequired	string	The segment identifier.

GET /segments/{segmentId}200 OK · APPLICATION/JSON

{
  "segmentId": "seg_00a2",
  "surfaceType": "GRAVEL",
  "carriagewayType": "SINGLE",
  "pci": 47,
  "conditionRating": "POOR",
  "visualCondition": "POOR",
  "distressTags": ["POTHOLES", "CORRUGATION"],
  "iri": 5.4,
  "iriBand": "POOR",
  "lengthKm": 0.6,
  "defectCounts": { "POTHOLE": 14, "CORRUGATION": 6, "OTHER": 2 },
  "geometry": {
    "type": "LineString",
    "coordinates": [[28.0470, -26.2044], [28.0481, -26.2038]]
  },
  "trend": [
    { "surveyedOn": "2026-01-12", "pci": 54, "iri": 4.8 },
    { "surveyedOn": "2026-03-31", "pci": 47, "iri": 5.4 }
  ]
}

Defects

GROUP 03 / 04 · 3 ENDPOINTS

Individual road defect events: potholes, cracks, patches, corrugation and more, each geolocated with a type, severity, and confidence. Includes counts, density, and hotspots.

GET/events

List defects

Returns a paginated, filterable list of geolocated road defect events.

QUERY PARAMETERS
type	string	Filter by defect type (see Enumerations).e.g. POTHOLE
severity	string	LOW \| MEDIUM \| HIGHe.g. HIGH
min_conf	number	Minimum confidence (0.0-1.0).e.g. 0.7
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
from	string (date)	Start of date range (ISO 8601).
to	string (date)	End of date range (ISO 8601).
status	string	UNREVIEWED \| ACCEPTED \| DECLINEDe.g. ACCEPTED
page	integer	Page number (1-based).e.g. 1
limit	integer	Results per page (max 100).e.g. 50

GET /events200 OK · APPLICATION/JSON

{
  "items": [
    {
      "eventId": "e1a2b3c4",
      "type": "POTHOLE",
      "severity": "HIGH",
      "confidence": 0.92,
      "lat": -26.2041,
      "lon": 28.0473,
      "surfaceType": "ASPHALT_CONCRETE",
      "status": "ACCEPTED",
      "firstSeenTimeUtc": "2026-03-31T11:02:10Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1188, "totalPages": 24 }
}

GET/events/{eventId}

Get defect detail

Returns full detail for a single defect, including evidence frames and location.

PATH PARAMETERS
eventIdrequired	string	The defect / event identifier.

GET /events/{eventId}200 OK · APPLICATION/JSON

{
  "eventId": "e1a2b3c4",
  "type": "POTHOLE",
  "severity": "HIGH",
  "confidence": 0.92,
  "lat": -26.2041,
  "lon": 28.0473,
  "surfaceType": "ASPHALT_CONCRETE",
  "status": "ACCEPTED",
  "firstSeenTimeUtc": "2026-03-31T11:02:10Z",
  "lastSeenTimeUtc": "2026-03-31T11:02:14Z",
  "evidenceFrames": [
    {
      "frameId": "aa11bb22",
      "confidence": 0.92,
      "imageUrl": "https://roadscout-frames.s3.af-south-1.amazonaws.com/..."
    }
  ]
}

GET/events/summary

Defect counts, density and hotspots

Aggregated defect diagnostics: totals by type and severity, pothole density per km, and the worst hotspots in the filtered area.

QUERY PARAMETERS
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
from	string (date)	Start of date range (ISO 8601).
to	string (date)	End of date range (ISO 8601).

GET /events/summary200 OK · APPLICATION/JSON

{
  "total": 2871,
  "byType": { "POTHOLE": 1188, "CRACK": 942, "PATCH": 401, "CORRUGATION": 340 },
  "bySeverity": { "LOW": 1102, "MEDIUM": 1157, "HIGH": 612 },
  "potholeDensityPerKm": 2.88,
  "hotspots": [
    { "lat": -26.2041, "lon": 28.0473, "potholes": 23, "surfaceType": "GRAVEL" },
    { "lat": -26.1925, "lon": 28.0512, "potholes": 17, "surfaceType": "ASPHALT_CONCRETE" }
  ]
}

Export

GROUP 04 / 04 · 2 ENDPOINTS

Download network condition and defect data in GIS-ready formats for ArcGIS, QGIS, and other platforms. Returns a short-lived download URL.

GET/export/events

Export defects (GeoJSON / KML / Shapefile / CSV)

Exports filtered defect events to a GIS format. Filters mirror GET /events. Returns a presigned download URL.

QUERY PARAMETERS
formatrequired	string	geojson \| kml \| shapefile \| csve.g. kml
type	string	Filter by defect type (see Enumerations).e.g. POTHOLE
severity	string	LOW \| MEDIUM \| HIGHe.g. HIGH
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
from	string (date)	Start of date range (ISO 8601).
to	string (date)	End of date range (ISO 8601).

GET /export/events200 OK · APPLICATION/JSON

{
  "format": "kml",
  "downloadUrl": "https://roadscout-exports.s3.af-south-1.amazonaws.com/exports/events-2026-05-20.kml?X-Amz-...",
  "featureCount": 1188,
  "expiresIn": 3600
}

GET/export/segments

Export segment condition (GeoJSON / KML / Shapefile / CSV)

Exports per-segment PCI / IRI / condition rating to a GIS format for pavement-management systems. Returns a presigned download URL.

QUERY PARAMETERS
formatrequired	string	geojson \| kml \| shapefile \| csve.g. geojson
bbox	string	Bounding box filter: sw_lat,sw_lon,ne_lat,ne_lone.g. -26.3,27.9,-26.1,28.1
surface_type	string	Filter by surface type (see Enumerations).e.g. ASPHALT_CONCRETE
carriageway_type	string	Filter by carriageway configuration (see Enumerations).e.g. DUAL
condition	string	Filter by PCI condition rating (see Enumerations).e.g. POOR

GET /export/segments200 OK · APPLICATION/JSON

{
  "format": "geojson",
  "downloadUrl": "https://roadscout-exports.s3.af-south-1.amazonaws.com/exports/segments-2026-05-20.geojson?X-Amz-...",
  "featureCount": 1043,
  "expiresIn": 3600
}

No capture or ingestion endpoints are exposed publicly. Trips, work orders and virtual inspections are surfaced in the dashboard; see the API overview for the full surface map and webhooks.

Condition scales

Three published standards, one API.

Every score the API returns is banded to a published scale: PCI to ASTM D6433, roughness to World Bank / ARRB IRI thresholds, and visual condition to the TMH 5-point scale used across SA / SADC networks.

SEC. 05 / SCALES

PCI · ASTM D6433

7 BANDS · 0-100 · PER ~100 M SEGMENT

GOOD	86-100
SATISFACTORY	71-85
FAIR	56-70
POOR	41-55
VERY_POOR	26-40
SERIOUS	11-25
FAILED	0-10

Derived from AI-detected defect types, densities and severities with a severity-weighted deduct model.

IRI · World Bank / ARRB

5 BANDS · M/KM

EXCELLENT	< 1.5 m/km
GOOD	1.5-2.7 m/km
FAIR	2.7-4.2 m/km
POOR	4.2-6.0 m/km
VERY_POOR	> 6.0 m/km

Estimated from 25 Hz IMU accelerometer telemetry and calibrated to World Bank / ARRB bands. An estimate, not a quarter-car measurement. Good-practice benchmark: IRI 2.7.

Visual condition · TMH

5-POINT SCALE · SA / SADC

VERY_GOOD	Very Good
GOOD	Good
FAIR	Fair
POOR	Poor
VERY_POOR	Very Poor

The 5-point visual assessment scale used by TMH manuals across South African and SADC road networks, reported per segment alongside PCI and IRI.

Enumerations

The fixed value sets used in filters and responses.

SEC. 06 / ENUMS

Surface types

surfaceType

ASPHALT_CONCRETEAsphalt Concrete (flexible)
ASPHALT_OVERLAYAsphalt Overlay
SURFACE_TREATMENTSurface Treatment / Chip Seal
CONCRETEConcrete (rigid / PCC)
BLOCK_PAVINGBlock / Segmental Paving
COBBLESTONECobblestone
GRAVELGravel (unpaved)
EARTHEarth / Unimproved
PAVED_GRAVEL_MIXEDMixed Paved & Gravel

Carriageway types

carriagewayType

SINGLESingle Carriageway
SINGLE_NARROWSingle Carriageway (Narrow)
SINGLE_WIDESingle Carriageway (Wide)
DUALDual Carriageway

Condition rating (PCI · ASTM D6433)

conditionRating

GOODGood (PCI 86-100)
SATISFACTORYSatisfactory (71-85)
FAIRFair (56-70)
POORPoor (41-55)
VERY_POORVery Poor (26-40)
SERIOUSSerious (11-25)
FAILEDFailed (0-10)

Visual condition (TMH)

visualCondition

VERY_GOODVery Good
GOODGood
FAIRFair
POORPoor
VERY_POORVery Poor

Distress tags

distressTags

POTHOLESPotholes
RUTTINGRutting
CRACKINGCracking
RAVELLINGRavelling
EDGE_BREAKEdge break
CORRUGATIONCorrugation (washboarding)
SEASONAL_RAINYDeteriorates in rainy season

Defect types

type

POTHOLEPothole
CRACKCracking (alligator, transverse, longitudinal)
PATCHPatch / repair
CORRUGATIONCorrugation (washboarding, from IMU)
INCLINATIONSteep grade (from GPS altitude)
MISSING_LANE_LINESMissing lane markings
OTHEROther defect

Severity

severity

LOWLow
MEDIUMMedium
HIGHHigh

IRI bands

iriBand

EXCELLENT< 1.5 m/km
GOOD1.5-2.7 m/km
FAIR2.7-4.2 m/km
POOR4.2-6.0 m/km
VERY_POOR> 6.0 m/km

Errors & versioning

Predictable, machine-readable failures.

SEC. 07 / ERRORS

STATUS CODES

400	Validation errorA query parameter is missing or malformed.
401	UnauthorizedMissing or invalid Bearer token.
404	Not foundThe requested segment or defect does not exist.
500	Server errorAn unexpected error occurred. Safe to retry.
502	Upstream errorA downstream dependency failed. Retry with backoff.

The API is versioned through the URL path. The current version is /v1; breaking changes ship under a new prefix.

Errors return an application/problem+json body (RFC 7807) with a machine-readable errorCode and a retryable flag.

400 BAD REQUESTAPPLICATION/PROBLEM+JSON

{
  "type": "https://api.roadscoutai.com/errors/VALIDATION_INVALID_PARAMETER",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid value for parameter 'bbox'",
  "errorCode": "VALIDATION_INVALID_PARAMETER",
  "category": "VALIDATION_ERROR",
  "retryable": false,
  "timestamp": "2026-05-20T10:00:00Z"
}

Ready to build?

Get organization API keys with the Integration Plus module, or talk to us about wiring RoadScout into your PMS, GIS or data warehouse.

Request a demo See pricing