Introduction

Welcome to the ClearRoad API!

ClearRoad is an online platform that aims to centralize data in the Road Usage Charging industry and standardize its format.

Many actors in the Road Usage Charging industry can simplify their IT integration needs by using the ClearRoad platform through its API.

This document aims to provide complete steps on how to quickly get set-up to start building great applications using the ClearRoad API.

All API interactions with ClearRoad are described in this document. The ClearRoad API is focused around the synchronization of data rather than a specification of API messages. To learn more about the ClearRoad API messages, please review the API documentation.

QuickStart

Step 1. Install the library as dependency

We are using npm to install the ClearRoad api library. Open a terminal window in your project and install the dependency using the command:

npm i @clearroad/api -S

If you want to include the files directly in your page, you can include via our CDN:

<script src="https://clearroadlab.azureedge.net/lib/ajv.js"></script>
<script src="https://clearroadlab.azureedge.net/lib/rsvp.js"></script>
<script src="https://clearroadlab.azureedge.net/lib/jio.js"></script>
<script src="https://clearroadlab.azureedge.net/api/clearroad.js"></script>

Step 2. Create a new ClearRoad instance

(function(ClearRoad) {
  const cr = new ClearRoad('apiUrl', 'accessToken');
})(ClearRoad);

import { ClearRoad } from '@clearroad/api';
const cr = new ClearRoad('apiUrl', 'accessToken');

const ClearRoad = require('@clearroad/api').ClearRoad;
const cr = new ClearRoad('apiUrl', 'accessToken');

To create an instance, you will need to have the apiUrl (the url of the ClearRoad API instance) and an accessToken. If you do not have an access token, you can request one on the developer platform.

Step 3. Choose a local storage

const cr = new ClearRoad('apiUrl', 'accessToken', {
  type: 'indexeddb'
});

const cr = new ClearRoad('apiUrl', 'accessToken', {
  type: 'indexeddb'
});

// if using .env
CLEARROAD_URL=<url>
CLEARROAD_ACCESS_TOKEN=<access token>
DROPBOX_ACCESS_TOKEN=<access token>

const dotenv = require('dotenv');
dotenv.config();
const cr = new ClearRoad(process.env.CLEARROAD_URL, process.env.CLEARROAD_ACCESS_TOKEN, {
  localStorage: {
    type: 'dropbox',
    accessToken: process.env.DROPBOX_ACCESS_TOKEN
  }
});

The ClearRoad API is based on a synchronization process, which will effectively synchronize data from the ClearRoad Platform to a "local" storage. This local storage can be on a local server, on the browser, or on a remote server.

By default, the API will use indexeddb as local storage. To use another storage please refer to the API reference.

Step 4. Retrieve messages

cr.sync()
  .then(function() {
    console.log('sync done');
    return cr.allDocs();
  })
  .then(function(results) {
    console.log(results);
  });

await cr.sync();
console.log('sync done');
const results = await cr.allDocs();
console.log(results);

await cr.sync();
console.log('sync done');
const results = await cr.allDocs();
console.log(results);

Now that you're all setup, you can start by synchronizing your local storage and then query the data.

Concepts

Pushing data to ClearRoad API

The storage must first be instantiated:

const cr = new ClearRoad('APIUrl', 'accessToken');

Data can then be pushed on the storage using the post method, and then data is synchronized with the ClearRoad platform using:

(function(ClearRoad) {
  cr.post(data)
    .push(function() {
      return cr.sync();
    })
    .push(function() {
      console.log('sync done');
    });
})(ClearRoad);

await cr.post(data);
await cr.sync();
console.log('sync done');

await cr.post(data);
await cr.sync();
console.log('sync done');

Pushing data to ClearRoad is done by posting it in a local storage and synchronizing that storage with the ClearRoad API.

Data format and validation

You can install ajv to test your JSON messages:

$ npm install -g ajv-cli
$ ajv validate -s node_modules/@clearroad/api/definitions/road-account-message.json -d data.json

All of the data can be pushed to the ClearRoad Platform using the post method. To validate the data format, we are using the ajv library.

The list of valid data format can be found under the node_modules/@clearroad/api/definitions directory.

Retrieving data from ClearRoad API

The storage must first be instantiated:

const cr = new ClearRoad('APIUrl', 'accessToken');

Then create a query on the portal_type that you want:

