Data

The figure below shows the data exchange format to be provided by the fuel third party and EROAD:

fuel api 1

Use of site coordinates is strongly recommended in preference to site address as it avoids any inaccuracy introduced with geocoding.

Fields

This table provides field details:

 XML element or Tag   Description   Data type   Example data 
 transactionData   Holds the transaction data   fuelTransactionData   
 supplier   Unique fuel supplier name   string   BP 
 customerName   Name of the customer   string   Acme Ltd 
 customerAccountNumber   Account number of the customer in the fuel provider system   string   5566778899 
 transactionId   Unique id of the transaction. When voiding a previous transaction use the same transactionId.   long   123456789 
 transactionType   Is the transaction a PURCHASE or a VOID of a previous purchase due to refund/reversal.  fuelTransactionType   PURCHASE 
 transactionTimestamp   UTC date and time of the transaction   dateTime   
 fuelCardNumber   Unique fuel card number   string   7234123412341234 
 registrationPlate   Vehicle registration plate. Must be uppercase no spaces. This or vin must be provided.  string   ABC123 
 registrationState   The state the vehicle plate has been issued by using the ISO 3166-2 codeset. If omitted NZ is assumed.   string   US-OR

 AU-NSW

 NZ
 vin  The VIN of the vehicle. This or registrationPlate must be provided.  string  LJCPCBLCZ11000237
 amount   Total dollar amount of purchase   decimal   215.63 
 siteId   Unique site identifier. Only in use in NZ.   int   5 
 terminalId   Unique terminal id at the fuel up site   int   2 
 siteCoordinates   Latitude and longitude of the fuel up site   coordinate   
 siteAddress   Street address of the fuel up site if the coordinate cannot be provided. This will mean EROAD will attempt to geocode the street address.   address   
 fuelProducts   List of products purchased in the transaction  fuelProduct   
 productCode   Type of product purchased. Refer to Fuel Product Codes for valid codes.   fuelProductCode   DIESEL 
 quantity   Quantity of product purchased. Could be 60.35 litres or 1 wash for example. Decimal places used depending on the product type.   decimal   60.35 
 unit (optional)   The units the quantity has been expressed in. See here for the default unit for different fuels.   

 LITRE, US_GALLON, KILOGRAM, or POUND 

 amount   Total dollar amount of the product purchased. Two wash products at $10.00 would be represented at 20.00.   decimal   81.47 
 taxPaid   Whether or not tax has been paid on this product. Will be defaulted according to the expected behaviour of the jurisdiction if not provided.   

 PAID or NOT_PAID 

 consumer (optional)   The consumer of a fuel product if known. If not provided VEHICLE will be defaulted.     VEHICLE, REEFER or OTHER 
 source (optional)   Whether the fill up occurred at a retail location or at a bulk store of previously purchased fuel. If not provided RETAIL will be defaulted.   

 RETAIL or BULK 

 odometer (optional)   The vehicle odometer at the time of fill up   int   135456 

Fuel Product Codes:

 Code   Default Unit 
 DIESEL   LITRE 
 BIODIESEL 
 PETROL_REGULAR 
 PETROL_PREMIUM 
 GASOHOL 
 ETHANOL 
 METHANOL 
 E85 
 M85  
 A55  
 LPG    KILOGRAM 
 LNG 
 CNG  
 LPG_BOTTLE  
 OIL   N/A     
 MAINTENANCE  
 WASH  
 MISCELLANEOUS 

 

Site address geocoding

Site addresses must be geocodable using HERE Maps.

The more precise you can specify a location, the more accurate the location will be reported. That might seem obvious, but HERE Maps will provide a 'successful' result on coarse data, and this might be undesirable.

Geocoding examples

Imprecise address

Rosedale Rd, Pinehill, Auckland 0632, New Zealand

https://wego.here.com/directions/mix//Rosedale-Rd,-Pinehill,-Auckland-0632,-New-Zealand

(Location displayed is a calculated geographic 'centre' of the street.)

 

Precise Address

154 Rosedale Rd, Pinehill, Auckland 0632, New Zealand

https://wego.here.com/directions/mix//154-Roesdale-Rd,-Rosedale,-Auckland-0632,-New-Zealand

(Location displayed is the target location.)

Fuel Transaction XSD

Please download Fuel Transaction XSD here.