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.

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

# 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

Le champ commune doit toujours être en majuscules, sans accents pour la recherche (le stockage inclut les accents) :

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

Authentification

Changelog