Wyszukiwanie numeru telefonu

Dowiedz się, czym jest numer. Zanim wyślesz do niego wiadomość.

Rozpocznij Przeczytaj przewodnik po numerach telefonów

Jeden POST, jedna odpowiedź, bez zasobów do tworzenia ani odpytywania. Podstawowe wyszukiwanie zwraca kraj numeru, sieć obsługującą go obecnie, sieć, która przydzieliła jego zakres, flagę informującą o ewentualnym przeniesieniu między nimi oraz typ linii. Pięć dodatkowych właściwości uzyskasz, podając ich nazwy.

phone-number.ts

200

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"
}

phone-number.ts

200

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"
}

Dwie sieci i różnica między nimi.

Ta różnica to właśnie przenoszenie widoczne w odpowiedzi.

Wyszukiwanie numeru telefonu to jedna z dwóch operacji w Bird Lookup API. Wyślij numer w formacie międzynarodowym, z plusem na początku lub bez niego, a otrzymasz country_code, blok network_info z operatorem obsługującym numer obecnie oraz blok original_network_info z operatorem, któremu przydzielono jego zakres. Gdy te dwa się różnią, numer został przeniesiony, a flags to potwierdza. Numery wyłącznie krajowe są odrzucane zamiast odgadywane, więc nieprawidłowe dane wejściowe kończą się jawnym błędem zamiast zwracaniem wiarygodnej odpowiedzi dotyczącej niewłaściwego kraju.

Co jest zwracane i kiedy.

Pierwsze trzy są zwracane przy każdym wyszukiwaniu. Pozostałe pojawiają się, gdy wymienisz je w type.

01
Kraj i obaj operatorzy.
country_code to kraj ISO danego zakresu — dla numerów niegeograficznych jest nieobecny zamiast odgadywany. network_info i original_network_info zawierają nazwę operatora oraz kody kraju i sieci mobilnej, co jest istotne, jeśli rotujesz na podstawie MCC i MNC zamiast nazwy.
02
Typ linii ze zamkniętej listy.
mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other lub unknown. Lista jest zamknięta, więc instrukcja switch na niej pozostaje wyczerpująca — to pole, które należy sprawdzić, zanim zdecydujesz, czy SMS w ogóle jest możliwy.
03
Flaga przenoszenia, bez dodatkowych opłat.
flags zawiera ported, gdy numer kiedykolwiek zmienił sieć. Jest zwracany z podstawową odpowiedzią, więc proste pytanie, czy numer był kiedyś przenoszony, nie wymaga żadnej dodatkowej właściwości.
04
classification — druga opinia o linii.
Dokładniejsze odczytanie z innego źródła, z wartościami, których line_type nie posiada: fixed_line_or_mobile, shared_cost, national_rate, personal_number, isp, voice_mail, short_codes i inne. Znajduje się obok line_type w odpowiedzi, a nie go zastępuje, więc możesz porównać oba, gdy numer wygląda nietypowo.
05
porting — z datami i historią.
ported jako wartość logiczna, last_ported_at jako znacznik czasu, last_ported_at_is_approximate gdy rejestr zna tylko miesiąc, oraz history jako lista zdarzeń przenoszenia od najstarszego. Każde zdarzenie zawiera kod akcji specyficzny dla rejestru, który warto wyświetlać, ale nie warto na nim rozgałęziać logiki.
06
presence i roaming — z sieci na żywo.
presence odpytuje sieć i raportuje reachable, co jest najbliższym odpowiednikiem pytania, czy linia jest włączona. roaming raportuje is_roaming oraz MCC i MNC odwiedzanej sieci, więc rejestracja z numeru znajdującego się w zagranicznej sieci to coś, co można zobaczyć, a nie domyślać się.
07
score — jedna liczba od 0 do 100.
Złożona ocena wiarygodności. Nie da się jej wyprowadzić z pozostałych właściwości — i właśnie dlatego warto o nią pytać: jedna liczba całkowita, na której możesz ustawić próg w procesie rejestracji, bez pisania własnych reguł na podstawie nazw operatorów i typów linii.

Każda właściwość informuje, czy odpowiedziała.

