Market & demand

Understand the market for a car type in one country: how many are on sale, what they cost, how fast listings leave the market, how long that takes, whether the type moves faster or slower than the market as a whole, and how that has changed over the last 12 months. Field tables on this page are generated from the OpenAPI contract.

Use both together: POST /v1/market for the type (a 2019 Volvo XC60 diesel automatic), then POST /v1/selling-times for the one car you are pricing.

#What the figures are

Every figure is an aggregate over the listings AutoUncle tracks in the requested market, never a single listing.

• Listings, not registrations. The counts describe the listings AutoUncle tracks, not every car registered or sold.
• Left the market is not always a sale. A listing that left the market was removed from sale, which is usually, but not always, a sale. Its price is the last asking price, not a transaction price.
• The same segment as the similar-cars link. The segment is the search behind a valuation's similar_cars_url, and segment.similar_cars_url opens it on the market's own AutoUncle site. It is make and model plus whatever you send that narrows it. A model year gives that year and one either side, kept within the model generation; in Germany and Italy it gives the exact year. Mileage narrows the segment only in Germany and Italy. Fuel, gearbox and body narrow it too.
• Small numbers are withheld. A figure built from fewer than 10 listings is left out, and suppressed says which block or month. Prices are rounded to three significant figures and mileage to 1,000 km or mi (100 Scandinavian mil), so no listing can be picked out.
• Freshness. On-sale and left-the-market figures can be up to three hours old, because they come from a shared cache. as_of says when the request read them.

#Demand measures

• days_of_supply = listings on sale ÷ listings leaving the market per day. It is how long today's stock would last at the current pace.
• turnovers_per_year = 12 × listings that left in 30 days ÷ listings on sale.
• relative_to_market = the segment's days_of_supply ÷ the same measure for the market's whole used-car stock. Below 1 the type moves faster than the market.
• level is high when relative_to_market is below 0.8, low above 1.25, and average in between. Comparing with the market itself keeps the level meaningful across countries, and it cancels most of the effect of listings removed for reasons other than a sale.

flow.new_listings_still_on_sale_per_day counts only listings that are still on sale. A listing that went on sale and left within the window is not in it. So it is not total inflow, and subtracting left_market_per_day from it does not give a net change.

#Status and cost

Test keys return deterministic example figures (synthetic: true) for free. Nothing is stored: a replay with the same Idempotency-Key reads the market again without spending a credit, and there is no read-back endpoint. See credits.

#POST /v1/market

Market and demand figures for a car type.

Describes the market for a car type in one country: how many are on sale and at what prices and mileages, the price-rating mix, how fast listings arrive and leave the market, how long they take to leave, days of supply and a demand level relative to the whole market, and a 12-month trend of listings leaving the market. Send the same vehicle input as a valuation; at least a make and model must be recognised, and model year, mileage, fuel, gearbox and body narrow the segment exactly as the valuation's similar_cars_url does. Every figure is an aggregate over the listings AutoUncle tracks in that market (not registrations or confirmed sales); left the market means removed from sale. A figure built from fewer than 10 listings is withheld and listed in suppressed. One credit for a measured live result; partial and insufficient_data results, refusals, failures, idempotent replays and test keys are free. Needs the valuations:write scope and shares the valuation rate and concurrency limits. Nothing is stored: a replay with the same Idempotency-Key reads the market again without spending a credit.

Nothing is stored: a replay with the same Idempotency-Key reads the market again without spending a credit, and there is no read-back endpoint. Counts against the valuation rate limit and needs a valuation concurrency slot, like POST /v1/valuations.

• Scope: valuations:write
• Cost: One credit for a measured live result. partial and insufficient_data results, test keys, refusals, failures and idempotent replays are free.
• Rate limit: valuations bucket, default 60 requests per minute. See limits.

#Parameters

#Request body

application/json, a MarketRequest: A car type in one market: the same vehicle input as a valuation (a VehicleInput, a description or photos), of which at least a make and model must be recognised. Mileage and model year are optional and only narrow the segment as the similar-cars link does. Pricing does not apply. Unknown fields are rejected.

Structured example:

{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2019,
    "fuel": "diesel",
    "transmission": "automatic"
  }
}

Text example:

{
  "country": "DE",
  "description": "VW Golf 1.5 TSI 2020"
}

#Response

application/json, a MarketResponse: Market & demand figures for a car type in one market: aggregates over the listings AutoUncle tracks there, never a listing. Errors return a Problem as application/problem+json.

#Response headers

#Errors

#Examples

curl https://data-services.autouncle.com/v1/market \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: market-001' \
  -d @- <<'JSON'
{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2019,
    "fuel": "diesel",
    "transmission": "automatic"
  }
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/market")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "market-001"
request.body = JSON.generate({
  "country" => "SE",
  "vehicle" => {
    "make" => "Volvo",
    "model" => "XC60",
    "model_year" => 2019,
    "fuel" => "diesel",
    "transmission" => "automatic"
  }
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/market",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "market-001",
    },
    json={
        "country": "SE",
        "vehicle": {
            "make": "Volvo",
            "model": "XC60",
            "model_year": 2019,
            "fuel": "diesel",
            "transmission": "automatic"
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/market", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "market-001",
  },
  body: JSON.stringify({
    country: "SE",
    vehicle: {
      make: "Volvo",
      model: "XC60",
      model_year: 2019,
      fuel: "diesel",
      transmission: "automatic"
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));