> ## 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.

# Géocoder une adresse pour filtrer une recherche

> Pipeline BAN/BANO Gouv (search/reverse) → injecter (lat, lon) ou postalCode dans un filtre Fluximmo.

## Goal

Partir d'une **adresse FR en texte libre** (saisie utilisateur, ligne CRM, point d'intérêt) et arriver à une **recherche Fluximmo géolocalisée** sans accroc : géocoder, choisir le bon mode de filtre, et appeler `/properties/search`.

## Scénario

Vous construisez une app où l'utilisateur tape une adresse ("12 rue de Rivoli, Paris" ou "Tour Eiffel"), et vous voulez lister les annonces Fluximmo dans un rayon autour. Vous n'avez pas les coordonnées GPS, juste la string. Ce playbook vous donne le pipeline complet.

## Étapes

<Steps>
  <Step title="1. Comprendre le service GEO Fluximmo">
    Le service de géocodage exposé par Fluximmo est le service public **BAN/BANO du gouvernement français** (`api-adresse.data.gouv.fr`), opéré et proxifié par Fluximmo.

    **Pourquoi passer par nous plutôt que d'appeler le service Gouv directement ?**

    * Pas de rate-limit côté Gouv à gérer vous-même (Fluximmo absorbe).
    * Une seule clé d'API pour toute la stack (search Fluximmo + géocodage).
    * Endpoints harmonisés et monitoring unifié.

    **Transparence assumée** : ce n'est pas une brique propriétaire. C'est de la donnée publique fiable, simplement intégrée à votre écosystème API Fluximmo.
  </Step>

  <Step title="2. Géocoder une adresse (forward)">
    `GET /geocoding/search?q=<adresse>` renvoie `lat`, `lon`, `postalCode`, `inseeCode`, et un `score` de confiance.

    ```bash theme={null}
    curl -G "https://geo.fluximmo.io/search" \
      --data-urlencode "q=12 rue de Rivoli, Paris" \
      --data-urlencode "limit=1" \
      -H "x-api-key: $FLUXIMMO_API_KEY"
    ```

    ```text theme={null}
    # Pseudocode parse
    top         = response.features[0]
    lat         = top.geometry.coordinates[1]
    lon         = top.geometry.coordinates[0]
    postal_code = top.properties.postcode
    insee_code  = top.properties.citycode
    score       = top.properties.score      # 0..1
    ```

    <Tip>
      Toujours encoder l'adresse (URL encoding) — utilisez `--data-urlencode` côté curl, ou un équivalent natif (`URLSearchParams`, `params=...`) côté code applicatif.
    </Tip>
  </Step>

  <Step title="3. Choisir comment injecter dans Fluximmo search">
    Selon la précision recherchée, trois options se présentent.

    **Option A — Par `postalCode`** (large, agrège toutes les communes du CP)

    Idéal pour des analyses macro ou marchés où le CP est l'unité naturelle.

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

    **Option B — Par `inseeCode`** (granularité commune)

    Légèrement plus fin que le CP en zone rurale (un CP peut couvrir plusieurs communes).

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

    **Option C — Par `geoDistance`** (rayon précis autour du pin)

    C'est la vraie option "X km autour de cette adresse".

    ```json theme={null}
    {
      "filterProperty": {
        "location": [{
          "locationCoordinate": {
            "location": {
              "geoDistance": {
                "pin": { "lat": 48.858, "lon": 2.295 },
                "distanceKm": 5
              }
            }
          }
        }]
      }
    }
    ```

    Voir [Recherche géographique](/concepts/recherche-geographique) pour le détail des modes (`postalCode`, `inseeCode`, `department`, `geoBoundingBox`, `geoDistance`, multi-zones OR).
  </Step>

  <Step title="4. Appeler /properties/search avec le filtre">
    ```bash theme={null}
    curl -X POST "https://api.fluximmo.io/v2/protected/properties/search" \
      -H "x-api-key: $FLUXIMMO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "size": 50,
        "sortBy": "FIRST_SEEN_AT",
        "orderBy": "DESC",
        "search": {
          "filterProperty": {
            "location": [{
              "locationCoordinate": {
                "location": {
                  "geoDistance": {
                    "pin": { "lat": 48.858, "lon": 2.295 },
                    "distanceKm": 5
                  }
                }
              }
            }],
            "offer": [{ "type": "OFFER_RENT" }],
            "type": ["CLASS_FLAT"],
            "meta": {
              "isTotallyOffline": false,
              "firstSeenAt": { "min": "2025-01-01T00:00:00.000Z" }
            }
          }
        }
      }'
    ```
  </Step>

  <Step title="5. Reverse géocoder (lat, lon → adresse)">
    Cas d'usage : étiqueter un point GPS issu d'un résultat Fluximmo (par exemple une app mobile qui affiche l'adresse sur une fiche annonce).

    `GET /geocoding/reverse?lat=...&lon=...`

    ```bash theme={null}
    curl -G "https://geo.fluximmo.io/reverse" \
      --data-urlencode "lat=48.858" \
      --data-urlencode "lon=2.295" \
      -H "x-api-key: $FLUXIMMO_API_KEY"
    ```

    ```text theme={null}
    # Pseudocode
    addr = response.features[0].properties.label
    ```
  </Step>

  <Step title="6. Batch CSV (sync ou async)">
    Pour géocoder N adresses en lot.

    * **Sync** : `POST` d'un fichier CSV en multipart, réponse synchrone (limite de taille).
    * **Async** : pipeline batch async disponible sur demande — écrivez à [contact@fluximmo.com](mailto:contact@fluximmo.com) pour activation et SLA.

    Choisir async dès que le volume dépasse quelques milliers de lignes ou que la latence sync devient pénalisante.
  </Step>
</Steps>

## Architecture / flow

```mermaid theme={null}
flowchart LR
  Adresse["Adresse string<br/>'1 rue de Rivoli, Paris'"] --> GeoSearch["GET /geocoding/search"]
  GeoSearch --> Coords["lat, lon, postalCode,<br/>inseeCode, score"]
  Coords --> Choose{"Précision<br/>voulue ?"}
  Choose -- "Large (CP entier)" --> ByCP["postalCode"]
  Choose -- "Commune" --> ByInsee["inseeCode"]
  Choose -- "Rayon précis" --> ByDist["geoDistance<br/>{pin, distanceKm}"]
  ByCP --> FluxSearch["POST /v2/protected/<br/>properties/search"]
  ByInsee --> FluxSearch
  ByDist --> FluxSearch
  FluxSearch --> Results["Annonces filtrées"]
```

## Pièges fréquents

<Warning>
  **Adresse approximative → plusieurs candidats.** Le géocodage renvoie une liste triée par `score` (0 à 1). Toujours prendre le premier candidat (`features[0]`), et idéalement filtrer si `score < 0.5` (qualité douteuse).
</Warning>

<Warning>
  **Outre-mer / étranger.** BAN/BANO couvre la métropole et certains DOM-TOM. Pour des adresses étrangères, le service ne renverra rien d'utile — vérifier la couverture avant.
</Warning>

<Warning>
  **Encoder l'adresse.** Les caractères spéciaux (`é`, `'`, espaces) cassent les URL non-encodées. Utiliser `--data-urlencode` (curl) ou un équivalent natif côté code applicatif.
</Warning>

<Warning>
  **`distanceKm: 0`.** Un rayon nul n'a pas de sens et est rejeté. Mettre au minimum `0.5`.
</Warning>

<Warning>
  **Code postal ≠ commune.** En zone rurale, un même CP peut couvrir 5+ communes. Si vous avez besoin d'une granularité commune, utiliser `inseeCode` plutôt que `postalCode`.
</Warning>

## Pour aller plus loin

* [Géocodage direct (recherche)](/api-geocoding-reference/search/recherche-par-géocodage-direct)
* [Géocodage inverse](/api-geocoding-reference/reverse/recherche-par-géocodage-inverse)
* [Concept — Recherche géographique](/concepts/recherche-geographique)
* [Playbook — Recherche géographique avancée](/playbooks/recherche-geographique-avancee)
* Pipeline batch async géocodage — sur demande (`contact@fluximmo.com`)

<Card title="Clé test gratuite — 1 semaine" icon="key" href="https://my.fluximmo.io">
  Créez un compte sur **my.fluximmo.io** pour récupérer une clé API test gratuite (1 semaine, accès limité). Aucun paiement requis.
</Card>