This JSON-based web service allows you to generate emissions, energy economy and safety information and ratings for use in VEEEL-compliant listings when selling a vehicle.
The web service can be used for server-side processing through a GET or POST, or in browser-based solutions through an Ajax call or similar.
In order to use this service you first need to sign up at https://resources.fuelsaver.govt.nz. For full documentation see https://resources.fuelsaver.govt.nz/bulkusers.
| Parameters | Values | Call examples | ||
|---|---|---|---|---|
| Request: | ||||
| api | labels | |||
| plate | [a valid licence plate] - [GNJ454 | FLW415 | HOON] | ?params={"api":"labels","plate":"flw415","listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | ||
| vin | [a valid 17 character VIN] | ?params={"api":"labels","vin":"","listingid":"veh_flw415"} | ||
| listingid | [a unique ID value for the vehicle] - this is a mandatory field | ?params={"api":"labels","listingid":"veh_flw415"} | ||
| chassisnumber | [a valid chassis number] | ?params={"api":"labels","chassisnumber":"","listingid":"veh_flw415"} | ||
| modelcode | [a valid NZ or Japanese model code] | ?params={"api":"labels","modelcode":"300E6H5SP25","modelvariant":"","listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | ||
| modelvariant | [a valid model variant number (classification number)] - required with a Japanese model code | ?params={"api":"labels","modelcode":"ABA-WF0A0D","modelvariant":"3","listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | ||
| login | [a valid VFEL login token obtained on signup for the VFEL service] | Get yours at: https://resources.fuelsaver.govt.nz | ||
| Using multiple lookup fields | plate=gnj454 will not find a vehicle because it has been de-registered | ?params={"api":"labels","plate":"gnj454","listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | ||
| Adding the VIN will return the vehicle label | ?params={"api":"labels","plate":"gnj454","vin":"WF0MXXGCDM6S47735" ,"listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | |||
| (NZ) modelcode | using default list price information for Clean Car | ?params={"api":"labels","modelcode":"HA590/590AE/1","modelvariant":"","listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | ||
| forceJSONheaders | force the API to return Content-Type application/json | ?params={"api":"labels","forceJSONheaders":"","plate":"flw415","listingid":"veh_flw415","login":"[enter your vfel login]"} Test this call | ||
| Sample response: | ||||
|
{ "Mode":"LIVE:", "ErrorCode":0, "LabelVersion":"2023(a)", "LastRegUpdate":"2022-02-01T00:00:00", "ModelCode":"300E6H5SP25;", "Variant":0, "Make":"MAZDA", "Model":"MAZDA3", "SubModel":"SPORTHATCH SP25", "VehicleType":"Car(Small): Hatchback", "Seats":5, ""Doors":null, "FuelType":"Petrol", "EngineSize":2488, "EnginePower":122, "Transmission":"6-gear manual", "Drive":"", "Weight":1770, "CO2stars":3, "CO2StarsText":"1.5 stars out of 6", "CleanVehiclePromoBadge":null, "CleanVehiclePromoBadge64":null, "CO2Text":"229 grams/km", "CO2":229, "YearlyCO2":3.21, "CleanVehicleText":"", "CleanVehicleInd":"", "CO2Disclaimer":"", "CleanVehicleDisclaimerLong":null, "CleanVehicle":0.0, "FuelStars":3, "FuelStarsText":"1.5 stars out of 6", "FuelPromoBadge":null, "FuelPromoBadge64":null, "AnnFuelCostText":"Annual fuel cost of $3,360", "FuelEconomyText":"9.6L per 100km", "FuelEconomyDisclaimer":""Cost per year is an estimate based on petrol price of $2.80 per litre and an average distance of 14000 km. Emissions and Energy Economy figures standardised to 3P WLTP.", "SafetyStars":8, "SafetyStarsText":"4 stars out of 5", "SafetyPromoBadge":"safety-star-4.png", "SafetyPromoBadge64":null, "DriverSafetyTest":"Based on 2021 UCSR rating for 09-13 models", "PollutantsStars":6, "TestRegime":"A79/01", "warningSeverity":null, "warning":null, "warningAction":null, "warningDetails":null, "hasBeenDamaged":null, "cannotBeSold":null, "mvrYear":"2010" } |
||||
Implementation steps for a browser-based solution:
$.ajax('https://resources.fuelsaver.govt.nz/api/?params={"api":"labels","listingid":"[unique_vehicle_id]","login":"[your_vfel_login]","plate":"flw415"}',
{
type: "GET",
dataType: "json",
success: function (result) {
/*
A successful result object looks like:
{"Mode":"LIVE:","ErrorCode":0,"LabelVersion":"2022(a)","IDmatched":"P:FLW415","LastRegUpdate":"2022-03-31T00:00:00","ModelCode":"300E6H5SP25;","Variant":0,"Make":"MAZDA","Model":"MAZDA3","SubModel":"SPORTHATCH SP25","VehicleType":"Car(Small): Hatchback","Seats":5,"Doors":null,"FuelType":"Petrol","EngineSize":2488,"EnginePower":122,"Transmission":"6-gear manual","Drive":"","Weight":1770,"CO2stars":3,"CO2StarsText":"1.5 stars out of 6","CleanVehiclePromoBadge":null,"CleanVehiclePromoBadge64":null,"CO2Text":"229 grams/km","CO2":229,"YearlyCO2":3.21,"CleanVehicleText":"No rebate or fee","CleanVehicleInd":"Not eligible","CO2Disclaimer":"This car has already been registered in New Zealand and is not eligible for a Clean Car fee or rebate.","CleanVehicleDisclaimerLong":null,"CleanVehicle":0.0,"FuelStars":3,"FuelStarsText":"1.5 stars out of 6","FuelPromoBadge":null,"FuelPromoBadge64":null,"AnnFuelCostText":"Annual fuel cost of $3,360","FuelEconomyText":"9.6L per 100km","FuelEconomyDisclaimer":"Cost per year is an estimate based on petrol price of $2.50 per litre and an average distance of 14000 km. Emissions and Energy Economy figures standardised to 3P WLTP.","SafetyStars":8,"DriverSafetyStars":8,"SafetyStarsText":"4 stars out of 5","SafetyPromoBadge":"safety-star-4.png","SafetyPromoBadge64":null,"DriverSafetyTest":"Based on 2021 UCSR rating for 09-13 models","PollutantsStars":6,"TestRegime":"A79/01","warningSeverity":null,"warning":null,"warningAction":null,"warningDetails":null,"hasBeenDamaged":null,"cannotBeSold":null,"mvrYear":"2010"}
An unsuccessfull result might look like:
{"error":"Invalid input parameters"}
or
{"ErrorCode":40,"Explanation":"No valid plate, VIN or other details specified."}
*/
if(result.ErrorCode == 0){
$('#your_data_container').html(data_from_webservice);
}else{
$('#your_data_container').html(result.Explanation);
}
},
error: function(xhr, status, the_error){
/* handle the ajax call failing e.g. server 500 errors*/
}
}
});
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
if (xhr.readyState === 4){
document.getElementById('your_data_container').innerHTML = data_from_webservice;
}
};
xhr.open('GET', 'https://resources.fuelsaver.govt.nz/api/?params={"api":"labels","listingid":"[unique_vehicle_id]","login":"[your_vfel_login]","plate":"flw415"}');
xhr.send();
var response = await fetch('https://resources.fuelsaver.govt.nz/api/?params={"api":"labels","listingid":"[unique_vehicle_id]","login":"[your_vfel_login]","plate":"flw415"}',{
method: 'GET',
headers: {'Content-Type':'application/json'}
});
response.json();