---
title: "Résoudre une adresse ou un point"
method: GET
path: "/adresses/recherche"
---

# Résoudre une adresse ou un point

`GET /adresses/recherche`

## Request

- Base URL: `https://pillr.fr/api/v1`
- URL: `https://pillr.fr/api/v1/adresses/recherche`
- Auth: HTTP bearer

Géocodage par la Base Adresse Nationale d'une adresse en texte (avec son code postal pour départager) ou d'un point (géocodage inverse, du plus proche au plus lointain). Chaque candidat porte sa clé BAN, son numéro, sa voie, sa commune et son ancienne commune, sa position, son score ou sa distance, et pour un numéro le type de position, les parcelles cadastrales et la certification lus dans la copie de la BAN de Pillr. La clé BAN d'un numéro sert aux autres opérations du domaine. Coût : 0 crédit par appel réussi.

## Query parameters

- `q` string: Adresse en texte (recherche).
- `code_postal` string: Code postal, pour départager une adresse homonyme (avec q).
- `limite` integer: Nombre de candidats rendus.

## Response `200`

Réponse servie et débitée (sauf réponse identique déjà servie dans les 24 h).

- object
  - `mode` 'recherche' | 'inverse', required
  - `candidats` object[], required
    - `cle_ban` string, nullable, required: Clé BAN du candidat : celle d'un numéro (adresse servie par les autres opérations), d'une voie ou d'un lieu-dit.
    - `libelle` string, required
    - `type` 'numero' | 'voie' | 'lieu_dit' | 'commune', required: Ce que désigne le candidat : un numéro, une voie, un lieu-dit ou une commune.
    - `numero` string, nullable, required
    - `suffixe` string, nullable, required: Indice de répétition (bis, ter, A...), en minuscules.
    - `voie` string, nullable, required
    - `code_postal` string, nullable, required
    - `insee` string, nullable, required
    - `commune` string, nullable, required
    - `ancienne_commune` object, nullable, required: Commune déléguée ou fusionnée, quand l'adresse en porte une.
      - `insee` string, nullable, required
      - `nom` string, nullable, required
    - `lat` number, required
    - `lon` number, required
    - `type_position` string, nullable, required: Type de position de la BAN (entrée, bâtiment, délivrance postale, parcelle, segment...) ; null si non lu.
    - `parcelles` string[], nullable, required: Parcelles cadastrales (14 caractères) rattachées au numéro par la BAN ; vide quand la BAN n'en donne pas (environ une adresse sur deux) ; null quand la base n'a pas été lue.
    - `score` number, nullable, required: Score de la recherche, de 0 à 1 (recherche en texte).
    - `distance_m` number, nullable, required: Distance au point demandé, en mètres (géocodage inverse).
    - `certification` boolean, nullable, required: Vrai si la commune a certifié l'adresse dans la BAN.
  - `credits` object, required: Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).
    - `debites` integer, required
    - `restants` integer, nullable, required

## Other responses

- `304`: Non modifiée depuis l'ETag fourni : rien n'est débité.
- `400`: Paramètres invalides
- `401`: Clé d'API absente
- `402`: Crédits insuffisants ; Carte requise ; Plafond mensuel de dépense atteint
- `403`: Portée insuffisante
- `404`: Ressource absente : rien n'est débité
- `429`: Trop de requêtes par minute
- `500`: Erreur interne
- `503`: API indisponible ; Donnée momentanément indisponible

---

[API](https://skmtc.dev/pillr/apis/api-pillr.md) · [All operations](https://skmtc.dev/pillr/apis/api-pillr/llms.txt) · [OpenAPI document](https://skmtc.dev/pillr/apis/api-pillr/revisions/218b2866bd6c?raw)