> ## 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éocodage direct (adresse → coordonnées)

> Service public BAN/BANO opéré par Fluximmo : adresse → coordonnées GPS.

## À quoi ça sert

`GET /search` résout une chaîne d'adresse libre (rue, ville, lieu connu) en **coordonnées GPS** + métadonnées administratives : code postal, code INSEE de la commune, type de voie, score de confiance.

**Transparence** : ce service expose la **Base Adresse Nationale (BAN/BANO)** publique française (`api-adresse.data.gouv.fr`), opérée et proxifiée par Fluximmo. C'est un service public ouvert ; en passant par Fluximmo vous bénéficiez d'une intégration unifiée à l'écosystème API (mêmes clés, mêmes quotas, monitoring), sans rate-limit côté gouvernement à gérer vous-même.

**Cas d'usage typiques** :

* Géocoder une adresse saisie par un utilisateur avant d'appeler une recherche Fluximmo (`/v2/protected/properties/search` avec filtre `location` lat/lon + radius).
* Récupérer le `inseeCode` d'une commune pour filtrer par code INSEE (plus précis que le code postal qui peut couvrir plusieurs communes).
* Normaliser des adresses entrées en clair dans un CRM avant export.

## Exemples

### E1 — Lieu connu : "Tour Eiffel"

<CodeGroup>
  ```bash curl theme={null}
  curl "https://geo.fluximmo.io/search?q=Tour+Eiffel&limit=1"
  ```

  ```python Python theme={null}
  import requests
  resp = requests.get(
      "https://geo.fluximmo.io/search",
      params={"q": "Tour Eiffel", "limit": 1},
      timeout=10,
  )
  print(resp.json())
  ```

  ```javascript Node theme={null}
  const url = new URL("https://geo.fluximmo.io/search");
  url.searchParams.set("q", "Tour Eiffel");
  url.searchParams.set("limit", "1");
  const resp = await fetch(url);
  console.log(await resp.json());
  ```
</CodeGroup>

Retourne typiquement `{ lat, lon, address, postalCode: "75007", inseeCode: "75107", ... }`.

### E2 — Adresse précise pour récupérer le code INSEE

<CodeGroup>
  ```bash curl theme={null}
  curl "https://geo.fluximmo.io/search?q=1+rue+de+Rivoli+Paris&limit=1"
  ```

  ```python Python theme={null}
  import requests
  resp = requests.get(
      "https://geo.fluximmo.io/search",
      params={"q": "1 rue de Rivoli Paris", "limit": 1},
      timeout=10,
  )
  hit = resp.json()["features"][0]
  print(hit["properties"]["citycode"], hit["geometry"]["coordinates"])
  ```

  ```javascript Node theme={null}
  const url = new URL("https://geo.fluximmo.io/search");
  url.searchParams.set("q", "1 rue de Rivoli Paris");
  url.searchParams.set("limit", "1");
  const resp = await fetch(url);
  const hit = (await resp.json()).features[0];
  console.log(hit.properties.citycode, hit.geometry.coordinates);
  ```
</CodeGroup>

Le `citycode` retourné est le code INSEE exploitable directement dans les filtres `location` Fluximmo.

## Liens utiles

* [Concept · Recherche géographique](/concepts/recherche-geographique)
* [Géocodage inverse (coordonnées → adresse)](/api-geocoding-reference/reverse/recherche-par-géocodage-inverse)
* Playbook · *Géocoder pour Search* (à venir Phase 4)

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


## OpenAPI

````yaml get /search
openapi: 3.1.1
info:
  title: Service de géocodage
  description: API du service de géocodage 2.0 de l'IGN.
  contact:
    email: contact.geoservices@ign.fr
  version: 2.0.0
  license:
    name: Licence ouverte 2.0
    url: https://www.etalab.gouv.fr/licence-ouverte-open-licence
servers:
  - url: https://geo.fluximmo.io
security: []
tags:
  - name: getCapabilities
    description: Découverte du service
  - name: search
    description: Géocodage direct (recherche)
  - name: reverse
    description: Géocodage inverse
  - name: batch
    description: Géocodage par lot synchrone
  - name: batch-async
    description: Géocodage par lot asynchrone
