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 : transactions, comparables et estimation

Les trois usages n'ont pas le même contrat. Pour les transactions,radius_m au-delà de 1 000 m applique, si aucune date n'est fournie, une fenêtre automatique de 12 mois. Les comparables (jusqu'à 36 mois) et l'estimation (jusqu'à 24 mois) respectent le rayon et l'horizon explicitement demandés : ils ne sont pas réduits silencieusement.

Le champ notice vous en informe

Pour les transactions, 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.

Démarrer petit, élargir explicitement

Commencez par 500 m et 12 mois. Réservez 2 km, et 36 mois pour les comparables, aux zones peu denses. Pour explorer un centre-ville dense, fournissez une fenêtre de date explicite et découpez l'exploration par périodes. Une réponse avec notice conserve les données déjà obtenues ; un dense_query_timeout signifie qu'aucun résultat exploitable n'a été produit, que les crédits sont remboursés et qu'il faut resserrer la requête. Un résultat vide reste, lui, une réponse complète sans vente correspondante.

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