Multiple markets

Value vehicles in several European markets from one integration. Each valuation belongs to exactly one market, with its own currency, mileage unit and price level; this guide shows how to choose the market, send mileage correctly and keep results apart.

#One market per valuation

country selects the market whose vehicle data, currency and conventions are used. A result applies only to that market. Every valued result carries a market_specific note that says so:

{ "code": "market_specific", "category": "limitation",
  "message": "This result applies only to the DK market, its currency and the stated price basis. Do not apply it to another market." }

Value a car in the market where it is, or will be, sold. Do not convert a Danish price into euros to price a car in Germany: value it in DE.

#Supported markets

GET /v1/catalogue/countries lists the markets and their mileage units:

curl https://data-services.autouncle.com/v1/catalogue/countries \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY"

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/catalogue/countries")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
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.get(
    "https://data-services.autouncle.com/v1/catalogue/countries",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/catalogue/countries", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
  },
});
console.log(JSON.stringify(await response.json(), null, 2));

Romanian results are in euros, because car prices in Romania are usually quoted in euros. Always read valuation.currency from the result rather than hard-coding this table. Markets, currencies & units covers each market in more detail.

Note: Being listed here does not mean every market is enabled for your workspace, or that a live valuation model is available in every market at every moment. New workspaces are enabled for every market above except Belgium, which GET /v1/catalogue/countries marks as "availability": "on_request"; contact sales to change your workspace's markets. Check with a request in the market you need; a market you may not use returns 403 country_not_enabled.

#Send the market code

Send the ISO 3166-1 alpha-2 code. It is case-insensitive (dk works) and normalized before any data is read; the result always reports it in upper case. The United Kingdom is GB. An unknown code returns 400 unsupported_country, and a request without country returns 400 country_required.

#Mileage and units

Send the odometer reading in the unit it was recorded in, and say which unit that is:

The service converts to the market's unit for the valuation. The returned vehicle, an AVS document, always reports the odometer in kilometres as vehicle.odometer.km, whatever the market: a car sent to GB with {"value": 28000, "unit": "mi"} comes back as {"km": 45062}. Store your original value alongside if you need it.

A Swedish example in Scandinavian miles, valued as a private sale:

curl https://data-services.autouncle.com/v1/valuations \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: valuation-se-001' \
  -d @- <<'JSON'
{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2019,
    "mileage": {
      "value": 9000,
      "unit": "mil"
    }
  },
  "pricing": {
    "price_basis": "private_sale"
  }
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/valuations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "valuation-se-001"
request.body = JSON.generate({
  "country" => "SE",
  "vehicle" => {
    "make" => "Volvo",
    "model" => "XC60",
    "model_year" => 2019,
    "mileage" => {
      "value" => 9000,
      "unit" => "mil"
    }
  },
  "pricing" => {
    "price_basis" => "private_sale"
  }
})
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/valuations",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "valuation-se-001",
    },
    json={
        "country": "SE",
        "vehicle": {
            "make": "Volvo",
            "model": "XC60",
            "model_year": 2019,
            "mileage": {
                "value": 9000,
                "unit": "mil"
            }
        },
        "pricing": {
            "price_basis": "private_sale"
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/valuations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "valuation-se-001",
  },
  body: JSON.stringify({
    country: "SE",
    vehicle: {
      make: "Volvo",
      model: "XC60",
      model_year: 2019,
      mileage: {
        value: 9000,
        unit: "mil"
      }
    },
    pricing: {
      price_basis: "private_sale"
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));

electric_range_km is always in kilometres, whatever the market.

#Price basis per market

pricing.price_basis works the same way everywhere:

valuation.price_basis_description gives a display-ready sentence. Neither basis is a trade-in or transaction price.

#Restrict keys by market

If one system serves only one market, give its key only that market: choose Allowed countries when you create the key. A request for any other market is then refused with 403 country_not_enabled, before anything is recorded. The workspace's own markets are set by AutoUncle; contact sales to change them. See authentication & keys.

GET /v1/account shows the markets the calling key can value in allowed_countries, as the ISO codes you send in country, such as DK and GB: the workspace's markets narrowed by the key's own restriction. See account.

#Catalogue across markets

The catalogue is shared by all markets: the same brand, model, generation and drivetrain IDs work in every country. A model that exists in the catalogue can still be rare or absent in a market's data, which shows up as lower precision rather than as an error.

#Pitfalls

• Comparing prices across markets. Different currencies, taxes and price levels. Compare within a market.
• Converting mileage twice. Send the original value and unit; do not convert and then send the original unit.
• Hard-coding currencies. Read valuation.currency.
• One key for everything. Market-restricted keys limit the damage of a misrouted request.

#Next steps

• Markets, currencies & units.
• Batch & bulk valuations, which share limits across all markets.
• Show notes & attributions.