Data is passed to EROAD via a REST PUT operation in an XML format. The custom data acquisition process from third Parties by EROAD is described in the drawing below. A request must be sent in a specific XML format.
NOTE: In this context, 'third party' means the provider of custom data for a vehicle.
Planning Your Integration
1. Obtain an API key. See APIkey setup.
2. Obtain the hostname for your country.
3. Identify vehicles to monitor.
One of the first steps to integrating data from a third party system into Depot is to determine how to identify vehicles so the attributes match in both systems. Ideally, a field like rego or vin can be used, but the customer and integrator need to co-ordinate with each other.
4. Arrange vehicle attributes for optimal field display on the Activity page.
When you created an APIkey, it triggered Depot to create a Gateway tab in the Activity page, under the map area, for monitorinig your incoming data from the third party system. Attributes added in the XML request are displayed as fields in the Gateway tab and are loaded in the order of the request. So it is important to structure the attributes based on the most logical use to reduce requiring users to scroll through across the page.
5. Select attribute status levels.
You can select from four status levels for each attribute of the data: no status, OK, WARNING and ERROR.
Always use NO STATUS for attributes that can never be set to WARNING or ERROR. These are likely to include metadata or informational attributes, or simple status attributes as an ON/OFF indicator.
Use WARNING OR ERROR if the value of an attribute indicates a problem that require a response from the dispatcher when the value is outside of an acceptable range.
To select between WARNING and ERROR - determine the most likely workflow of a dispatcher when they see the state.
If a dispatcher must act immediately, it is probably an ERROR. If the dispatcher needs to monitor the status, it is likely a WARNING.
NOTE: You are not required to use both ERROR and WARNING for a given value; and either can be omitted if it makes more sense.
The PUT request ...
A specific hostname is used to access the API based on the customer location (e.g., North America, New Zealand, or Australia).
|New Zealand or||https://api.apac.eroad.com|
|Query Parameters||The purpose of the query parameters is to identify the specific vehicle from which you require data. Use the following options as a part of the URL during the PUT operation:|
|Rego & Rego State||Rego is the registration plate or license plate of the vehicle. Rego State is the country
(in the case of a country like NZ without states) or the country and state that the vehicle was registered.
|VIN||Vehicle Identification Number of the vehicle and is a unique 17-character string.||https://api.na.eroad.com/CustomerApi/vehicle/customdata?vin=XXXXX|
|Asset Code||An arbitrary code that can be assigned to a vehicle from the Depot Vehicle Administration page.||https://api.na.eroad.com/CustomerApi/vehicle/customdata?assetCode=XXXXX|
|Display Name||Name of the vehicle from the Depot Vehicle Administration page.||https://api.na.eroad.com/CustomerApi/vehicle/customdata?displayName=XXXXX|
|Request Header||All requests must include the following two HTTP headers:|
|ApiKey||Data received by EROAD is mapped to an organization by the ApiKey header. This is a unique identifier generated provided by a Client Administrator from each specific organization. See API Key Setup.|
|Content-type||Each request should also include the Content-Type header set to application/xml.|
|Request Body||The body of each request sent must contain data in the XML format described below. An XSD is also available to validate your XML in various tools.|
|Custom data attributes||
Attached to a root node attributes are 'attribute nodes' that contain the custom data. Each custom data attribute recieved by EROAD includes up to four tags - key, value, status, and utcTimestamp.
Both key and value will accept any unicode characters, these will be displayed on the Activity Screen however some extremely un-usual unicode characters may not display in certain browsers.
Required. An alpha numeric description of the attribute (e.g., Front Temperature °C). Maximum 50 characters.
|value*||Required. An alpha numeric value of the attribute (e.g., 11). Maximum 500 characters.|
|status||Optional. Defines the status of a value in the data (e.g. WARNING). If this field is added, it must include one of the following statuses: OK, WARNING, or ERROR.|
|utctimestamp||Indicates the time the data was acquired at the source, which must be in ISO Time Format (For example: 2014-06-11 12:00:05).|
|Zero attribute nodes||Accepted and used to blank out the current custom data display for a vehicle. However no more than 128 zero attrubute nodes are accepted per message.|
XML Schema Definition
|Click XLM Schema Definition to download.|
*The value attribute can contain CDATA (Character Data) sections to accomodate keeping the original text as illustrated below:
<key>Front Temp °C</key>
<value><[![CDATA[260 Oteha Valley Road,
Albany, Auckland 0632,
<!-- More Attributes -->
After client completes sending data via a 'PUT' operation, the EROAD server sends an HTTP response back to the client.
|204||Indicates data is accepted. Occures with a valid API Key, valid query parameters, and a valid XML structure.|
|401||Indicates a missing API Key.|
|403||Indicates an invalid API key.|
|Other 400||Indicates other error and includes an explanatory message.|
|500||Indicates an error occured in Depot while processing the request. If this error persists,contact EROAD support with the time the error occurred, and the nature of the request that was being made.|