Comment fonctionne une API de code postal sur le plan technique ? [Guide complet]

Une API de code postal semble simple : vous envoyez un code postal et un numéro de rue, et vous récupérez une adresse. Mais il y a beaucoup de technique derrière tout cela. Ce guide explique tout : de la base de données sous-jacente à la bonne gestion des erreurs.

Qu'est-ce qu'une API de code postal ?

Une API de code postal est un service web qui convertit un code postal (et éventuellement un numéro de rue) en une adresse complète et structurée. Le résultat contient généralement le nom de la rue, le numéro de rue, la ville, la commune, la province et les coordonnées GPS.

Comment fonctionne techniquement une recherche d'adresse ?

1. Entrée

L'appel contient au minimum :

• postalcode — le code postal (par ex. 1092CX)
• number — le numéro de rue (par ex. 12)
• Optionnel : numberAddition — complément du numéro de rue (par ex. A)

2. Recherche dans la base de données

L'API effectue une recherche dans une copie actualisée de la Basisregistratie Adressen en Gebouwen (BAG), le registre officiel néerlandais des adresses. Cette base de données contient toutes les adresses officiellement enregistrées aux Pays-Bas et est mise à jour mensuellement par les autorités publiques.

3. Réponse

{
  "street": "Linnaeusstraat",
  "number": 12,
  "numberAddition": "",
  "postalcode": "1092CX",
  "city": "Amsterdam",
  "municipality": "Amsterdam",
  "province": "Noord-Holland",
  "streetShort": "Linnaeusstraat",
  "location": {
    "coordinates": {
      "latitude": 52.3586,
      "longitude": 4.9254
    }
  }
}

Différents types de requêtes API

Rapidité et fiabilité

Une bonne API de code postal répond aux requêtes en moins de 300 millisecondes. ApiCheck atteint en moyenne moins de 100 ms. C'est suffisamment rapide pour une utilisation en direct dans des formulaires, sans latence perceptible pour l'utilisateur.

Pour des volumes plus élevés, vous pouvez mettre les réponses en cache. Attention : les adresses sont mises à jour mensuellement dans la BAG. Une durée de vie de cache de 7 à 30 jours convient dans la plupart des cas.

Gestion des erreurs

Une intégration robuste tient compte des scénarios d'erreur :

• 404 Not Found : le code postal + numéro de rue n'existe pas. Affichez un message à l'utilisateur.
• 422 Unprocessable : entrée invalide (par ex. format de code postal incorrect).
• 429 Too Many Requests : vous avez atteint votre limite de requêtes.
• 503 Service Unavailable : panne temporaire. Implémentez une logique de nouvelle tentative avec backoff exponentiel.

Exemple d'implémentation en PHP

$response = Http::withHeaders([
    'X-Api-Key' => config('services.apicheck.key'),
])->get('https://api.apicheck.nl/lookup/v1/address/nl', [
    'postalcode' => '1092CX',
    'number' => 12,
]);

if ($response->ok()) {
    $address = $response->json();
    echo $address['street']; // Linnaeusstraat
}

Exemple d'implémentation en JavaScript

const response = await fetch(
  '/api/validate/address?postalcode=1092CX&number=12'
);
const address = await response.json();
document.getElementById('street').value = address.street;
document.getElementById('city').value = address.city;

Sécurité

Ne jamais appeler l'API directement depuis le navigateur avec votre véritable clé API visible dans le code JavaScript. Utilisez toujours un proxy côté serveur qui :

1. Accepte l'appel depuis le navigateur
2. Ajoute votre véritable clé API côté serveur
3. Renvoie la réponse au navigateur

La propre démo d'ApiCheck fonctionne aussi de cette manière : voir routes/api.php pour un exemple.

Erreurs fréquentes

1. Clé API dans le JavaScript front-end — à ne jamais faire
2. Aucun repli en cas de 404 — l'utilisateur est bloqué si l'adresse n'existe pas
3. Cache conservé trop longtemps — les adresses changent parfois lors d'un renumérotage
4. Aucune limitation de débit — certains utilisateurs spamment les formulaires

Conclusion

Une API de code postal est conceptuellement simple mais nécessite une implémentation soignée pour un usage en production. Avec un proxy côté serveur, une gestion des erreurs correcte et une mise en cache intelligente, vous construisez une intégration robuste qui durera des années.