API et données d’indicatifs téléphoniques
Indicatifs.com fournit des fichiers statiques lisibles sans compte, conçus pour identifier un indicatif, documenter un plan de numérotation ou alimenter un outil interne.
Trois modes d’accès
| Besoin | Ressource | Réponse |
|---|---|---|
| Identifier un code | /api/lookup/?code=212 | Objet JSON ciblé |
| Charger la base complète | indicatifs-pays.json | Pays, formats et métadonnées |
| Analyser dans un tableur | indicatifs-pays.csv | Export tabulaire UTF-8 |
Pour un besoin interactif, utilisez le lookup JSON. Pour normaliser une saisie, lisez le contrat de formatage. Les intégrations frontales peuvent partir du widget documenté.
Champs et périmètre
Chaque fiche pays contient notamment le nom français, le code ISO, l’indicatif E.164, le préfixe de sortie, le préfixe national, les longueurs possibles, des exemples de présentation et l’URL canonique de la fiche éditoriale. Les codes partagés ou spéciaux renvoient vers une page de désambiguïsation plutôt que vers un pays choisi arbitrairement.
Les exemples servent au formatage. Ils ne prouvent pas qu’un numéro existe, qu’il est attribué ou qu’il appartient à une personne donnée.
Version, sources et réutilisation
La version et la date de vérification sont incluses dans les fichiers. L’attribution des indicatifs s’appuie prioritairement sur l’UIT E.164 ; les formats sont rapprochés de métadonnées de numérotation documentées. Une application critique doit conserver sa propre gestion d’erreur et vérifier les changements auprès de l’autorité compétente.
Les exports sont proposés comme données de référence avec leurs limites. Consultez la présentation des données, les sources détaillées et le journal des mises à jour avant une intégration en production.
Exemple minimal
fetch('/api/lookup/?code=212')
.then(response => response.json())
.then(data => console.log(data.canonical));Le serveur renvoie un fichier JSON statique lorsqu’un code connu est fourni. Sans paramètre, la page de documentation reste accessible.
Bonnes pratiques d’intégration
Préférez les URL de données aux pages HTML lorsque votre application attend du JSON. Contrôlez le code HTTP, le type de contenu et la présence des champs indispensables avant d’enregistrer une réponse. Une indisponibilité temporaire ne doit jamais être interprétée comme l’absence définitive d’un indicatif.
Conservez localement la version du jeu utilisée pour produire un résultat. Lors d’une mise à jour, comparez les codes, les URL canoniques et les dates plutôt que l’ordre des lignes. Cette stratégie permet d’expliquer pourquoi une réponse a changé.
Quel fichier choisir ?
- Lookup : interface ou vérification occasionnelle.
- JSON complet : moteur local, site ou application.
- CSV : contrôle humain, rapprochement et tableur.
Les fichiers sont en UTF-8. Un cache raisonnable réduit les requêtes, mais il doit pouvoir être invalidé lorsqu’une nouvelle version est publiée.
Contrat de données minimal
Journalisez la requête normalisée, la version du jeu et l’URL canonique. Ne dépendez pas de l’ordre des objets et ne convertissez pas une liste de destinations en réponse unique.
if (!response.ok) throw new Error('indicatif inconnu');
if (!data.canonical || !Array.isArray(data.results)) throw new Error('réponse incomplète');Le lookup reçoit un code international numérique comme 33, 212 ou 800. Il ne résout pas une zone régionale comme 1-212 : utilisez la fiche éditoriale correspondante.
Échecs à prévoir dans une intégration
Une intégration doit distinguer requête invalide, code inconnu, code partagé et version de jeu dépassée. Conservez la clé demandée et l’URL canonique afin de reproduire la réponse.
N’utilisez jamais le premier élément d’un tableau comme destination implicite.
Stabilité et cache
Les fichiers sont statiques afin de rester prévisibles et faciles à mettre en cache. L’intégrateur doit toutefois prévoir une invalidation lors d’un changement de version. Une ancienne réponse peut rester techniquement lisible tout en portant un statut devenu obsolète, comme l’a montré +888.
Ressources complémentaires
Sources complémentaires : Métadonnées techniques libphonenumber. Ces références sont utilisées selon leur périmètre respectif.
Référence officielle : liste officielle UIT des indicatifs E.164, pour l’attribution des codes internationaux. Consultation éditoriale : 26 août 2026.
Choisir entre endpoint et export complet
Le lookup convient à une recherche ponctuelle ; les fichiers JSON ou CSV sont préférables pour un traitement en série. Ce choix réduit les appels inutiles et permet d’enregistrer la version exacte du jeu utilisée lors d’un calcul.
| Usage | Ressource | Contrôle à conserver |
|---|---|---|
| Résoudre un code saisi | Lookup | Requête, résultat complet et URL canonique |
| Alimenter une liste interne | Export JSON | Version et date de vérification |
| Analyse tabulaire | Export CSV | Encodage, colonnes et nombre de lignes |
Une application cliente ne doit jamais prendre automatiquement le premier pays d’un code partagé. Elle doit afficher l’ambiguïté ou demander les chiffres suivants.