(function(ClearRoad) {
  cr.allDocs({
    query: 'grouping_reference: "report" AND portal_type:"Road Account Message"',
    select_list: ['source_reference', 'state', 'comment']
  }).push(result => {
    for (let i = 0; i < result.data.total_rows; i++) {
      var ref = result.data.rows[i].value.source_reference;
      var state = result.data.rows[i].value.state;
      var comment = result.data.rows[i].value.comment;
      ...
    }
  });
})(ClearRoad);

const result = await cr.allDocs({
  query: 'grouping_reference: "report" AND portal_type:"Road Account Message"',
  select_list: ['source_reference', 'state', 'comment']
});
result.data.rows.forEach(row => {
  const ref = row.value.source_reference;
  const state = row.value.state;
  const comment = row.value.comment;
  ...
});

const result = await cr.allDocs({
  query: 'grouping_reference: "report" AND portal_type:"Road Account Message"',
  select_list: ['source_reference', 'state', 'comment']
});
result.data.rows.forEach(row => {
  const ref = row.value.source_reference;
  const state = row.value.state;
  const comment = row.value.comment;
  ...
});

After pushing data to the API, you can retrieve it using the cr.allDocs function.

Examples

Check the state of all messages:

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

Retrieve the Road Account associated with a Road Account Message:

const reference = 'my-account-reference';
await cr.post({
  portal_type: 'Road Account Message',
  account_reference: reference,
  ...
});
// use reference in search as "reference"
cr.allDocs({
  query: 'portal_type: "Road Account" AND reference: "' + reference + '"',
  select_list: ['source_reference', 'registrations']
});

API Reference

ClearRoad

The ClearRoad class contains a subset of functions from the underlying jIO.js library, which uses RSVP.js to chain functions like Promises. Please refer to their documentation for more information.

constructor

new ClearRoad('apiUrl', 'accessToken');

constructor(url, accessToken, options)

Initialise a new ClearRoad object to interact with the ERP5 storage.

post

cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
}).then(function(id) {
  // 'id' is the posted document 'source_reference'
})

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

post(data)

Returns: string The id of the posted message.

Posts data in your local storage and return the reference of the new document. Then use the sync method to synchronize the data with the ClearRoad API.

state

cr.post({...})
  .then(function(reference) {
    // posting a message returns the reference of the message
    // use reference to get the state of the message
    return cr.state(reference);
  })
  .then(function(state) {
    // state = 'processed'
  });

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

state(id)

Returns: ValidationStates The [state](#api-reference-clearroad-enums-validationstates) of the message.

Check for the processing state of the message. Allow some time after synchronizing before checking for the state.

sync

cr.sync();

sync(progress)

Returns: IQueue<void>

Synchronizes the local storage with the ClearRoad Platform (will make sure both storage contain the same data).

queryByState

cr.queryByState('rejected').then(function(results) {
  // rejected messages
});

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

queryByState(state, options)

Returns: IQueue<IJioQueryResults> Search results.

Retrieve the messages in a certain "processing" state. By default, when a message is not yet synchronized or processed, the state is not_processed.

allDocs

Query the documents from ClearRoad Platform:

cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
}).then(function(result) {
  // read rows in result.rows
})

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

Which returns object in the following format:

// with select_list: ['select_list_key']
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "value": {
      "select_list_key": "select_list_value"
    }
  }, ...]
}

// with include_docs = true
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "doc": {
      "key": "value"
    }
  }, ...]
}

allDocs(options)

Returns: IQueue<IJioQueryResults> Search results.

Query for documents in the local storage. Make sure .sync() is called before.

getReportFromRequest

cr.getReport('reference').then(function(report) {
  // read report
})

const report = await cr.getReport('reference');

const report = await cr.getReport('reference');

getReportFromRequest(sourceReference)

Returns: IQueue<any> The report as JSON.

Get a report using the Report Request reference.

getReport

cr.getReportFromRequest('reference').then(function(report) {
  // read report
})

const report = await cr.getReportFromRequest('reference');

const report = await cr.getReportFromRequest('reference');

getReport(reference)

Returns: IQueue<any> The report as JSON.

Retrieve the report with the given report reference. If you only have the reference of the report request, please use getReportFromRequest instead.

Enums

LocalStorageTypes

Note: this list does not contain the additional Node.js storages developped by ClearRoad available here.

PortalTypes

Each message is represented by a "portal_type" (or message category)

ValidationStates

When a message is processed by the ClearRoad platform, it will create a new message with a validation state.

