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

	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.apac.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.apac.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.apac.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.