Documentation / Concepts / Filtres de localisation

Filtres de localisation

Un filtre de localisation est obligatoire sur chaque requête. Sans lui, l'API retourne une erreur 400 missing_location.

Commencez par resolve_location

Si vous partez d'une saisie libre, appelez GET /v1/locations/resolve (ou resolve_location dans MCP). Il accepte les accents, tirets, abréviations et ordinaux, puis retourne les filtres canoniques à réutiliser.

Les quatre types de filtre

Paramètre	Format	Exemple
`code_postal`	String 5 chiffres	`"75011"`, `"69001"`
`commune`	String MAJUSCULES	`"BORDEAUX"`, `"PARIS 11"`
`code_departement`	String 2–3 chiffres	`"75"`, `"974"`
`latitude` + `longitude`	Float WGS84 + radius_m	`48.8566, 2.3522, 500`

# Par code postal
GET /v1/transactions?code_postal=75011

# Résoudre une saisie libre avant une analyse
GET /v1/locations/resolve?query=Paris%2011e

# Par commune (MAJUSCULES obligatoires)
GET /v1/transactions?commune=BORDEAUX

# Paris — utiliser le format arrondissement
GET /v1/transactions?commune=PARIS%2011

# Par département
GET /v1/transactions?code_departement=69

# Par rayon GPS (en mètres)
GET /v1/comparables?latitude=48.8581&longitude=2.3790&radius_m=500

Paris — arrondissements obligatoires

Les transactions parisiennes sont stockées par arrondissement : PARIS 01 à PARIS 20. Requêter PARIS sans numéro d'arrondissement peut provoquer un timeout sur les endpoints de liste.

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

# ✅ Correct — commune_base pour chercher tout Paris
GET /v1/transactions?code_departement=75  # tous les arrondissements

# ❌ Incorrect — trop large, timeout probable
GET /v1/transactions?commune=PARIS        # pas d'arrondissement précisé

Lyon et Marseille aussi

Lyon et Marseille utilisent le même format : LYON 01–LYON 09, MARSEILLE 01–MARSEILLE 16. Pour requêter toute une ville, préférez le code_departement.

Grands codes postaux parisiens

Les codes postaux 75015 à 75020 couvrent des volumes importants. Sans filtre de date, le serveur applique automatiquement une limite temporelle et retourne un champ notice dans la réponse.

Pour éviter cette auto-limitation, ajoutez explicitement date_debut :

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

Rayon GPS et restriction temporelle

Lors d'une recherche par latitude + longitude, le paramètre radius_m s'applique. Au-delà de 1000 m de rayon, la requête est automatiquement limitée aux 12 derniers mois pour éviter un scan trop large.

Le champ notice vous en informe

Quand une limite automatique est appliquée, la réponse contient : "notice": "Applied date_debut=2024-04-01 automatically". Ce n'est pas une erreur — c'est une indication que les résultats sont temporellement restreints.

Communes en MAJUSCULES

Une fois la localisation résolue, transmettez le champ communecanonique retourné par Normi. Les appels directs restent plus prévisibles en majuscules :

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

Authentification

Nouveautés