Search Vehicle by VIN

The Vehicle Registration API allows you to search for a vehicle by supplying its VIN. The request requires a VIN provided as a path variable. This will return either a matching vehicle or a null.

It is critical that the confidence of the match is checked. MotorWeb will seek to always provide a match however there may be instances where a definitive match is not possible, or the vehicle is very rare and not in our database.

Possible confidence scores are:

• standard

• reduced

• unsupported

• failed

Any confidence score below standard should be investigated.

In all cases, and importantly if a matching vehicle is unable to be identified, we will return the upstream_vehicle field allowing you to identify how the relevant road transport authority describes the vehicle.

Depending on your use case you may wish to allow front-end users to manually classify the vehicle using the upstream_vehicle as a guide to fill out a Facet-style search.

Features

The API has a series of optional features that augment the response payload. Please note that these features do incur an additional cost. An example of the API is as follows:

https://api.motorweb.app/market-data/v1/vehicles/vin/:vin?features=vsrr,odo_history,odo_predictionapi.motorweb.app

vsrr

This feature will return information on the vehicle's fuel economy, emissions, pollutants and safety as recorded by NZTA.

Example output:

"vsrr": {
        "fuel_economy": {
            "star_rating": 6
        },
        "emissions": {
            "co2": 0,
            "star_rating": 6
        },
        "pollutants": {
            "star_rating": 6,
            "test_regime": "EXEMPT"
        },
        "safety": {
            "driver": {
                "test_regime": "Based on 2019 ANCAP rating for 19-23 models"
            }
        }
    },

odo_history

This feature will return information on the vehicle's mileage as recorded by NZTA and any other mileage information we may have access to.

Example output:

"odo_history": [
        {
            "read_date": "2021-09-23",
            "odometer": 7
        },
        {
            "read_date": "2024-09-17",
            "odometer": 7230
        }
    ],

odo_prediction

This feature utilises prior mileage history plus our custom algorithm to return a prediction of the vehicle's mileage as at today.

Example output:

"odo_prediction": {
        "prediction": 7269,
        "days_since_read": 6,
        "increase_since_read": 39,
        "avg_yearly": 2420,
        "avg_daily": 6.63,
        "ag_market_avg": 47412
    }

Retrieve Vehicle By VIN

get

Retrieve a vehicle by its Vehicle Identification Number

Path parameters

vinstringRequired

VIN of the vehicle

Example: JMFXTGA2WBZ004048

Query parameters

featuresstringOptional

Comma separated list of additional data packages to append to the core response

Example: odo_history

Responses

200

Vehicle Response

application/json

400

Bad Request / Validation Failed

application/json

404

Resource for id cannot be found

application/json

500

Unknown error on the service side

application/json

get

/v1/vehicles/vin/{vin}

HTTPcURLJavaScriptPython

GET /v1/vehicles/vin/{vin} HTTP/1.1
Host: 
Accept: */*

{
  "success": true,
  "vehicle": {
    "id": 2983792384791283,
    "region": "nz",
    "title": "2007 Mitsubishi Outlander XLS Automatic",
    "year": 2007,
    "make": "Mitsubishi",
    "model": "Outlander",
    "badge": "XLS",
    "series": null,
    "model_year": null,
    "release_month": 1,
    "release_year": 2007,
    "body_type": "Wagon",
    "body_config": null,
    "transmission": "Continuously Variable (CVT)",
    "transmission_type": "Automatic",
    "wheelbase": null,
    "wheelbase_type": null,
    "fuel": "Petrol",
    "fuel_type": "Petrol",
    "engine": "Piston",
    "engine_type": "Piston",
    "drive": "AWD",
    "drive_type": "Four Wheel Drive",
    "num_doors": 5,
    "num_seats": 5,
    "num_gears": 6,
    "num_cylinders": 4,
    "capacity_cc": 2359,
    "power_kw": 127,
    "torque_nm": 230,
    "range": 250
  },
  "upstream_vehicle": "2007 Mitsubishi OUTLANDER Outlander 2.4 AWD XLS Wagon CVT Petrol Wagon 2,359cc 127kw",
  "confidence": "standard",
  "colour": "GREY",
  "vin": "ABCDEFGH123456789",
  "additional_vehicles": [
    {
      "id": 2983792384791283,
      "region": "nz",
      "title": "2007 Mitsubishi Outlander XLS Automatic",
      "year": 2007,
      "make": "Mitsubishi",
      "model": "Outlander",
      "badge": "XLS",
      "series": null,
      "model_year": null,
      "release_month": 1,
      "release_year": 2007,
      "body_type": "Wagon",
      "body_config": null,
      "transmission": "Continuously Variable (CVT)",
      "transmission_type": "Automatic",
      "wheelbase": null,
      "wheelbase_type": null,
      "fuel": "Petrol",
      "fuel_type": "Petrol",
      "engine": "Piston",
      "engine_type": "Piston",
      "drive": "AWD",
      "drive_type": "Four Wheel Drive",
      "num_doors": 5,
      "num_seats": 5,
      "num_gears": 6,
      "num_cylinders": 4,
      "capacity_cc": 2359,
      "power_kw": 127,
      "torque_nm": 230,
      "range": 250
    }
  ],
  "odo_history": [
    {
      "read_date": "2024-11-21",
      "odometer": 110000
    }
  ],
  "odo_prediction": {
    "prediction": 2458,
    "days_since_read": 15,
    "avg_yearly": 3650,
    "avg_daily": 100,
    "ag_market_avg": 120
  },
  "vsrr": {
    "fuel_economy": {
      "star_rating": 5,
      "consumption": 15
    },
    "emissions": {
      "co2": 15,
      "star_rating": 5,
      "consumption": 15
    },
    "pollutants": {
      "star_rating": 5,
      "test_regime": "EU3"
    },
    "safety": {
      "driver": {
        "star_rating": 5,
        "test_regime": "EU3"
      }
    }
  }
}