# La Centrale Facets API Documentation

Retrieve live listing totals and facet distributions for the La Centrale filter grammar. This is the search backbone: counts and facet distributions, no listing hits. Supports make, model, price, year, mileage, energy, gearbox, category, region, and good-deal-badge filters.

- **Documentation:** [https://scrappa.co/docs/lacentrale-api/lacentrale_facets](https://scrappa.co/docs/lacentrale-api/lacentrale_facets)
- **API group:** La Centrale API
- **Endpoint:** `GET https://scrappa.co/api/lacentrale/v1/facets`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `families` | string | No | Vehicle family: AUTO, UTILITY, MOTO, SCOOTER, or QUAD. |
| `facets` | array | No | Comma-separated facet names: MAKE, MODEL, VERSION, CATEGORY, ENERGY, GEARBOX, CRITAIR, PRICE, REGION, INTERNAL_COLOR, EXTERNAL_COLOR, GOOD_DEAL_BADGE. |
| `make_model` | string | No | Filter by make:model, e.g. RENAULT:CLIO. |
| `zip_code` | string | No | Filter by zip code. Requires zip_code_distance. |
| `zip_code_distance` | string | No | Distance from zip code, e.g. 50km. Required when zip_code is present. |
| `price_min` | integer | No | Minimum price in EUR. |
| `price_max` | integer | No | Maximum price in EUR. |
| `mileage_min` | integer | No | Minimum mileage in km. |
| `mileage_max` | integer | No | Maximum mileage in km. |
| `year_min` | integer | No | Minimum first registration year. |
| `year_max` | integer | No | Maximum first registration year. |
| `energies` | array | No | Comma-separated energy types: ESSENCE, DIESEL, HYBRID, ELECTRIC, etc. |
| `gearbox` | string | No | Gearbox type: AUTO or MANUAL. |
| `categories` | array | No | Comma-separated category codes, e.g. SUV_4X4_CROSSOVER. |
| `regions` | array | No | Comma-separated region codes, e.g. FR-OCC. |
| `customer_family_codes` | array | No | Comma-separated customer family codes, e.g. PART. |
| `good_deal_badges` | array | No | Comma-separated badges: VERY_GOOD_DEAL, GOOD_DEAL, EQUITABLE_DEAL, BAD_DEAL, NOT_COMPUTED. |
| `crit_air` | array | No | Comma-separated Crit'Air vignette codes. |
| `page_size` | integer | No | 0 = counts only (default). hits is always empty. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/lacentrale/v1/facets?families=AUTO&facets=MAKE&page_size=0"
```

## Example response

```json
{
    "success": true,
    "data": {
        "total": 342880,
        "seed": 12345,
        "facets": {
            "vehicle_make": [
                {
                    "value": "ABARTH",
                    "count": 446
                },
                {
                    "value": "ALFA ROMEO",
                    "count": 2019
                }
            ]
        }
    },
    "meta": {
        "endpoint_family": "facets"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | Invalid aggregation found |  |
|  | Missing or invalid API key |  |
|  | Upstream service error |  |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)