NAV Navbar
javascript

Overview

Welcome to the ClearRoad API documentation!

ClearRoad is a SaaS platform that enables to quickly build a road pricing solution.

ClearRoad API is a synchronisation protocol that ensures 100% accuracy, auditability, transparency on the data and the financial transactions managed by the platform. ClearRoad work as a central ledger from which other systems can feed into or pull data from.

The API is based on the synchronization of messages. The document below describes the different messages and the data that compose them. ClearRoad Platform will process each message and provide a status on each of the message in the platform. If the platform approves the messages, then it will create or update the necessary documents (or objects) in the system. This documentation provides the details of the different documents (or objects) that can be created.

You will find here samples to send and receive data on the API, and will be able to test them with a basic account or your own account.

Using the Playground

You can use the ClearRoad API in the following cases:

Please refer to the API Reference for more information on how to use the JavaScript SDK.

Tutorial

Account Manager: before starting the tutorial, you can either follow the Data Provider tutorial to send road usage data or send an email to ClearRoad so that we can create transactions for you.

Account Manager

Registering a road account

To create road account registration for a specific vehicle:

cr.post({
  "account_manager": "testamref",
  "data_collector": "testmpref",
  "condition": "test-stc-1",
  "cert_id": "1051",
  "account_reference": "USER000011",
  "effective_date": "2018-04-01T00:00:00Z",
  "expiration_date": "2018-04-01T00:00:00Z",
  "fuel_consumption": "12.0",
  "fuel_taxable": "1",
  "obu_reference": "977298026d50a5b1795c6563",
  "vehicle_reference": "2C1MR2295T6789740",
  "product_line": "ruc_metrics",
  "portal_type": "Road Account Message"
});

You can get the status of your request of road account registration by listing them:

cr.allDocs({
  query: 'portal_type: "Road Account Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'grouping_reference'
  ]
});

This method allows to create a road account registration for a vehicle associate with a specific road account. If the road account does not exist, the system will create a new road account as well.

ClearRoad will only accept and process road usage data for a specific vehicle if the vehicle has already an active road account registration.

cr.post({account_manager, data_collector, condition, cert_id, account_reference, effective_date, expiration_date, fuel_consumption, fuel_taxable, obu_reference, vehicle_reference, product_line, portal_type});

Parameters

Property Description Required Default
account_manager The reference of an account manager that already exists in ClearRoad Platform. No
data_collector The reference should be of a data provider that already exists in ClearRoad Platform. Yes
condition Sale Trade Condition to apply. The reference should be of an object that already exists in ClearRoad Platform. Yes
cert_id The DOT certificate ID value Yes
account_reference The reference of the road account to be defined. Yes
effective_date The start date of the customer account. Could not be left empty. Should be in UTC. Yes
expiration_date The stop date of the customer account. Could be left empty - the road account will have no expiration date. Should be in UTC. No
fuel_consumption Combined EPA Miles Per Gallon (MPG) rating for the vehicle. Yes
fuel_taxable Boolean defining if customer is subject to taxable fuel. Yes
obu_reference An object for this on board unit will be created in the ClearRoad platform if it is nor already present. No
vehicle_reference An onject for this vehicle will be created in the ClearRoad Platform if it is not already present. Yes
product_line The reporting method the customer choosed to use.
Values:
odometer_message_no_transaction
odometer_message_transaction
ruc_metrics
service
Yes
portal_type The type of the message in the ClearRoad Platform. Only one value is possible. Yes Road Account Message

Try it out

Listing road accounts

You can list the road accounts along their messages:

cr.allDocs({
  query: 'portal_type: "Road Account"',
  select_list: [
    'reference',
    'registrations'
  ]
}).push(result => {
  result.data.rows.forEach(row => {
    // reference is used as "destination_reference" when registering a road account
    const reference = row.value.reference;
    // contains the documents associated with the account
    const registrations = row.value.registrations;
  });
});

List the road accounts you have access to.

cr.allDocs({query, select_list})

Parameters

Property Value
query 'portal_type: "Road Account"'
select_list Any of
'reference': road account reference
'registrations': all documents linked to the road account

Try it out

Registering a billing period

Adding a billing period can be done using the following post method:

cr.post({
  "reference": "2018Q1",
  "start_date": "2018-04-01T00:00:00Z",
  "stop_date": "2018-04-01T00:00:00Z",
  "portal_type": "Billing Period Message"
});

You can get the status of your request of billing period message by listing them:

cr.allDocs({
  query: 'portal_type: "Billing Period Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'destination_reference',
    'grouping_reference'
  ]
});

