> ## Documentation Index
> Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Recherche géographique immobilière : zones, bbox, distance

> Filtrer par zone : 4 modes administratifs + 2 modes géométriques (bbox, distance) + multi-zones OR.

Le filtre `location[]` est un **tableau** : chaque entrée définit **une** zone, et les zones sont combinées en `OR` côté moteur. Vous disposez de 6 modes : 4 administratifs (codes) et 2 géométriques (lat/lng).

## Vue d'ensemble

| Catégorie     | Mode         | Champ                                        | Quand l'utiliser                     |
| ------------- | ------------ | -------------------------------------------- | ------------------------------------ |
| Administratif | Code postal  | `postalCode`                                 | Zone connue par CP                   |
| Administratif | Code INSEE   | `inseeCode`                                  | Identifiant commune unique (5 chars) |
| Administratif | Département  | `department`                                 | Zone large (ex. `"75"`)              |
| Administratif | Ville        | `city`                                       | ⚠️ **ignoré**                        |
| Géométrique   | Bounding box | `locationCoordinate.location.geoBoundingBox` | Carte interactive (viewport)         |
| Géométrique   | Rayon        | `locationCoordinate.location.geoDistance`    | "Tout dans X km autour de Y"         |

## Modes administratifs

### Code postal

```json theme={null}
{ "location": [{ "postalCode": "75011" }] }
```

### Code INSEE

```json theme={null}
{ "location": [{ "inseeCode": "75056" }] }
```

### Département

```json theme={null}
{ "location": [{ "department": "75" }] }
```

### Ville (⚠️ ignoré)

<Snippet file="/snippets/warning-city-deprecated.mdx" />

## Modes géométriques

### `geoBoundingBox` — rectangle latitude/longitude

```json theme={null}
{
  "location": [{
    "locationCoordinate": {
      "location": {
        "geoBoundingBox": {
          "topLeft":     { "lat": 48.9020, "lon": 2.2240 },
          "bottomRight": { "lat": 48.8155, "lon": 2.4699 }
        }
      }
    }
  }]
}
```

**Contraintes** :

* `topLeft.lat > bottomRight.lat` (latitude croît vers le nord).
* `topLeft.lon < bottomRight.lon` (longitude croît vers l'est).

Une bbox inversée ne lève pas d'erreur côté moteur mais retourne **0 résultat**.

### `geoDistance` — rayon autour d'un point

```json theme={null}
{
  "location": [{
    "locationCoordinate": {
      "location": {
        "geoDistance": {
          "pin": { "lat": 48.8584, "lon": 2.2945 },
          "distanceKm": 20
        }
      }
    }
  }]
}
```

## Multi-zones — logique OR

`location` étant un array, **chaque entrée est combinée en OR**. Mélangez librement les modes :

```json theme={null}
{
  "location": [
    { "postalCode": "75011" },
    { "department": "92" },
    { "department": "93" },
    {
      "locationCoordinate": {
        "location": {
          "geoDistance": { "pin": { "lat": 48.8584, "lon": 2.2945 }, "distanceKm": 5 }
        }
      }
    }
  ]
}
```

→ Résultats : Paris 11e **OU** 92 **OU** 93 **OU** 5 km autour de la Tour Eiffel.

<Warning>
  **Différence PROPERTY vs ADVERT** : côté `/properties/search` et `/properties/search/alerts`, `location` est un **array** (multi-zones OR). Côté `/adverts/search` et `/adverts/search/alerts`, `location` est un **objet unique** — pour cibler plusieurs zones côté advert, créez une alerte par zone. Cf [Property vs Advert](/concepts/property-vs-advert).
</Warning>

## Quel mode choisir ?

```mermaid theme={null}
flowchart TD
  Start["Quelle est ma zone ?"] --> Q1{"Connue par<br/>code admin ?"}
  Q1 -- "1 commune" --> CP["postalCode<br/>ou inseeCode"]
  Q1 -- "1 département" --> Dep["department"]
  Q1 -- "Non" --> Q2{"Forme<br/>géométrique ?"}
  Q2 -- "Rectangle / viewport carte" --> BB["geoBoundingBox"]
  Q2 -- "Rayon autour d'un point" --> Dist["geoDistance"]
```

## Anti-patterns

<Warning>
  * **`distanceKm` = 0 ou négatif** → erreur ou 0 résultat selon le mode.
  * **Bbox inversée** (`topLeft.lat < bottomRight.lat`) → 0 résultat.
  * **Mixer `postalCode` et `city` dans la même entrée** → `city` est ignoré, donc le `postalCode` prend le dessus, mais c'est ambigu. Choisissez **un** mode par entrée.
</Warning>

## Pour aller plus loin

* [Filtres communs](/concepts/filtres-communs) — l'ensemble des autres filtres de search.
* [Playbook — recherche géographique avancée](/playbooks/recherche-geographique-avancee)
* [Search Properties](/api-v2-reference/properties-search/search-properties)