Partner Gateway API

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.

Integrations API Diagram2 01

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.

General Guidelines

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.

 

Request Format

The PUT request ...

 

Description

Example Request

Host path

A specific hostname is used to access the API based on the customer location (e.g., North America, New Zealand, or Australia).

 
North America

https://api.na.eroad.com

 
New Zealand or https://api.apac.eroad.com  
Australia    
     
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.
https://api.na.eroad.com/CustomerApi/vehicle/customdata?rego=XXXXX&regoState=US-OR
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.

 
key

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:

CDATA Example

<attributes xmlns="http://www.eroad.co.nz/schema/CustomData">
    <attribute>
        <key>Serial Number</key>
        <value>12345XXX12345</value> 
    </attribute>
    <attribute>
        <key>Front Temp °C</key>
        <value>11</value>
        <status>WARNING</status>
        <utcTimestamp>2014-06-11T12:00:05Z</utcTimestamp>
    </attribute> 
    <attribute>
         <key>Delivery Address</key>
         <value><[![CDATA[260 Oteha Valley Road,
Albany, Auckland 0632,
New Zealand.]]></value> 
         <status>OK</status>
         <utcTimestamp>2014-06-11T12:00:07Z</utcTimestamp>
    </attribute> 
    <!-- More Attributes -->
</attributes>

 

Response Format

After client completes sending data via a 'PUT' operation, the EROAD server sends an HTTP response back to the client.

Response Codes  
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.