# 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:

```json
{ "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**

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

**Ruby**

```ruby
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))
```

**Python**

```python
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))
```

**JavaScript**

```javascript
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));
```

| Market | `country` | Currency | Mileage unit |
| --- | --- | --- | --- |
| Denmark | `DK` | DKK | km |
| Sweden | `SE` | SEK | mil |
| Germany | `DE` | EUR | km |
| Italy | `IT` | EUR | km |
| Spain | `ES` | EUR | km |
| Austria | `AT` | EUR | km |
| Portugal | `PT` | EUR | km |
| Poland | `PL` | PLN | km |
| Finland | `FI` | EUR | km |
| Romania | `RO` | EUR | km |
| United Kingdom | `GB` | GBP | mi |
| France | `FR` | EUR | km |
| Switzerland | `CH` | CHF | km |
| Netherlands | `NL` | EUR | km |
| Belgium | `BE` | EUR | km |

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](/docs/concepts/markets) 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`](/docs/errors#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`](/docs/errors#unsupported_country), and a request without `country` returns `400` [`country_required`](/docs/errors#country_required).

## Mileage and units

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

| Unit | Meaning | Typical market |
| --- | --- | --- |
| `km` | Kilometres | Most markets |
| `mi` | Miles | United Kingdom |
| `mil` | Scandinavian mile, 10 km | Sweden |

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**

```bash
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
```

**Ruby**

```ruby
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))
```

**Python**

```python
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))
```

**JavaScript**

```javascript
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));
```

[Open this request in the console playground](https://data-services.autouncle.com/console/playground?example=valuation_se)

`electric_range_km` is always in kilometres, whatever the market.

## Price basis per market

`pricing.price_basis` works the same way everywhere:

| Value | Meaning |
| --- | --- |
| `dealer_retail` (default) | Expected asking price when freshly listed by a dealer |
| `private_sale` | Expected asking price from a private seller |

`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](/contact-sales) to change them. See [authentication & keys](/docs/authentication).

`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](/docs/reference/account#market-codes-in-allowed_countries).

## 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](/docs/concepts/markets).
- [Batch & bulk valuations](/docs/guides/batch-valuations), which share limits across all markets.
- [Show notes & attributions](/docs/guides/notes-and-attributions).