Recherche d'adresses

GET

Rechercher des adresses françaises par texte libre avec algorithme de similarité.

Endpoint

GET /api/v1/geocoder/search

Authentification

Authentification requise

Cet endpoint nécessite une clé API valide dans le header Authorization.

Authorization: Bearer VOTRE_CLE_API

Paramètres de requête

Paramètre	Type	Requis	Description	Exemple
recherche	string	✅ Oui	Terme de recherche (min. 3 caractères)	7 Rue de l'Elysée Paris
champs	array	❌ Non	Champs à retourner (séparés par virgules)	identifiant_ban,adresse_complete,centre
champ_tri	string	❌ Non	Champ de tri	similarite (défaut)
ordre_tri	string	❌ Non	Direction du tri (asc, desc)	desc (défaut)
format	string	❌ Non	Format de sortie (json, geojson)	json (défaut)
limite	integer	❌ Non	Nombre de résultats (1-50)	10 (défaut)
curseur	string	❌ Non	Curseur de pagination	-

Champs disponibles

• identifiant_ban : Identifiant unique BAN
• adresse_complete : Adresse formatée complète
• numero : Numéro de voie
• nom_voie : Nom de la voie
• municipalite : Nom de la commune
• parcelles : Liste des parcelles cadastrales
• centre : Point GPS (GeoJSON Point)
• similarite : Score de similarité (0-1)

Réponse

Code de succès

• 200 OK : Requête réussie

Format JSON

[
  {
    "identifiant_ban": "75108_9575_00007",
    "adresse_complete": "7 Rue de l'Elysée 75008 Paris 8e Arrondissement",
    "numero": "7",
    "nom_voie": "Rue de l'Elysée",
    "municipalite": "Paris 8e Arrondissement",
    "parcelles": ["75108000AA0001", "75108000AA0002"],
    "centre": {
      "type": "Point",
      "coordinates": [2.316667, 48.870556]
    },
    "similarite": 0.95
  }
]

Format GeoJSON

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.316667, 48.870556]
      },
      "properties": {
        "identifiant_ban": "75108_9575_00007",
        "adresse_complete": "7 Rue de l'Elysée 75008 Paris 8e Arrondissement",
        "numero": "7",
        "nom_voie": "Rue de l'Elysée",
        "municipalite": "Paris 8e Arrondissement",
        "parcelles": ["75108000AA0001", "75108000AA0002"],
        "similarite": 0.95
      }
    }
  ]
}

Headers de pagination

X-Pagination-Limit: 10
X-Pagination-Cursor: eyJpZCI6MTIzfQ==
X-Pagination-Next-Cursor: eyJpZCI6MTMzfQ==
X-Pagination-Has-More: true

Exemples de requêtes

Exemple 1 : Recherche simple

cURL

curl -X GET "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Tour+Eiffel+Paris&limite=5" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Accept: application/json"

PHP

<?php
$apiKey = getenv('INFOPARCELLE_API_KEY');

$url = 'https://app.infoparcelle.fr/api/v1/geocoder/search';
$params = http_build_query([
    'recherche' => 'Tour Eiffel Paris',
    'limite' => 5,
]);

$ch = curl_init($url . '?' . $params);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$adresses = json_decode($response, true);
curl_close($ch);

foreach ($adresses as $adresse) {
    echo $adresse['adresse_complete'] . "\n";
}

JavaScript

const apiKey = process.env.INFOPARCELLE_API_KEY;

const response = await fetch(
  'https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Tour+Eiffel+Paris&limite=5',
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Accept': 'application/json',
    },
  }
);

const adresses = await response.json();

adresses.forEach(adresse => {
  console.log(adresse.adresse_complete);
});

Python

import os
import requests

api_key = os.getenv('INFOPARCELLE_API_KEY')

response = requests.get(
    'https://app.infoparcelle.fr/api/v1/geocoder/search',
    params={
        'recherche': 'Tour Eiffel Paris',
        'limite': 5,
    },
    headers={
        'Authorization': f'Bearer {api_key}',
        'Accept': 'application/json',
    }
)

adresses = response.json()

for adresse in adresses:
    print(adresse['adresse_complete'])

Exemple 2 : Recherche avec champs personnalisés

curl -X GET "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Louvre&champs=identifiant_ban,adresse_complete,centre,similarite&limite=3" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Exemple 3 : Format GeoJSON pour cartographie

curl -X GET "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Opéra+Garnier&format=geojson" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Testeur interactif

Testez cet endpoint directement depuis votre navigateur :

GET/api/v1/geocoder/search

Clé API

recherche

limite

Cas d'usage

1. Autocomplétion d'adresses

// Fonction debounced pour autocomplétion
let timeoutId;

function autocompleteAddress(input) {
  clearTimeout(timeoutId);

  timeoutId = setTimeout(async () => {
    if (input.length < 3) return;

    const results = await fetch(
      `https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=${encodeURIComponent(input)}&limite=10`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    ).then(r => r.json());

    displaySuggestions(results);
  }, 300);
}

2. Validation d'adresse

// Vérifier qu'une adresse existe
$response = file_get_contents(
    'https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=' . urlencode($userInput) . '&limite=1',
    false,
    stream_context_create([
        'http' => [
            'header' => "Authorization: Bearer $apiKey"
        ]
    ])
);

$adresses = json_decode($response, true);

if (empty($adresses)) {
    throw new Exception('Adresse introuvable');
}

$adresseValidee = $adresses[0];
if ($adresseValidee['similarite'] < 0.8) {
    echo "Attention: correspondance approximative\n";
}

3. Géolocalisation pour carte

// Centrer une carte sur une adresse
async function centerMapOnAddress(address) {
  const response = await fetch(
    `https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=${encodeURIComponent(address)}&limite=1&format=geojson`,
    {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }
  );

  const geojson = await response.json();

  if (geojson.features.length === 0) {
    console.error('Adresse non trouvée');
    return;
  }

  const coords = geojson.features[0].geometry.coordinates;
  map.setView([coords[1], coords[0]], 15);
}

Codes d'erreur

Code	Description	Solution
400	Paramètre recherche manquant ou invalide	Fournissez au moins 3 caractères
401	Token d'authentification invalide	Vérifiez votre clé API
429	Trop de requêtes	Respectez la limite de 1200 req/min
434	Quota dépassé	Passez à un plan supérieur

Voir la gestion des erreurs →

Bonnes pratiques

Optimisations

1. Utilisez le paramètre champs pour ne récupérer que les données nécessaires
2. Limitez le nombre de résultats (10-20 max pour une UI)
3. Implémentez un debounce pour l'autocomplétion (300-500ms)
4. Cachez les résultats si vous recherchez souvent les mêmes adresses
5. Gérez les adresses approximatives en vérifiant le score de similarité (>0.8 recommandé)

Limites

• Minimum 3 caractères pour le terme de recherche
• Maximum 50 résultats par page
• France métropolitaine et DOM uniquement
• Recherche textuelle : pas de regex ou caractères spéciaux complexes

Voir aussi

• Guide géocodage - Guide complet avec exemples
• Gestion des erreurs - Gérer les erreurs API
• Rate Limits - Limites de débit