Każdy blok ma własny status: ok, unavailable lub inconclusive. Tylko ok zawiera wartość, więc nigdy nie musisz analizować odpowiedzi, żeby stwierdzić, że jest pusta — pole bez wartości jest pomijane zamiast ustawiane na null. Rozliczanie działa analogicznie. Podstawowe wyszukiwanie jest rozliczane raz, właściwość jest rozliczana tylko gdy jej status to ok, a nieudane wyszukiwanie nie jest rozliczane wcale.

properties.ts

200 · partial

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");
}

Jeden numer na zapytanie.

Nie ma formy wsadowej — celowo: wyszukiwanie to zapytanie na żywo do danych operatora, a wsad ukrywałby, który z tysiąca wierszy uzyskał odpowiedź, a który nie. Limit szybkości zaczyna się od 10 zapytań na minutę na dane uwierzytelniające, a Lookup ma własny budżet, więc sprawdzanie numerów nigdy nie wchodzi w limit wysyłki. Wyślij Idempotency-Key, a ponowne zapytanie odtworzy odpowiedź, za którą już zapłaciłeś, zamiast kupować drugą.

Dowiedz się więcej w dokumentacji.

Wyszukiwanie numeru telefonu omawia zapytanie i każde pole, które może zwrócić. Przegląd Lookup obejmuje obie operacje i statusy właściwości na jednej stronie, limity szybkości dokumentują grupę lookup, a idempotencja wyjaśnia, ile kosztuje powtórzona odpowiedź.

Pytania o wyszukiwanie numerów telefonów — z odpowiedziami.

Formatowanie, typy linii, przenoszenie i czego wyszukiwanie nie robi.

Co odpowiada wyszukiwanie numeru telefonu?

Podstawowe wyszukiwanie zwraca kraj numeru, sieć aktualnie go obsługującą, sieć, która wydała jego zakres, czy kiedykolwiek zmienił sieć, oraz ogólny typ linii. Wykonuje się zawsze — jeśli nie może zwrócić odpowiedzi, całe żądanie kończy się błędem zamiast zwracać częściowo pustą odpowiedź.

Jak powinien być zapisany numer?

Najpierw kod kraju, potem numer krajowy. Początkowy plus jest opcjonalny, a 00 działa jako jego zamiennik — +31612345678, 31612345678 i 0031612345678 to ten sam numer.

Dlaczego mój numer został odrzucony?

Numer zapisany w formacie do wybierania wewnątrz jednego kraju, bez kodu kraju, zwraca błąd E22000 zamiast być zgadywany. Dodanie kodu kraju do 0612345678 wskazałoby prawdziwy numer w innym miejscu i obciążyło Cię opłatą za jego wyszukanie.

Jakie typy linii mogą zostać zwrócone?

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other lub unknown. unknown oznacza, że platforma operatora nie ma klasyfikacji dla danego zakresu, a other oznacza, że posiada klasyfikację, która nie ma tutaj odpowiednika. Użyj właściwości classification, aby uzyskać dokładniejszą informację o przydzielonej usłudze.

Jak sprawdzić, czy numer został przeniesiony?

network_info to sieć aktualnie obsługująca numer, a original_network_info to sieć, która wydała jego zakres. Te dwie wartości różnią się po przeniesieniu numeru, a flags zawiera wówczas ported. Użyj właściwości porting, jeśli potrzebujesz również daty i pełnego rekordu.

Dlaczego w mojej odpowiedzi brakuje country_code?

Ponieważ numer nie należy do żadnego konkretnego kraju, jak to bywa w przypadku zakresów niegeograficznych. Pola bez wartości są pomijane zamiast zwracane jako null, więc każde pole obecne w odpowiedzi zostało rozwiązane.

Czy wyszukiwanie dzwoni na numer lub wysyła do niego wiadomość?

Nie. Wyszukiwanie nigdy nie kontaktuje się z samym numerem. Odczytuje dane operatora i dane analityczne numeru, a właściwości presence i roaming odpytują sieć, w której numer jest zarejestrowany — nic więc nie dzwoni i nic nie trafia na urządzenie.