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.