For applications that only need the aggregate charges over a long period of time, it is easier to set up billing periods. ClearRoad will aggregate for you the related transactions in reports.

To learn more about reports, see the report section.

cr.post({reference, start_date, stop_date, portal_type});

Parameters

Property Description Required Default
reference The reference given to the new billing period which will be used to reference it in the future. Yes
start_date The date, starting which, the billing period is going to be active. Should be in UTC. Yes
stop_date The date, starting which, the billing period will become inactive. Should be UTC. If it is left empty, the billing period will never turn inactive, once activated. Yes
portal_type The type of message in the ClearRoad Platform. Only one value is possible Yes Billing Period Message

Try it out

Listing road events

You can list the road events using:

cr.allDocs({
  query: 'portal_type: "Road Event"',
  select_list: [
    'source_reference',
    'vehicle_reference',
    'obu_reference',
    'event_date',
    'report_date',
    'type',
    'state'
  ]
});

List processed road messages.

cr.allDocs({query, select_list})

Parameters

Property Value
query 'portal_type: "Road Event"'
select_list Any of
'source_reference': the reference of the source road message
'vehicle_reference': the VIN of the vehicle
'obu_reference': the OBU of the vehicle
'event_date': date associated with the road message
'report_date': the date the message was sent
'type': the event type
'state': state of the road message (acknowledged if the message was processed)

Try it out

Listing road transactions

You can list the road transactions using:

cr.allDocs({
  query: 'portal_type: "Road Transaction"',
  select_list: [
    'vehicle_reference',
    'obu_reference',
    'transaction_date',
    'report_date',
    'state',
    'transaction_type',
    'rule',
    'fuel_quantity',
    'miles_quantity'
  ]
});

List road transactions.

cr.allDocs({query, select_list})

Parameters

Property Value
query 'portal_type: "Road Transaction"'
select_list Any of
'vehicle_reference': the VIN of the vehicle
'obu_reference': the OBU of the vehicle
'transaction_date': the date that the miles being reported were traveled on
'report_date': the date when the transaction was reported
'transaction_type': a value to indicate the type of message from the MRD
'rule': see rules
'fuel_quantity': amount of fuel consumed at the transaction date (gallon)
'miles_quantity': miles traveled at the transaction date
'state': state of the transaction (acknowledged if it was processed)

Try it out

Requesting a report

Step 1: request a report:

cr.post({
  "report_type": "AccountBalance",
  "billing_period_reference": "2018Q1",
  "request_date": "2017-07-18T00:00:00Z",
  "request": "",
  "portal_type": "Road Report Request"
}).push(reference => {
  // use this reference in step 2
});

Step 1.1: if you need to find the reference of your request, use:

cr.allDocs({
  query: 'grouping_reference: "data" AND portal_type: "Road Report Request" AND billing_period_reference: "<reference>"',
  select_list: [
    'source_reference',
    'request_date'
  ]
}).push(result => {
  // look for the result matching your request from step 1
  result.data.rows.forEach(row => {
    // use this reference in step 2
    const reference = row.value.source_reference;
  });
});

Step 2: check the status of the request:

cr.allDocs({
  query: 'grouping_reference: "report" AND portal_type: "Road Report Request" AND source_reference: "<reference from step 1>"',
  select_list: [
    'state',
    'comment'
  ]
}).push(result => {
  const document = result.data.rows[0].value;
  if (document.state === 'processed') {
    // report is ready, go to step 3
  }
  else {
    // check again later (processing time depends on collected data)
  }
});

Step 3: get the result of the report using the source_reference obtained at step 1 (or find it with step 1.1):

cr.getReportFromRequest('reference').push(report => {
  // display the report
  console.log(JSON.Stringify(report));
});

You can request a report that will be processed in the background and will be available later on. This is done in 3 steps as per the code sample.

cr.post({report_type, billing_period_reference, request_date, request, portal_type});

Parameters

Property Description Required Default
report_type The type of the requested report.
Values:
AccountBalance
Yes
billing_period_reference The reference of the billing period. The billing period should already exist in the ClearRoad Platform. Yes
request_date The datetime for which the request is made. Should be in UTC. Yes
request Used to give specific parameters to report if needed. This filed could be left empty for an AccountBalance report. No
portal_type The type of the object in the ClearRoad Platform. Only one possible value. Yes Road Report Request

Try it out

Data Provider

Sending road usage data

Sending road usage data can be done using the following post method:

