Documentation / Concepts / Location filters

Location filters

A location filter is required on every request. Without one, the API returns a 400 error missing_location.

Start with resolve_location

If you start from free text, call GET /v1/locations/resolve (or resolve_location in MCP). It accepts accents, hyphens, abbreviations and ordinals, then returns the canonical filters to reuse.

The four filter types

Parameter	Format	Example
`code_postal`	5-digit string (postcode)	`"75011"`, `"69001"`
`commune`	UPPERCASE string (municipality)	`"BORDEAUX"`, `"PARIS 11"`
`code_departement`	2–3 digit string (department)	`"75"`, `"974"`
`latitude` + `longitude`	WGS84 float + radius_m	`48.8566, 2.3522, 500`

# By postcode
GET /v1/transactions?code_postal=75011

# Resolve free-text input before an analysis
GET /v1/locations/resolve?query=Paris%2011e

# By municipality (UPPERCASE required)
GET /v1/transactions?commune=BORDEAUX

# Paris — use the arrondissement format
GET /v1/transactions?commune=PARIS%2011

# By department
GET /v1/transactions?code_departement=69

# By GPS radius (in metres)
GET /v1/comparables?latitude=48.8581&longitude=2.3790&radius_m=500

Paris — arrondissements required

Paris sales are stored by arrondissement: PARIS 01 to PARIS 20. Querying PARIS without an arrondissement number can time out on list endpoints.

# ✅ Correct — one arrondissement
GET /v1/stats/market?commune=PARIS%2011    # Paris 11th

# ✅ Correct — code_departement to cover all of Paris
GET /v1/transactions?code_departement=75  # every arrondissement

# ❌ Wrong — too broad, likely to time out
GET /v1/transactions?commune=PARIS        # no arrondissement given

Lyon and Marseille too

Lyon and Marseille use the same format: LYON 01–LYON 09, MARSEILLE 01–MARSEILLE 16. To query a whole city, prefer code_departement.

Large Paris postcodes

Postcodes 75015 to 75020 cover large volumes. Without a date filter, the server applies a time limit automatically and returns a notice field in the response.

To avoid this automatic limit, add date_debut (start date) explicitly:

GET /v1/transactions?code_postal=75015&date_debut=2024-01-01

GPS radius: transactions, comparables and valuation

The three uses don't follow the same contract. For transactions, a radius_m above 1,000 m applies an automatic 12-month window when no date is given. Comparables (up to 36 months) and valuation (up to 24 months) respect the radius and time span you ask for: they are never silently narrowed.

The notice field tells you

For transactions, when an automatic limit is applied, the response contains: "notice": "Applied date_debut=2024-04-01 automatically". That isn't an error — it tells you the results are restricted in time.

Start small, widen explicitly

Start with 500 m and 12 months. Keep 2 km, and 36 months for comparables, for sparse areas. To explore a dense city centre, give an explicit date window and split the exploration into periods. A response with a notice keeps the data already retrieved; a dense_query_timeout means no usable result was produced, the credits are refunded and the request needs narrowing. An empty result is still a complete answer: there was simply no matching sale.

Municipalities in UPPERCASE

Once the location is resolved, pass the canonical commune field returned by Normi. Direct calls are more predictable in uppercase:

✅ Correct	❌ Wrong
`BORDEAUX`	`bordeaux`
`LYON 07`	`Lyon 7`
`PARIS 11`	`Paris 11e`
`AIX-EN-PROVENCE`	`aix en provence`
`MARSEILLE 13`	`Marseille`

Rate limits

Pagination