Aller au contenu principal

Rechercher des adresses

Le géocodage permet de convertir une adresse textuelle en coordonnées GPS. Ce guide vous explique comment utiliser l'endpoint de recherche d'adresses.

Vue d'ensemble​

L'endpoint /geocoder/search utilise un algorithme de recherche par similarité pour trouver les adresses correspondant le mieux à votre requête, même si elle est approximative.

Fonctionnalités principales​

  • ✅ Recherche textuelle flexible
  • ✅ Algorithme de similarité fuzzy
  • ✅ Recherche sur toute la France
  • ✅ Support des adresses partielles
  • ✅ Retour des coordonnées GPS
  • ✅ Références cadastrales associées

Recherche basique​

Adresse complète​

curl -X GET \
  "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=7+Rue+de+l%27Elysée+75008+Paris" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Adresse partielle​

L'API accepte des adresses incomplètes :

# Sans code postal
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Rue+de+l%27Elysée+Paris" \
  -H "Authorization: Bearer VOTRE_CLE_API"

# Seulement le nom et la ville
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Tour+Eiffel+Paris" \
  -H "Authorization: Bearer VOTRE_CLE_API"

# Lieu-dit ou monument
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Château+de+Versailles" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Score de similarité​

Chaque résultat inclut un score de similarité entre 0 et 1 :

  • 1.0 : Correspondance exacte
  • 0.8 - 0.99 : Très bonne correspondance
  • 0.6 - 0.79 : Bonne correspondance
  • < 0.6 : Correspondance faible
{
  "adresse_complete": "7 Rue de l'Elysée 75008 Paris",
  "similarite": 0.95
}

Filtrer par score​

curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Elysée+Paris" \
  -H "Authorization: Bearer VOTRE_CLE_API"

# Filtrer ensuite avec jq (outil ligne de commande pour JSON)
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=Elysée+Paris" \
  -H "Authorization: Bearer VOTRE_CLE_API" | jq '.[] | select(.similarite > 0.8)'

Limiter le nombre de résultats​

Par défaut, l'API retourne 10 résultats. Vous pouvez ajuster ce nombre :

# Un seul résultat (le meilleur)
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=1+Rue+de+Rivoli&limite=1" \
  -H "Authorization: Bearer VOTRE_CLE_API"

# 20 résultats
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=1+Rue+de+Rivoli&limite=20" \
  -H "Authorization: Bearer VOTRE_CLE_API"

# Maximum : 50 résultats
curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=1+Rue+de+Rivoli&limite=50" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Sélectionner les champs​

Optimisez la réponse en ne demandant que les champs nécessaires :

curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=1+Rue+de+Rivoli&champs=identifiant_ban,adresse_complete,centre" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Champs disponibles​

ChampTypeDescription
identifiant_banstringIdentifiant unique BAN
adresse_completestringAdresse formatée
numerostringNuméro de voie
nom_voiestringNom de la voie
municipalitestringCommune
parcellesarrayRéférences cadastrales
centreobjectCoordonnées GPS (Point GeoJSON)
similaritenumberScore de correspondance (0-1)

Format GeoJSON​

Pour une intégration directe dans une carte :

curl "https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=1+Rue+de+Rivoli&format=geojson" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Résultat attendu :

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.3364, 48.8606]
      },
      "properties": {
        "identifiant_ban": "75056_7560_00001",
        "adresse_complete": "1 Rue de Rivoli 75001 Paris"
      }
    }
  ]
}

Cas d'usage avancés​

1. Autocomplétion d'adresses​

import { useState, useEffect } from 'react';