cr.post({
  "request": {
    "description": "Mileage data",
    "vehicle_reference": "1GTG6BE38F1262119",
    "obu_reference": "977298026d50a5b1795c6563",
    "type": "MRP",
    "transaction_date": "2018-04-01T00:00:00Z",
    "mileage_details": {
      "fuel_price": "-0.30000001192092896",
      "fuel_quantity": "0.14000000059604645",
      "miles_price": "0.014999999664723873",
      "miles_quantity": "3.700000047683716",
      "rule_id": "41",
      "sub_rule_id": "1"
    }
  },
  "portal_type": "Road Message"
});

You can get the status of your request of road messages by listing them:

cr.allDocs({
  query: 'portal_type: "Road Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'destination_reference',
    'grouping_reference'
  ]
});

You can send the usage of mileage of a user using Road Message.

cr.post({request, portal_type});

Parameters

Property Description Required Default
request.description The description of the reported mileage Yes
request.vehicle_reference The Vehicle Identification Number of the vehicle for which the message is reported. Yes
request.obu_reference The On Board Unit reference of the device for which the message is reported Yes
request.type A value to indicate the type of message.
Values:
ADJ
CRE
FEE
INV
MRP
Yes
request.transaction_date The date at which mileage was traveled. Should be in UTC. Yes
request.mileage_details[].fuel_price The price of the fuel consumed at the transaction date. No 0
request.mileage_details[].fuel_quantity The quantity of fuel consumed at the transaction date. Yes 0
request.mileage_details[].miles_price The price of miles traveled. No 0
request.mileage_details[].miles_quantity The number of miles traveled. Yes 0
request.mileage_details[].rule_id An identifier associated with a geographic area, or zone, in which a specific rate per mile will be assessed for miles traveled. FIPS codes are used to identify states. Yes 0
request.mileage_details[].sub_rule_id 0 if the travel was on public roads, 1 if it was on private roads Yes 0
portal_type The type of message in the ClearRoad Platform. Only one type possible Yes Road Message

Try it out

Reporting a road event

Reporting events can be done using the following post method:

cr.post({
  "request": {
    "vehicle_reference": "1GTG6BE38F1262119",
    "obu_reference": "977298026d50a5b1795c6563",
    "event_details": {
      "type": "12",
      "date": "2018-04-01T00:00:00Z"
    }
  },
  "portal_type": "Road Event Message"
});

You can get the status of your request of road event messages by listing them:

cr.allDocs({
  query: 'portal_type: "Road Event Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'destination_reference',
    'grouping_reference'
  ]
});

Events like connection of device, or management event like missing mileage can be reported through the usage of Road Event Message.

cr.post({request, portal_type});

Parameters

Property Description Required Default
request.vehicle_reference The Vehicle Identification Number of the road account registration for which the event is reported Yes
request.obu_reference The On Board Unit reference of the road account registration for which the event is reported Yes
request.event_details[].type The ID of the event. Every type has it own ID. Yes
request.event_details[].date The datetime of the event. Should be a UTC time. Yes
portal_type The type of the object in ClearRoad Platform. Only one value is possible. Yes Road Event Message

Try it out

Listing road events

You can list the road events using:

cr.allDocs({
  query: 'portal_type: "Road Event"',
  select_list: [
    'source_reference',
    'vehicle_reference',
    'obu_reference',
    'event_date',
    'report_date',
    'type',
    'state'
  ]
});

List processed road messages.

cr.allDocs({query, select_list})

Parameters

Property Value
query 'portal_type: "Road Event"'
select_list Any of
'source_reference': the reference of the source road message
'vehicle_reference': the VIN of the vehicle
'obu_reference': the OBU of the vehicle
'event_date': date associated with the road message
'report_date': the date the message was sent
'type': the event type
'state': state of the road message (acknowledged if the message was processed)

Try it out

Please refer to the Account Manager's Listing road events section.

Listing road transactions

You can list the road transactions using:

cr.allDocs({
  query: 'portal_type: "Road Transaction"',
  select_list: [
    'vehicle_reference',
    'obu_reference',
    'transaction_date',
    'report_date',
    'state',
    'transaction_type',
    'rule',
    'fuel_quantity',
    'miles_quantity'
  ]
});

List road transactions.

cr.allDocs({query, select_list})

Parameters