paths:
  /search:
    get:
      tags:
        - search
      summary: Recherche par géocodage direct
      operationId: search
      parameters:
        - name: q
          in: query
          description: >
            chaîne décrivant la localisation à rechercher


            Exemples de requêtes:

            - /search?q=73 Avenue de Paris Saint-Mandé

            - /search?q=cimetière Vincennes

            - /search?q=75056104AE0003


            Note:

            L'absence de valeur est autorisée sur le type parcel pour réaliser
            une recherche structurée.

            Par exemple:
            /search?q=&index=parcel&departmentcode=75&municipalitycode=056&section=AV
          required: false
          schema:
            type: string
        - name: autocomplete
          in: query
          description: >
            indique si la recherche doit être effectuée en mode auto-complétion
            (comportement par défaut).
          schema:
            type: string
            enum:
              - '1'
              - '0'
            default: '1'
        - name: index
          in: query
          description: >
            index(es) de recherche :

            - <b>address</b> pour la recherche par adresse

            - <b>parcel</b> pour la recherche par parcelle cadastrale

            - <b>poi</b> pour la recherche par lieu et unité administrative


            Il est possible de spécifier plusieurs indexes séparés par une
            virgule.


            Exemples:

            - /search?index=parcel

            - /search?index=poi,address
          required: false
          schema:
            $ref: '#/components/schemas/Index'
        - name: limit
          in: query
          description: >
            Nombre maximum de résultats retournés.

            La valeur ne peut pas dépasser 50.

            Dans le cas où returntruegeometry est activé, la valeur est
            automatiquement ramenée à 20.
          schema:
            type: integer
            default: 10
        - name: lat
          in: query
          description: >-
            latitude d'un localisant pour favoriser les candidats les plus
            proches.
          schema:
            type: number
        - name: lon
          in: query
          description: >-
            longitude d'un localisant pour favoriser les candidats les plus
            proches.
          schema:
            type: number
        - name: returntruegeometry
          in: query
          description: indique si la vraie géométrie doit être retournée
          schema:
            type: boolean
            default: false
        - name: postcode
          in: query
          description: >-
            Filtre pour les index address et poi. Il permet de filtrer les
            résultats par code postal.
          schema:
            $ref: '#/components/schemas/PostalCode'
        - name: citycode
          in: query
          description: >-
            Filtre pour les index address et poi. Il permet de filtrer les
            résultats par code INSEE.
          schema:
            $ref: '#/components/schemas/InseeCode'
        - name: type
          in: query
          description: >-
            Filtre pour l'index address. Il permet de filtrer par type de
            données adresse : numéro de maison, rue, commune, ...
          schema:
            type: string
            enum:
              - housenumber
              - street
              - locality
              - municipality
        - name: city
          in: query
          description: >-
            Filtre pour les index address et poi. Il permet de filtrer par nom
            de commune.
          schema:
            type: string
        - name: category
          in: query
          description: >
            Filtre pour l'index poi. Il permet de filtrer par catégorie de poi.

            Les valeurs possibles sont listées dans le getCapabilities du
            service de géocodage.
          schema:
            type: string
        - name: departmentcode
          in: query
          description: >-
            Filtre pour l'index parcel. Il permet de filtrer par code de
            département.
          schema:
            type: string
        - name: municipalitycode
          in: query
          description: >-
            Filtre pour l'index parcel. Il permet de filtrer par code de
            commune.
          schema:
            type: string
        - name: oldmunicipalitycode
          in: query
          description: >-
            Filtre pour l'index parcel. Il permet de filtrer par code d'ancienne
            commune.
          schema:
            type: string
        - name: districtcode
          in: query
          description: >-
            Filtre pour l'index parcel. Il permet de filtrer par code
            d'arrondissement.
          schema:
            type: string
        - name: section
          in: query
          description: Filtre pour l'index parcel. Il permet de filtrer par section.
          schema:
            type: string
        - name: number
          in: query
          description: Filtre pour l'index parcel. Il permet de filtrer par numéro.
          schema:
            type: string
        - name: sheet
          in: query
          description: Filtre pour l'index parcel. Il permet de filtrer par feuille.
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      $ref: '#/components/schemas/GeocodeResponse'
        '400':
          description: Parse query failed
          content:
            application/json: {}
