---
title: "Market intelligence"
description: "Precomputed price snapshots for a brand, model, and year window."
canonical: "https://thecarapi.com/docs/market"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/market.md"
---

# Market intelligence

Precomputed price snapshots for a brand, model, and year window.

## GET /api/cars-bg-market

Cars.bg Bulgarian retail market snapshot.

**Scope:** `market`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `brand / make` | Query string | string | yes | `BMW` | /api/brands -> brands[].name | Brand name. |
| `model` | Query string | string | yes | `320d` | /api/models?brand=bmw -> models[].name | Model name. |
| `year` | Query string | integer | yes | `2019` | Centre year chosen by your application. | Centre registration year. |
| `flex` | Query string | integer | no | `2` | Tolerance chosen by your application. | Year tolerance from 0 to 10. Default 1. |

### Example requests

```http
GET https://api.thecarapi.com/api/cars-bg-market?brand=BMW&model=320d&year=2019
```

```http
GET https://api.thecarapi.com/api/cars-bg-market?make=Audi&model=A4&year=2020&flex=2
```

### Example response

```json
{
  "success": true,
  "snapshot": {
    "brand": "BMW",
    "model": "320d",
    "year": 2019,
    "sample_size": 42,
    "avg_price_eur": 23100,
    "min_price_eur": 17900,
    "max_price_eur": 29500
  }
}
```

**Notes.** Missing parameters return 400. An unknown brand/model, or a snapshot that has not been built yet, returns 404.

## GET /api/auction-market

Auction-market price snapshot for the same brand, model, and year window.

**Scope:** `market`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `brand / make` | Query string | string | yes | `BMW` | /api/brands -> brands[].name | Brand name. |
| `model` | Query string | string | yes | `320d` | /api/models?brand=bmw -> models[].name | Model name. |
| `year` | Query string | integer | yes | `2019` | Centre year chosen by your application. | Centre registration year. |
| `flex` | Query string | integer | no | `2` | Tolerance chosen by your application. | Year tolerance from 0 to 10. Default 1. |
| `scope` | Query string | enum | no | `active` | Choose all, active, or inactive. | Default all. |

### Example requests

```http
GET https://api.thecarapi.com/api/auction-market?brand=BMW&model=320d&year=2019&scope=active
```

```http
GET https://api.thecarapi.com/api/auction-market?brand=Kia&model=EV6&year=2023&flex=1
```

### Example response

```json
{
  "success": true,
  "snapshot": {
    "brand": "BMW",
    "model": "320d",
    "year": 2019,
    "scope": "active",
    "sample_size": 118,
    "avg_price_eur": 18400
  }
}
```