function AddressAutocomplete() {
  const apiKey = process.env.INFOPARCELLE_API_KEY;
  const [query, setQuery] = useState('');
  const [suggestions, setSuggestions] = useState([]);

  useEffect(() => {
    if (query.length < 3) {
      setSuggestions([]);
      return;
    }

    const timeoutId = setTimeout(async () => {
      const response = await fetch(
        `https://app.infoparcelle.fr/api/v1/geocoder/search?` +
        new URLSearchParams({
          recherche: query,
          limite: '10',
          champs: 'identifiant_ban,adresse_complete,centre',
        }),
        {
          headers: { 'Authorization': `Bearer ${apiKey}` }
        }
      );

      const results = await response.json();
      setSuggestions(results);
    }, 300); // Debounce de 300ms

    return () => clearTimeout(timeoutId);
  }, [query]);

  return (
    <div>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Rechercher une adresse..."
      />

      {suggestions.length > 0 && (
        <ul>
          {suggestions.map((adresse) => (
            <li key={adresse.identifiant_ban}>
              {adresse.adresse_complete}
              <span>Score: {Math.round(adresse.similarite * 100)}%</span>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

2. Validation d'adresse​

async function validerAdresse(adresseSaisie) {
  /**
   * Valide une adresse saisie par l'utilisateur
   * Retourne l'adresse normalisée ou null si invalide
   */
  const apiKey = process.env.INFOPARCELLE_API_KEY;

  const response = await fetch(
    'https://app.infoparcelle.fr/api/v1/geocoder/search?' +
    new URLSearchParams({
      recherche: adresseSaisie,
      limite: '1',
    }),
    {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }
  );

  const adresses = await response.json();

  if (!adresses || adresses.length === 0) {
    return null;
  }

  const adresse = adresses[0];

  // Vérifier le score de similarité
  if (adresse.similarite < 0.8) {
    console.warn(`⚠️  Attention: correspondance faible (${Math.round(adresse.similarite * 100)}%)`);
    return null;
  }

  return {
    adresse_complete: adresse.adresse_complete,
    latitude: adresse.centre.coordinates[1],
    longitude: adresse.centre.coordinates[0],
  };
}

// Utilisation
const adresseValidee = await validerAdresse("7 Rue de l'Elysée Paris");

if (adresseValidee) {
  console.log(`✅ Adresse validée: ${adresseValidee.adresse_complete}`);
} else {
  console.log("❌ Adresse invalide");
}

3. Recherche de proximité avec autocomplétion​

async function rechercherAvecProximite(query, userLat, userLon) {
  const apiKey = process.env.INFOPARCELLE_API_KEY;

  // 1. Rechercher les adresses
  const response = await fetch(
    `https://app.infoparcelle.fr/api/v1/geocoder/search?recherche=${encodeURIComponent(query)}&limite=20`,
    {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }
  );

  const adresses = await response.json();

  // 2. Calculer la distance pour chaque adresse
  const adressesAvecDistance = adresses.map(adresse => {
    const coords = adresse.centre.coordinates;
    const distance = calculerDistance(
      userLat, userLon,
      coords[1], coords[0]
    );

    return { ...adresse, distance };
  });

  // 3. Trier par distance
  adressesAvecDistance.sort((a, b) => a.distance - b.distance);

  return adressesAvecDistance;
}

function calculerDistance(lat1, lon1, lat2, lon2) {
  // Formule de Haversine
  const R = 6371; // Rayon de la Terre en km
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLon = (lon2 - lon1) * Math.PI / 180;

  const a =
    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
    Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
    Math.sin(dLon / 2) * Math.sin(dLon / 2);

  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
  return R * c;
}

Bonnes pratiques​

✅ À faire​

  1. Implémenter un debounce pour l'autocomplétion (300-500ms)
  2. Vérifier le score de similarité (>0.8 recommandé)
  3. Limiter le nombre de résultats (10-20 pour une UI)
  4. Utiliser champs pour optimiser la bande passante
  5. Gérer les erreurs (adresse non trouvée, timeout)
  6. Cacher les résultats pour les recherches fréquentes

❌ À éviter​

  1. ❌ Requête à chaque frappe sans debounce
  2. ❌ Accepter des scores de similarité < 0.6
  3. ❌ Demander trop de résultats (>50)
  4. ❌ Ne pas gérer les cas sans résultat
  5. ❌ Ignorer les erreurs de timeout
  6. ❌ Requêtes synchrones bloquantes

Limites​

  • Minimum 3 caractères pour déclencher une recherche
  • France uniquement (métropole + DOM)
  • Pas de recherche par coordonnées (utilisez le géocodage inverse)
  • Pas de regex dans la recherche

Performances​

  • Temps de réponse moyen : < 100ms
  • Cache côté serveur : 15 minutes
  • Rate limit : 1200 requêtes/minute

Voir aussi​