Valuation Predict

Generate market accurate predictions for vehicles.

Overview

The Valuation API can be used to determine new vehicles' present retail and trade values and their residual values.

This API requires authentication and an appropriate license attached to it.

A Vehicle ID returned from the Vehicle Search API or Vehicle Facet API is required to use the API.

How is a valuation provided?

AutoGrab’s Valuation captures the asking prices from the past week for a specific vehicle’s year, make, model, and variant at a given mileage, sourced from private sellers and dealers within a selected state. It excludes government charges but includes GST, assuming the vehicles are in good condition and fitted with standard OEM accessories.

Leveraging advanced machine learning and updated weekly, our pricing integrates active listings and recently delisted data from public marketplaces. AutoGrab emphasises the most recent data to deliver comprehensive valuations that reflect current market trends.

Each estimate includes a confidence score, which indicates AutoGrab’s certainty in the valuation. Two key factors determine this score:

• The number of vehicles listed in the past 365 days for the specific vehicle type

• A detailed accuracy analysis of the pricing algorithm for that vehicle type

The confidence score ranges from 0 to 1, with 1 representing the highest confidence level

Value a vehicle using an AutoGrab ID

Value a vehicle using an AutoGrab ID

POST/v2/valuations/predict

Authorization

ApiKeyAuth

Body

application/json

request body

regionRegion (enum)

aunzukmy

vehicle_id*string

The AutoGrab Vehicle ID which corresponds to the vehicle that should be valued

kmsnumber

The odometer reading of the vehicle. If no reading is provided, the average value will be subsituted

rrp_overwritenumber

rrp_adjustmentnumber

condition_scorenumber

regostring

The registration plate of the vehicle, for reference purposes only

statestring

The registration state of the vehicle, if applicable

vinstring

The VIN of the vehicle, for reference purposes only

Response

200400401

Success

Body

