Partner Gateway API

Request Format

Data should be passed to EROAD via a REST PUT operation containing an XML in the format described below.

Integrations API Diagram2 01

Figure 1 - Custom data acquisition from Third Parties by EROAD

NOTE: In this context 'Third Party' means the provider of custom data for a vehicle.

Host and Path

Currently there are three different regions that EROAD customers belong to. A different hostname will need to be used to access the API depending on whether the customer is in NZ, Australia, or North America.

Requests for NZ customers should go to: https://api.apac.eroad.com

Requests for North American customers should go to: https://api.na.eroad.com

Requests for Australian customers should go to: https://depot.eroad.com.au
Note that shortly the legacy australian instance will be merged into the APAC environment and the URL for NZ customers will become the correct one

Query Parameters

The purpose of the query parameters are to identify the vehicle that the data being sent relates to. One of the following options can be used 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 in.

Example 1: A vehicle registered in New Zealand will use query parameters like:

https://api.apac.eroad.com/CustomerApi/vehicle/customdata?rego=XXXXX&regoState=NZ

Example 2: A vehicle registered in New South Wales will use query parameters like:

https://api.apac.eroad.com/CustomerApi/vehicle/customdata?rego=XXXXX&regoState=AU-NSW

Example 3: A vehicle registered in Oregon will use query parameters like:

https://api.apac.eroad.com/CustomerApi/vehicle/customdata?rego=XXXXX&regoState=US-OR

VIN

A VIN is the Vehicle Identification Number of the vehicle and is a unique 17-character string.

Example: https://api.apac.eroad.com/CustomerApi/vehicle/customdata?vin=XXXXX

Asset Code

Asset Code is an arbitrary code that can be assigned to a vehicle from the MyEROAD Vehicle Admin Screen.

Example: https://api.apac.eroad.com/CustomerApi/vehicle/customdata?assetCode=XXXXX

Display Name

Display Name is the name given to the vehicle from the Depot Vehicle Admin Screen.

Example: https://api.apac.eroad.com/CustomerApi/vehicle/customdata?displayName=XXXXX

Request Headers

All requests must include two HTTP Headers:

ApiKey: Data received by EROAD will be mapped to an organisation by the ApiKey header, which must be the unique identifier generated provided by a Client Admin of the organisation information is being provided for. See the section Obtaining a Custom API-Key above for more details.

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.

Attached to a root node "attributes" will be "attribute" nodes containing custom data. Each custom data attribute recieved by EROAD will have upto four tags, which are the key, value, status and utcTimestamp.

key: An alpha numeric description of the attribute (For example: Front Temperature °C).
value: An alpha numeric value of the attribute (For example: 11).
status: A value defining the status with regard to the value of the data (For example: WARNING). The status field is optional but if included must be either 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).

The key and value fields are required, and are limited to 50 and 500 characters respectively.

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 be displaybale in certain browsers.

Note: The value attribute can contain CDATA (Character Data) sections to accomodate keeping the original text as illustrated in the example below.

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>

Note: Zero attribute nodes are accepted and will be used to blank out the current custom data display for a vehicle. However no more than 128 attrubute nodes will be accepted per message.

XML Schema Definition

Please click here to download the XML Schema Definition.

Response Format

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

Response Codes

Requests with a valid API Key, valid query parameters and an valid XML Structure will recieve a 204 response. This indicates the data has been accepted
Requests with a missing or invalid API Key will receive a 401 or 403 response respectively. If you are having trouble with an API Key supplied by an EROAD customer please verify the key with the customer before contactin EROAD support.
Requests with an other error should receive an error code in the 400's with an explanatory error message.
If a error occurs in MyEROAD processing the request a 500 error will be returned. If this error persists please contact EROAD support and be prepared to provide information about what time the error occurred and the nature of the request being made.

API Integration

Matching Vehicles

One of the first steps in an integration is to determine which way the Vehicles will be matched from the third party system to the data stored in MyEROAD. Hopefully a field like rego or vin can be used easily, but if required the customer and the integrator may need to co-ordinate in order to make sure that one field in both MyEROAD and the integrators system match.

Arranging Fields for Optimal Display

The MyEROAD Activity Screen displays attributes in the order that they are provided in the XML send to this API. So it's important to order the fields in a way that will make logical sense to most users. In general we recommend ordering the most referred to fields first, as they are visible without scrolling.

Choosing Status Levels

There are four status levels to choose between for each attribute of the data; no status, OK, WARNING and ERROR. In general no status should always be used for anything that can't ever be set to either WARNING or ERROR, this is likely to include metadata or informational attributes, and any simple status attributes such as an ON/OFF indicator. If the value of an attribute could indicate a problem that a dispatcher might need to deal with then the value can be set to WARNING or ERROR when the value is outside of an acceptable range. In order to choose between WARNING and ERROR think about the likely workflow of a dispatcher when they see the state, do they need to act immediately then it is likely an ERROR, should they keep an eye on it then it is likely a WARNING. Note that there is actually no need to use both ERROR and WARNING for a given value, either can be omitted if it makes more sense.