一次 POST，一个结果，无需创建或轮询资源。基础查询返回号码所属国家、当前服务网络、原始分配号段的网络、号码是否在两者之间迁移的标志，以及线路类型。通过指定名称，还可获取另外五个属性。
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"
}
两个网络，以及它们之间的差异。
这个差异就是携号转网在响应中的表现。
电话号码查询是 Bird Lookup API 中两个操作之一。发送国际格式的号码（带或不带前导加号），即可获得 country_code、一个包含当前服务运营商的 network_info 块，以及一个包含原始分配号段运营商的 original_network_info 块。当两者不一致时，表示号码已携号转网，flags 会标明。仅限国内格式的号码会被拒绝而非猜测处理，因此错误输入会明确报错，而不是返回关于错误国家的貌似合理的结果。
返回内容及返回时机。
前三项随每次查询返回。其余项在您于 type 中指定时返回。
- 01
国家和两个运营商。
country_code 是号段的 ISO 国家代码，对于非地理号码会缺省而非猜测。network_info 和 original_network_info 各包含运营商名称以及移动国家代码和网络代码——如果您基于 MCC 和 MNC 而非名称进行路由，这正是您需要的。
- 02
线路类型，来自固定列表。
mobile、fixed_line、voip、toll_free、premium_rate、satellite、pager、payphone、m2m、service、other 或 unknown。列表是封闭的，因此对其进行 switch 判断始终是穷举的；在决定 SMS 是否可行之前，应先检查此字段。
- 03
携号转网标志，无额外费用。
flags 中的 ported 表示号码曾在任何时候更换过网络。它随基础查询一起返回，因此判断号码是否曾经携号转网这一低成本问题，无需请求任何额外属性。
- 04
classification，对线路的第二意见。
来自不同数据源的更精细判断，包含 line_type 所没有的值：fixed_line_or_mobile、shared_cost、national_rate、personal_number、isp、voice_mail、short_codes 等。它在响应中与 line_type 并列而非替代，因此当号码看起来异常时，您可以对比两者。
- 05
porting，包含日期和历史记录。
ported 为布尔值，last_ported_at 为时间戳，当注册机构仅知月份时提供 last_ported_at_is_approximate，history 为按时间从早到晚排列的携号转网事件列表。每个事件包含一个注册机构特定的操作代码，适合展示但不建议用于逻辑分支。
- 06
presence 和 roaming，来自实时网络。
presence 查询网络并报告 reachable，这是判断线路是否开机的最接近方式。roaming 报告 is_roaming 以及访问网络的 MCC 和 MNC，因此来自外国网络号码的注册是可以直接看到而非推测的。
- 07
score，0 到 100 的单一数值。
一个综合可信度评分。它无法从其他属性推导得出，这正是请求它的意义所在：在注册流程中，您可以用一个整数设定阈值，而无需自行编写基于运营商名称和线路类型的规则。
每个属性都会告诉您它是否已响应。
每个块都有自己的状态：ok、unavailable 或 inconclusive。只有 ok 才会携带值，因此您无需检查响应来判断它是否为空，没有值的字段会被省略而非设为 null。计费遵循同样的逻辑：基础查询计费一次，属性仅在状态为 ok 时计费，查询失败则不计费。
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");
}
每次请求一个号码。
没有批量形式，这是设计使然：查询是对运营商数据的实时请求，批量操作会掩盖一千行中哪些已响应、哪些未响应。速率限制起始为每个操作凭证每分钟 10 次请求，Lookup 有独立的配额，因此筛选号码不会占用您的发送额度。发送 Idempotency-Key 后，重试会重放您已付费的结果，而非再次购买。
电话号码查询常见问题解答。
格式、线路类型、携号转网，以及查询不能做什么。
电话号码查询能返回哪些信息？
号码应该怎么写？
为什么我的号码被拒绝了？
可以返回哪些线路类型？
如何判断号码是否已携号转网？
为什么我的结果中没有 country_code？
查询会拨打或发送消息给该号码吗？
Lookup 的其他功能
一个 API 密钥，一个错误信封。探索另一项能力。