Phone number lookup
Sachez ce qu'est un numéro. Avant de lui envoyer quoi que ce soit.
Un POST, une réponse, aucune ressource à créer ou interroger. La recherche de base renvoie le pays du numéro, le réseau qui le dessert aujourd'hui, le réseau qui a attribué sa plage, un indicateur précisant s'il a changé de réseau, et le type de ligne. Cinq propriétés supplémentaires sont disponibles en les nommant.
const answer = await bird.lookup.phoneNumber({
phone_number: "+31612345678",
type: ["classification", "porting"],
});
console.log(answer.country_code, answer.line_type);
// → "NL" "mobile"
console.log(answer.network_info?.carrier_name);
// → "KPN"
console.log(answer.original_network_info?.carrier_name);
// → "Vodafone"
console.log(answer.flags);
// → ["ported"]
if (answer.porting?.status === "ok") {
console.log(answer.porting.ported, answer.porting.last_ported_at);
// → true "2021-04-18T00:00:00Z"
}
Deux réseaux, et l'écart entre eux.
Cet écart, c'est ce à quoi ressemble la portabilité dans une réponse.
Phone number lookup est l'une des deux opérations de l<hub>API Bird Lookup</hub>. Envoyez un numéro au format international, avec ou sans le plus initial, et vous obtenez en retour <code>country_code</code>, un bloc <code>network_info</code> pour lopérateur desservant le numéro aujourd'hui, et un bloc original_network_info pour l'opérateur auquel sa plage a été attribuée. Quand les deux diffèrent, le numéro a été porté, et flags l'indique. Les numéros uniquement nationaux sont rejetés plutôt que devinés, de sorte qu'une entrée invalide échoue clairement au lieu de renvoyer une réponse plausible sur le mauvais pays.
Ce qui est renvoyé, et quand.
Les trois premiers sont inclus dans chaque recherche. Les autres sont renvoyés quand vous les nommez dans type.
- 01
Pays et les deux opérateurs.
country_code est le pays ISO de la plage, et il est absent pour les numéros non géographiques plutôt que deviné. network_info et original_network_info contiennent chacun un nom d'opérateur ainsi que les codes pays mobile et réseau, ce qui est utile si vous routez sur MCC et MNC plutôt que sur un nom.
- 02
Type de ligne, à partir d'une liste fermée.
mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other ou unknown. La liste est fermée, donc un switch dessus reste exhaustif, et c'est le champ à vérifier avant de décider si un SMS est même possible.
- 03
L'indicateur de portabilité, sans coût supplémentaire.
flags contient ported lorsque le numéro a changé de réseau à un moment donné. Il est inclus dans la réponse de base, donc la simple question de savoir si un numéro a déjà été porté ne nécessite aucune propriété supplémentaire.
- 04
classification, un deuxième avis sur la ligne.
Une lecture plus fine provenant d'une source différente, avec des valeurs que line_type ne propose pas : fixed_line_or_mobile, shared_cost, national_rate, personal_number, isp, voice_mail, short_codes, et plus. Elle se place à côté de line_type dans la réponse au lieu de le remplacer, ce qui vous permet de comparer les deux quand un numéro semble inhabituel.
- 05
porting, avec dates et historique.
ported en booléen, last_ported_at en horodatage, last_ported_at_is_approximate quand le registre ne connaît que le mois, et history sous forme de liste d'événements de portabilité du plus ancien au plus récent. Chaque événement contient un code d'action spécifique au registre, qu'il vaut la peine d'afficher mais pas d'utiliser comme condition.
- 06
presence et roaming, depuis le réseau en temps réel.
presence interroge le réseau et renvoie reachable, ce qui se rapproche le plus de savoir si la ligne est allumée. roaming renvoie is_roaming ainsi que le MCC et le MNC du réseau visité, de sorte qu'une inscription depuis un numéro connecté à un réseau étranger est quelque chose que vous pouvez constater plutôt que déduire.
- 07
score, un seul nombre de 0 à 100.
Un score de crédibilité composite. Il n'est pas déductible des autres propriétés, c'est précisément l'intérêt de le demander : un seul entier sur lequel appliquer un seuil dans un flux d'inscription sans écrire vous-même des règles sur les noms d'opérateurs et les types de lignes.
Chaque propriété vous indique si elle a répondu.
Chaque bloc contient son propre statut : ok, unavailable ou inconclusive. Seul ok contient une valeur, vous n'avez donc jamais à inspecter une réponse pour savoir si elle est vide, et un champ sans valeur est omis plutôt que défini à null. La facturation suit la même logique. La recherche de base est facturée une fois, une propriété n'est facturée que lorsque son statut est ok, et une recherche qui échoue ne facture rien.
const answer = await bird.lookup.phoneNumber({
phone_number: "+31612345678",
type: ["presence", "roaming", "score"],
});
// Only a block whose status is ok carries a value.
if (answer.presence?.status === "ok") {
console.log(answer.presence.reachable);
}
if (answer.roaming?.status === "ok") {
console.log(answer.roaming.is_roaming, answer.roaming.mcc, answer.roaming.mnc);
}
// unavailable and inconclusive both mean no value, and no charge.
if (answer.score?.status !== "ok") {
console.log("no credibility score on this answer");
}
Un numéro par requête.
Il n'existe pas de forme batch, et c'est voulu : une recherche est une requête en temps réel contre les données opérateur, et un batch masquerait lesquelles parmi un millier de lignes ont reçu une réponse et lesquelles non. La limite de débit commence à 10 requêtes par minute par identifiant actif et Lookup dispose de son propre budget, de sorte que le filtrage de numéros n'entame jamais votre quota d'envoi. Envoyez un Idempotency-Key et un retry rejoue la réponse déjà payée au lieu d'en acheter une seconde.
Approfondissez dans la documentation.
Rechercher un numéro de téléphone détaille la requête et chaque champ qu'elle peut renvoyer. La vue d'ensemble de Lookup couvre les deux opérations et les statuts de propriétés sur une seule page, les limites de débit documentent le groupe lookup, et l'idempotence explique ce que coûte une réponse rejouée.
Questions sur le phone number lookup, avec réponses.
Formatage, types de lignes, portabilité, et ce qu'une recherche ne fait pas.
Quelles informations une recherche de numéro de téléphone fournit-elle ?
Comment dois-je écrire le numéro ?
Pourquoi mon numéro a-t-il été rejeté ?
Quels types de ligne peuvent être renvoyés ?
Comment savoir si un numéro a été porté ?
Pourquoi country_code est-il absent de ma réponse ?
Une recherche appelle-t-elle ou envoie-t-elle un message au numéro ?
Mettez-le en pratique.
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Le reste de Lookup
Une clé API, une enveloppe d'erreur. Explorez l'autre fonctionnalité.
Effectuez votre premier lookup sur un numéro que vous connaissez.
Le tableau de bord exécute la même opération un numéro à la fois — le moyen le plus rapide d'obtenir une réponse avant d'écrire la moindre ligne de code.