Property Value
query 'portal_type: "Road Transaction"'
select_list Any of
'vehicle_reference': the VIN of the vehicle
'obu_reference': the OBU of the vehicle
'transaction_date': the date that the miles being reported were traveled on
'report_date': the date when the transaction was reported
'transaction_type': a value to indicate the type of message from the MRD
'rule': see rules
'fuel_quantity': amount of fuel consumed at the transaction date (gallon)
'miles_quantity': miles traveled at the transaction date
'state': state of the transaction (acknowledged if it was processed)

Try it out

Please refer to the Account Manager's Listing road transactions section.

Miscellaneous

MRD types

Code Description
ADJ Adjusted mileage transaction
CRE Credit transaction
FEE Fees transaction
INV Invoicing transaction
MRP Reported mileage transaction

Event types

Common MRD Health code for OBD-II devices:

Code Type
EVENT_AM_100 AM Event for No mileage received from VIN for given date
EVENT_AM_101 AM Event for Unreadable message from MRD / Checksum failure
EVENT_AM_102 AM Event for MessageIDs from MRD not correctly incrementing
EVENT_AM_103 AM Event for VIN - MRD ID mismatch
EVENT_AM_104 AM Event for Date/time not increasing from last message
EVENT_AM_105 AM Event for Accumulated mileage decreased from last message
EVENT_AM_106 AM Event for New total mileage does not equal sum of mileage in zones
EVENT_AM_107 AM Event for InvalidRule ID
EVENT_AM_108 AM Event for Unreasonable miles per day
EVENT_MRD_1 MRD Event for Low Voltage
EVENT_MRD_10 MRD Event for Software updates
EVENT_MRD_11 MRD Event for Degraded mileage data
EVENT_MRD_12 MRD Event for Missed mileage
EVENT_MRD_13 MRD Event for Vendor-specific
EVENT_MRD_2 MRD Event for Compromising Anomaly
EVENT_MRD_3 MRD Event for Storage full
EVENT_MRD_4 MRD Event for Disconnects / reconnects
EVENT_MRD_5 MRD Event for Connected to new vehicle
EVENT_MRD_6 MRD Event for Vehicle interface communications failure
EVENT_MRD_7 MRD Event for Location data degraded
EVENT_MRD_8 MRD Event for Incorrect date/time
EVENT_MRD_9 MRD Event for Software resets

Mileage Rule ids

Code Description
0 UNDIFFERENTIATED
1 ALABAMA
2 ALASKA
4 ARIZONA
5 ARKANSAS
6 CALIFORNIA
8 COLORADO
9 CONNECTICUT
10 DELAWARE
11 DISTRICT OF COLUMBIA
12 FLORIDA
13 GEORGIA
15 HAWAII
16 IDAHO
17 ILLINOIS
18 INDIANA
19 IOWA
20 KANSAS
21 KENTUCKY
22 LOUISIANA
23 MAINE
24 MARYLAND
25 MASSACHUSETTS
26 MICHIGAN
27 MINNESOTA
28 MISSISSIPPI
29 MISSOURI
30 MONTANA
300 CANADA
301 Mexico
302 International Miles
303 Canada - Alberta
304 Canada - British Columbia
305 Canada - New Brunswick
306 Canada - Newfoundland and Labrador
307 Canada - Nova Scotia
308 Canada - Manitoba
309 Canada - Ontario
31 NEBRASKA
310 Canada - Quebec
311 Canada - Prince Edward Island
312 Canada - Saskatchewan
313 Canada - Northwest Territories
314 Canada - Nunavut
315 Canada - Yukon
32 NEVADA
320 Mexico - Aguascalientes
321 Mexico - Baja California
322 Mexico- Baja California Sur
323 Mexico - Campeche
324 Mexico - Chiapas
325 Mexico - Chihuahua
326 Mexico - Coahuila
327 Mexico - Colima
328 Mexico - Durango
329 Mexico - Guanajuato
33 NEW HAMPSHIRE
330 Mexico - Guerrero
331 Mexico - Hidalgo
332 Mexico - Jalisco
333 México - Mexico
334 Mexico - Michoacán
335 Mexico - Morelos
336 Mexico - Nayarit
337 Mexico - Nuevo León
338 Mexico - Oaxaca
339 Mexico - Puebla
34 NEW JERSEY
340 Mexico - Queretaro
341 Mexico - Quintana Roo
342 Mexico - San Luis Potosí
343 Mexico - Sinaloa
344 Mexico - Sonora
345 Mexico - Tabasco
346 Mexico - Tamaulipas
347 Mexico - Tlaxcala
348 Mexico - Veracruz
349 Mexico - Yucatán
35 NEW MEXICO
350 Mexico - Zacatecas
351 Mexico - Mexico City
36 NEW YORK
37 NORTH CAROLINA
38 NORTH DAKOTA
39 OHIO
40 OKLAHOMA
41 OREGON
42 PENNSYLVANIA
44 RHODE ISLAND
45 SOUTH CAROLINA
46 SOUTH DAKOTA
47 TENNESSEE
48 TEXAS
49 UTAH
50 VERMONT
51 VIRGINIA
53 WASHINGTON
54 WEST VIRGINIA
55 WISCONSIN
56 WYOMING
60 AMERICAN SAMOA
66 GUAM
72 PUERTO RICO
78 VIRGIN ISLANDS