GroupingReferences

Interfaces

IClearRoadOptions

IClearRoadOptionsLocalStorage

IJioQueryOptions

IJioQueryResults

IJioQueryResultsData

IJioQueryResultRow

IQueue

v2.7.0Show

This content is hidden by default. Click on "Show" above or in the menu to view it.

new ClearRoad('apiUrl', 'accessToken');

cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
}).then(function(id) {
  // 'id' is the posted document 'source_reference'
})

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

cr.post({...})
  .then(function(reference) {
    // posting a message returns the reference of the message
    // use reference to get the state of the message
    return cr.state(reference);
  })
  .then(function(state) {
    // state = 'processed'
  });

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

cr.sync();

cr.queryByState('rejected').then(function(results) {
  // rejected messages
});

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
}).then(function(result) {
  // read rows in result.rows
})

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

// with select_list: ['select_list_key']
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "value": {
      "select_list_key": "select_list_value"
    }
  }, ...]
}

// with include_docs = true
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "doc": {
      "key": "value"
    }
  }, ...]
}

cr.getReport('reference').then(function(report) {
  // read report
})

const report = await cr.getReport('reference');

const report = await cr.getReport('reference');

cr.getReportFromRequest('reference').then(function(report) {
  // read report
})

const report = await cr.getReportFromRequest('reference');

const report = await cr.getReportFromRequest('reference');

v3.0.1Show

This content is hidden by default. Click on "Show" above or in the menu to view it.

new ClearRoad('apiUrl', 'accessToken');

cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
}).then(function(id) {
  // 'id' is the posted document 'source_reference'
})

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

cr.post({...})
  .then(function(reference) {
    // posting a message returns the reference of the message
    // use reference to get the state of the message
    return cr.state(reference);
  })
  .then(function(state) {
    // state = 'processed'
  });

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

cr.sync();

cr.queryByState('rejected').then(function(results) {
  // rejected messages
});

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
}).then(function(result) {
  // read rows in result.rows
})

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

// with select_list: ['select_list_key']
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "value": {
      "select_list_key": "select_list_value"
    }
  }, ...]
}

// with include_docs = true
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "doc": {
      "key": "value"
    }
  }, ...]
}

cr.getReport('reference').then(function(report) {
  // read report
})

const report = await cr.getReport('reference');

const report = await cr.getReport('reference');

cr.getReportFromRequest('reference').then(function(report) {
  // read report
})

const report = await cr.getReportFromRequest('reference');

const report = await cr.getReportFromRequest('reference');

v3.0.2Show

This content is hidden by default. Click on "Show" above or in the menu to view it.

new ClearRoad('apiUrl', 'accessToken');

cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
}).then(function(id) {
  // 'id' is the posted document 'source_reference'
})

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

// 'id' is the posted document 'source_reference'
const id = await cr.post({
  key1: "value",
  key2: JSON.stringify({
    "subkey": "subvalue"
  })
});

cr.post({...})
  .then(function(reference) {
    // posting a message returns the reference of the message
    // use reference to get the state of the message
    return cr.state(reference);
  })
  .then(function(state) {
    // state = 'processed'
  });

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

// posting a message returns the reference of the message
const reference = await cr.post({
  ...
});
// use reference to get the state of the message
const state = await cr.state(reference);
// state = 'processed'

cr.sync();

cr.queryByState('rejected').then(function(results) {
  // rejected messages
});

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

const results = await cr.queryByState('rejected');
// rejected messages
console.log(results);

cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
}).then(function(result) {
  // read rows in result.rows
})

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

const result = await cr.allDocs({
  query: query_object,
  limit: [3, 42],
  sort_on: [['key1', 'ascending'], ['key2', 'descending']],
  select_list: ['key1', 'key2', 'key3'],
  include_docs: false
});
// read rows in result.rows

// with select_list: ['select_list_key']
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "value": {
      "select_list_key": "select_list_value"
    }
  }, ...]
}

// with include_docs = true
{
  "total_rows": 39,
  "rows": [{
    "id": "text_id",
    "doc": {
      "key": "value"
    }
  }, ...]
}

cr.getReport('reference').then(function(report) {
  // read report
})

const report = await cr.getReport('reference');

const report = await cr.getReport('reference');

cr.getReportFromRequest('reference').then(function(report) {
  // read report
})

const report = await cr.getReportFromRequest('reference');

const report = await cr.getReportFromRequest('reference');