Phone number lookup

Saiba o que é um número. Antes de enviar para ele.

Um POST, uma resposta, sem recurso para criar ou consultar. A consulta base devolve o país do número, a rede que o serve atualmente, a rede que emitiu a sua gama, um indicador que diz se houve mudança entre as duas, e o tipo de linha. Cinco propriedades adicionais ficam disponíveis ao nomeá-las.

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

Duas redes, e a diferença entre elas.

Essa diferença é o aspeto da portabilidade numa resposta.

Phone number lookup é uma das duas operações na Bird Lookup API. Envie um número em formato internacional, com ou sem o sinal de mais inicial, e recebe de volta country_code, um bloco network_info para a operadora que serve o número atualmente, e um bloco original_network_info para a operadora à qual a gama foi atribuída. Quando os dois divergem, o número foi portado, e flags indica-o. Números apenas nacionais são rejeitados em vez de adivinhados, para que uma entrada inválida falhe de forma clara em vez de devolver uma resposta plausível sobre o país errado.

O que é devolvido, e quando.

Os três primeiros chegam com cada consulta. Os restantes chegam quando os nomeia em type.

01
País e ambas as operadoras.
country_code é o país ISO da gama, e está ausente para números não geográficos em vez de ser adivinhado. network_info e original_network_info incluem cada um o nome da operadora mais os códigos de país e rede móvel, que é o que precisa se encaminha por MCC e MNC em vez de por nome.
02
Tipo de linha, a partir de uma lista fechada.
mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other ou unknown. A lista é fechada, por isso um switch sobre ela mantém-se exaustivo, e é o campo a verificar antes de decidir se um SMS é sequer possível.
03
O indicador de portabilidade, sem custo adicional.
flags inclui ported quando o número mudou de rede em algum momento. Chega com a resposta base, por isso a pergunta simples de saber se um número alguma vez foi portado não requer nenhuma propriedade adicional.
04
classification, uma segunda opinião sobre a linha.
Uma leitura mais detalhada de uma fonte diferente, com valores que line_type não possui: fixed_line_or_mobile, shared_cost, national_rate, personal_number, isp, voice_mail, short_codes, e mais. Aparece ao lado de line_type na resposta em vez de o substituir, para que possa comparar os dois quando um número parecer invulgar.
05
porting, com datas e histórico.
ported como booleano, last_ported_at como timestamp, last_ported_at_is_approximate quando o registo só conhece o mês, e history como a lista de eventos de portabilidade do mais antigo para o mais recente. Cada evento inclui um código de ação específico do registo, que vale a pena mostrar mas não vale a pena usar para ramificação.
06
presence e roaming, a partir da rede em tempo real.
presence consulta a rede e reporta reachable, que é o mais próximo de perguntar se a linha está ligada. roaming reporta is_roaming mais o MCC e MNC da rede visitada, para que um registo a partir de um número numa rede estrangeira seja algo que pode ver em vez de inferir.
07
score, um único número de 0 a 100.
Uma pontuação de credibilidade composta. Não é derivável das outras propriedades, que é exatamente o motivo para a solicitar: um inteiro único no qual pode aplicar um limiar num fluxo de registo sem ter de escrever regras sobre nomes de operadoras e tipos de linha.

Cada propriedade indica se respondeu.

Cada bloco contém o seu próprio status: ok, unavailable ou inconclusive. Apenas ok contém um valor, por isso nunca precisa de inspecionar uma resposta para perceber que está vazia, e um campo sem valor é omitido em vez de definido como null. A faturação segue a mesma lógica. A consulta base é cobrada uma vez, uma propriedade é cobrada apenas quando o seu status é ok, e uma consulta que falha não é cobrada.

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

Um número por pedido.

Não existe forma batch, por design: uma consulta é uma query em tempo real contra dados da operadora, e um batch ocultaria quais das mil linhas foram respondidas e quais não. O limite de taxa começa em 10 pedidos por minuto por credencial ativa e Lookup tem o seu próprio orçamento, para que a verificação de números nunca consuma o seu limite de envio. Envie um Idempotency-Key e uma nova tentativa reproduz a resposta pela qual já pagou em vez de comprar uma segunda.

Aprofunde na documentação.

Consultar um número de telefone percorre o pedido e cada campo que pode devolver. A Visão geral do Lookup abrange ambas as operações e os estados das propriedades numa única página, limites de taxa documenta o grupo de lookup, e idempotência explica quanto custa uma resposta repetida.

Perguntas sobre phone number lookup, respondidas.

Formatação, tipos de linha, portabilidade e o que um lookup não faz.

O que responde uma consulta de número de telefone?

A consulta base responde o país do número, a rede que o serve atualmente, a rede que emitiu a sua faixa, se alguma vez mudou de rede e um tipo de linha aproximado. É sempre executada e, se não puder ser respondida, todo o pedido falha em vez de devolver uma resposta meio vazia.

Como devo escrever o número?

Código de chamada do país primeiro, depois o número nacional. O sinal de mais inicial é opcional e 00 funciona no seu lugar, por isso +31612345678, 31612345678 e 0031612345678 são todos o mesmo número.

Porque é que o meu número foi rejeitado?

Um número escrito para marcação dentro de um país, sem código de país, devolve E22000 em vez de ser adivinhado. Adicionar um código de país a 0612345678 identificaria um número real noutro lugar e cobraria pela consulta desse número.

Que tipos de linha pode devolver?

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other ou unknown. unknown significa que a plataforma da operadora não tem classificação para a faixa, e other significa que tem uma sem equivalente aqui. Solicite a propriedade classification para o serviço alocado com maior precisão.

Como sei se um número foi portado?

network_info é a rede que serve o número atualmente e original_network_info é a rede que emitiu a sua faixa. As duas diferem quando um número foi portado, e flags contém ported nesse caso. Solicite a propriedade porting quando também precisar da data e do registo completo.

Porque é que country_code está em falta na minha resposta?

Porque o número não pertence a nenhum país específico, como acontece com uma faixa não geográfica. Campos sem valor são omitidos em vez de devolvidos como null, por isso cada campo presente na resposta foi resolvido.

Uma consulta liga ou envia mensagem para o número?

Não. Uma consulta nunca contacta o próprio número. Lê dados da operadora e de inteligência do número, e as propriedades presence e roaming consultam a rede onde o número está registado, por isso nada toca e nada chega ao aparelho.