Mileage Sub-Rule ids

Code Description
1 General roads
2 Private roads

Terminology

We list here all terms involved in CleaRoad API.

Account manager

Account manager is the entity that manage the RUC Payers accounts and the collection of the RUC (Road User Charging) from the RUC Payers.

Road charger

Road charger is the entity that owns and/or operate the road. The road charge is the final recipient of the RUC. The road chargers could be states, cities, municipalities as well as private companies.

RUC payer

The RUC payer is in charge of paying the RUC to the account manager for its usage of road owned by the road charger. The road charger has defined who are the RUC payer usually through rules and regulations. The account manager needs to report to the clearinghouse which RUC payers he has under its management. The RUC payer can be an individual or an organisation.

ClearRoad Platform

ClearRoad Platform or the clearinghouse is the centralized financial platforms that hosts the global ledger(s) for different account managers, data collectors and road chargers. Road Account is the account that keeps a balance of all the RUC transactions associated with a vehicle registration.

Properties and messages

Billing Period

An object that defines the time period that an invoice covers. The billing period is defined by the account manager for the RUC Payers he is managing.

Billing Period Message

A message sent by an account manager to the ClearRoad Platform to create a new billing period or update an existing one in the CR Platform.

Currency

A system of money used by an account manager for the billing of RUC Payers. Example of a currency: USD, Euro.

On Board Unit (OBU)

An object that represents an external or internal device that collects the driving data of a vehicle. In the case of an external device, it is usually inserted in the standard diagnostics port of the vehicle. The data collected by an OBU is used to compute the RUC and record different road events. An OBU is represented in the ClearRoad Platform by a unique alphanumeric identifier.

Odometer Message

A message sent by the data collector to the ClearRoad Platform to indicate the odometer reading of a specific vehicle, for a specific moment of time. It is used in the case of the RUC is not computed from the data collected by the RUC Payer's OBU.

Odometer Reading

An object that contains information on the odometer of a vehicle and the exact timestamp when this reading was observed.

Organisation

An object that represents an organisation in the ClearRoad Platform that interacts with it. Examples of organisations: data collectors, account managers, public bodies etc.

Person

An object that represents a physical person of an organisation related to ClearRoad Platform and that has an account in the ClearRoad system.

Road Account Message

An message sent by an account manager to ClearRoad Platform that defines transaction validation parameters to allocate a road usage data to a specific road account. This message could be also used to define necessary objects like OBU and vehicle.

Road Account Registration

An object that indicates the registration of the pair OBU and vehicle by a Road Account.

Road Event

An object that indicates an anomaly or an important event to a vehicle or an on board unit (like plugging/unplugging an on board unit in a vehicle, detection of mileage abnormalities etc). Usually detected by the On Board Unit. Road Events include also the anomalies of data collection reporting, detected by the ClearRoad Platform.

Road Account

An object that identifies the RUC Payer and his road account registrations.

Road Mileage Message

A message that contains mileage data and events for a road account for some period of time. The road mileage messages are generated by the on board units. This message could be replaced by a combination of Road Message and Road Event Messages.

Road Event Message

A message that is used in the case of the Road Mileage Message is not used. It contains information about events related to a vehicle or an on board unit.

Road Message

A message that is used in the case if the Road Mileage Message is not used. It contains mileage data for some period of time.

Road Report Request

A request of RUC balances sent by an account manager to ClearRoad Platform. The time period for which the request is made is bound by the validity time of the billing period referenced in the request.

Road Transaction

An object that describes the charges for the road usage, depending of the service used. It is generated by Road Messages (in the production ClearRoad Platform, it is generated by the Road Mileage Message).

Sale Trade Condition

An object that contains a pricing list for all services.

Service

An object that represents a service provided by ClearRoad. A service is a right to drive on specific roads, using a predefined road taxation for them.

Vehicle

A physical vehicle that is identified in the system by its Vehicle Identification Number (VIN).