components:
  schemas:
    Index:
      type: string
      enum:
        - address
        - poi
        - parcel
      default: address
    PostalCode:
      maxLength: 5
      minLength: 5
      type: string
      description: Code postal
    InseeCode:
      maxLength: 5
      minLength: 2
      type: string
      description: Code INSEE
    GeocodeResponse:
      type: object
      oneOf:
        - $ref: '#/components/schemas/Address'
        - $ref: '#/components/schemas/Poi'
        - $ref: '#/components/schemas/Parcel'
    Address:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: '#/components/schemas/AddressProperties'
        geometry:
          $ref: '#/components/schemas/GeometryPoint'
    Poi:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: '#/components/schemas/PoiProperties'
        geometry:
          $ref: '#/components/schemas/GeometryPoint'
    Parcel:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: '#/components/schemas/ParcelProperties'
        geometry:
          $ref: '#/components/schemas/GeometryPoint'
    AddressProperties:
      type: object
      properties:
        label:
          type: string
          description: Libellé complet de l'adresse
        id:
          type: string
        postcode:
          $ref: '#/components/schemas/PostalCode'
        city:
          type: string
          description: Commune de l'adresse
        district:
          type: string
          description: Arrondissement de l'adresse
        street:
          type: string
          description: Rue de l'adresse
        housenumber:
          type: string
        citycode:
          $ref: '#/components/schemas/InseeCode'
        x:
          type: number
          description: Longitude de l'adresse
        'y':
          type: number
          description: Latitude de l'adresse
        score:
          type: number
        _score:
          type: number
        name:
          type: string
        type:
          type: string
          enum:
            - housenumber
            - street
            - locality
            - municipality
        _type:
          type: string
          enum:
            - address
          description: Rétro-compatibilité
        context:
          type: string
        importance:
          type: number
      example:
        label: 10 Rue Nationale 75013 Paris 13e Arrondissement
        id: test-id
        postcode: '75013'
        city: Paris
        district: Paris 13e Arrondissement
        street: Rue Nationale
        housenumber: '10'
        citycode: '75113'
        x: 2.369063
        'y': 48.822409
        score: 0.6515151515151515
        _score: 0.6515151515151515
        name: 10 Rue Nationale
        type: housenumber
        _type: address
        contexte: 75, Paris
        importance: '0.6'
    GeometryPoint:
      type: object
      properties:
        type:
          type: string
          enum:
            - Point
        coordinates:
          type: array
          items:
            type: number
      example:
        type: Point
        coordinates:
          - 2.03648539635326
          - 44.3492508045369
    PoiProperties:
      type: object
      properties:
        toponym:
          type: string
          description: Libellé du toponyme
        postcode:
          type: array
          items:
            $ref: '#/components/schemas/PostalCode'
        citycode:
          type: array
          items:
            $ref: '#/components/schemas/InseeCode'
        city:
          type: array
          items:
            type: string
        category:
          $ref: '#/components/schemas/PoiType'
        extrafields:
          type: object
        truegeometry:
          $ref: '#/components/schemas/Geometry'
        _score:
          type: number
        _type:
          type: string
          enum:
            - poi
      example:
        toponym: Pont National
        postcode:
          - 77310
          - 91100
        citycode:
          - 77
          - 77300
          - 91
          - 91450
        city:
          - Saint-Fargeau-Ponthierry
          - Corbeil-Essonnes
        category:
          - construction linéaire
        extrafields:
          names:
            - pont strasbourg
            - pont national
          cleabs: CONSLINE0000000060494180
        truegeometry:
          coordinates:
            - - 2.03666899913969
              - 44.3490469250535
              - 257
            - - 2.03646952056093
              - 44.3492684335352
              - 256.3
            - - 2.03644906780383
              - 44.3492907599887
              - 256.3
            - - 2.03630075804051
              - 44.3494542018237
              - 256.3
          type: LineString
        _score: 0.5757575757575758
        _type: poi
    ParcelProperties:
      type: object
      properties:
        id:
          type: string
          description: Identifiant de la parcelle
        departmentcode:
          type: string
          description: Code du département
        municipalitycode:
          type: string
          description: Code de la commune
        city:
          type: string
          description: Nom de la commune
        oldmunicipalitycode:
          type: string
          description: Code de l'ancienne commune
        districtcode:
          type: string
          description: Code insee de l'arrondissement
        section:
          type: string
          description: Section cadastrale
        number:
          type: string
          description: Numéro cadastral
        sheet:
          type: string
          description: Feuille cadastrale
        truegeometry:
          $ref: '#/components/schemas/GeometryPolygon'
        _score:
          type: number
        _type:
          type: string
          enum:
            - parcel
      example:
        id: 75056104AV0133
        departmentcode: '75'
        municipalitycode: '056'
        city: Paris
        oldmunicipalitycode: '000'
        districtcode: '104'
        section: AV
        number: '133'
        sheet: 1
        truegeometry:
          type: Polygon
          coordinates:
            - - - 2.35457222187139
                - 48.8523027661354
              - - 2.35463049659443
                - 48.8523731401755
              - - 2.35465580843827
                - 48.8523650925735
              - - 2.35464724014948
                - 48.8522756505323
              - - 2.35457222187139
                - 48.8523027661354
        _score: 1
        _type: parcel
    PoiType:
      type: array
      items:
        type: string
    Geometry:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/GeometryType'
        coordinates:
          type: array
          items:
            type: number
      example:
        type: Point
        coordinates:
          - 2.03648539635326
          - 44.3492508045369
    GeometryPolygon:
      type: object
      properties:
        type:
          type: string
          enum:
            - Polygon
        coordinates:
          type: array
          items:
            type: number
      example:
        type: Polygon
        coordinates:
          - - - 2.35457222187139
              - 48.8523027661354
            - - 2.35463049659443
              - 48.8523731401755
            - - 2.35465580843827
              - 48.8523650925735
            - - 2.35464724014948
              - 48.8522756505323
            - - 2.35457222187139
              - 48.8523027661354
    GeometryType:
      type: string
      enum:
        - Point
        - MultiPolygon
        - LineString

````