*/*

successboolean

predictionobject

boundsobject

max_offerobject

Request

JavaScriptCurlPython

const response = await fetch('/v2/valuations/predict', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "vehicle_id": "text"
    }),
});
const data = await response.json();

Response

200400401

{
  "success": true,
  "prediction": {
    "id": "text",
    "vehicle_id": "text",
    "created_at": "text",
    "kms": 0,
    "price": 0,
    "score": 0,
    "retail_price": 0,
    "trade_price": 0,
    "adjustment": {
      "vehicle_id": "text",
      "type": "account",
      "enabled": false,
      "trade_adjustment": {
        "amount": 0,
        "type": "fixed"
      },
      "retail_adjustment": {
        "amount": 0,
        "type": "fixed"
      },
      "overrides": [
        {
          "id": "text",
          "min_kms": 0,
          "max_kms": 0,
          "trade_price": 0,
          "retail_price": 0
        }
      ]
    }
  },
  "bounds": {
    "retail": {
      "lower": 0,
      "upper": 0
    },
    "trade": {
      "lower": 0,
      "upper": 0
    }
  },
  "max_offer": {
    "reconditioning": 0,
    "profit_margin": 0,
    "lot": 0,
    "transport": 0,
    "admin": 0,
    "price": 0
  }
}

Example

Request

To retrieve a Vehicle ID, use the Vehicle Search APIs.

Starting with a vehicle ID post it to /v2/valuations/predict

{
    "region": "au",
    "catalogue": "autograb",
    "vehicle_id": "5804870883868672",
    "kms": 30000,
    "condition_score": 2
}

The condition score is optional and can be used to further refine your pricing prediction.

The Catalogue field is optional and will default to 'autograb' and the vehicle ID for performing a valuation. If you have access to Jato catalogue information, 'jato' can be passed as the catalogue and a JATO ID as the vehicle_id. The valuation will then be performed using the JATO information.

Response

{
    "success": true,
    "prediction": {
        "id": "a2955915-9611-40ef-8b98-b827dad76ff4",
        "vehicle_id": "5804870883868672",
        "kms": 57306,
        "price": 20622,
        "score": 0.9239,
        "retail_price": 20622,
        "trade_price": 17122,
        "adjustment": null
    },
}

Pricing ID

The payload returned by price prediction requests will include an ID, which you can use to refer to the pricing request in the future. The /v2/valuations/history/{PRICING_ID} method will return the response from a previous pricing request, and you can also use the Pricing ID to track price changes with the Price Changes API.

To get a paginated list of all your previous price predictions, you can use the /v2/valuations/history endpoint.

Condition Score

You can manipulate the valuation returned by the prediction endpoint by supplying a condition score. The condition score can be between 1 and 5. A condition of 1 is poor, and 5 is excellent.

Supplying any other numbers will return the default trade_price, which assumes excellent condition.

If you're building a user interface that allows the user to choose a condition, it is recommended that you follow the industry standard in the table below.

Condition	Condition Score
Poor	1
Fair	2
Average	3
Good	4
Excellent	5

Features

Positive Equity

The positive equity feature identifies if the vehicle is in positive equity and the current equity position. To add an equity calculation to the Predict call, use features=equity

{
    "success": true,
    "prediction": {
        "id": "599aff94-7c79-4b9c-a976-ff39c3892190",
        "vehicle_id": "4825547834130432",
        "kms": 20000,
        "price": 32669,
        "score": 0.8515,
        "retail_price": 32669,
        "trade_price": 27769,
        "adjustment": null
    },
    "equity": {
        "positive_equity": true,
        "equity_position": 15769
    }
}

Valuation Bounds

If you require the upper and lower bounds used to calculate a prediction, you can use features=bounds.

{
    "success": true,
    "prediction": {
        "id": "e2813b16-1012-41b5-9ea3-3b65675c50fd",
        "vehicle_id": "5804870883868672",
        "kms": 57306,
        "price": 20622,
        "score": 0.9239,
        "retail_price": 20622,
        "trade_price": 17122,
        "adjustment": null
    },
    "bounds": {
        "retail": {
            "lower": 19622,
            "upper": 21872
        },
        "trade": {
            "lower": 16122,
            "upper": 18372
        }
    }
}

Adjustments

Both the Residual Value and Used Value APIs support pricing adjustments. These can be used to retrieve a more accurate price prediction of a vehicle if the provided price is not already accurate enough.

Recommended Retail Price Adjustment

CommentTo adjust the stored Recommended Retail Price you can supply a rrp_adjustment value in the payload which accepts a number — positive or negative.CommentThis is useful when a car is fitted with factory extras, the Price When New can be increased for each of the options to get a better price prediction.Comment

Recommended Retail Price Overwrite

To adjust the stored Recommended Retail Price you can supply a rrp_adjustment value in the payload which accepts a number — positive or negative.

Predicted Retail and Trade Price Adjustments

The Pricing Adjustments API (/v2/valuations/adjustments) allows you to configure fixed or percentage adjustments for specific Vehicle IDs.

Per-Vehicle pricing adjustments will apply to price predictions that you perform using the same API Key and for the same Vehicle ID.

If you set a Retail Price Adjustment for a vehicle, the trade price will also be affected because the trade price is derived from the retail price. If you set an adjustment for both the retail price and the trade price, both adjustments will be applied to the trade price while the retail price is only affected by the retail price adjustment.

When you perform a price prediction, you will receive a summary of the price adjustments that were applied, if any.

Example

Below is an example price prediction payload with predicted trade and retail adjustments applied.

{
    "success": true,
    "prediction": {
        "id": "d028809e-0ef5-42de-9699-8b71fd1aee65",
        "vehicle_id": "5631424535199744",
        "price": 12347,
        "score": 0.81820,
        "retail_price": 14847,
        "trade_price": 2042.46,
        "adjustment": {
            "vehicle_id": "5631424535199744",
            "enabled": true,
            "retail_adjustment": {
                "type": "fixed",
                "amount": 2500,
                "overridden": false
            },
            "trade_adjustment": {
                "type": "percentage",
                "amount": 0.2,
                "overridden": false
            },
            "overrides": []
        }
    }
}

Predicted Retail and Trade Price Overrides

In addition to price adjustments, you also have the option to override retail and trade prices for specific vehicle IDs where the odometer reading falls within a set range. Price overrides are configured using the Price Override API at /v2/valuations/adjustments/{VEHICLE_ID}/overrides.

If you have configured a retail or trade price override that applies to a price prediction, the overridden price will be returned instead of the AutoGrab valuation. This will bypass any price adjustments that you may have configured, and the response payload will indicate this with the {overridden: true} flag.

Retail price overrides will impact the predicted trade price in the same way that retail price adjustments impact the trade-price - unless you have configured a trade price override. Suppose you have both a trade override and a retail override. In that case, the two overridden prices will be returned without pre-processing (except for calculating condition scores, if applicable - see below).

Example

Below is an example price prediction payload where price adjustments and price overrides have been configured. In this example, the retail price adjustment has been overridden by the retail price override, and the trade price adjustment has been applied.

{
    "success": true,
    "prediction": {
        "id": "faa847f1-d428-46e1-b2d6-b47a00173d6e",
        "vehicle_id": "5631424535199744",
        "price": 11697,
        "score": 0.81820,
        "retail_price": 12000,
        "trade_price": 1700,
        "adjustment": {
            "vehicle_id": "5631424535199744",
            "retail_adjustment": {
                "type": "fixed",
                "amount": 2500,
                "overridden": true
            },
            "trade_adjustment": {
                "type": "percentage",
                "amount": 0.2,
                "overridden": false
            },
            "overrides": [
                {
                    "id": "1ef42b79-c580-4055-a39b-e5257f81d0d9",
                    "min_kms": 80000,
                    "max_kms": 90000,
                    "trade_price": null,
                    "retail_price": 12000
                }
            ]
        }
    }
}