注册并联系客服，免费领取 100 次检测。免费注册
CarrierLookup
CarrierLookup 工作流示意图：集成原始归属运营商查询 API：原始运营商与线路类型工作流
本文所述工作流的示意图（CarrierLookup）。

集成原始归属运营商查询 API，通过实时 REST 端点和批量文件处理，检查原始运营商分配、线路类型及号码分配地理位置。

原始归属运营商查询 API 为电信数据管理提供原始运营商和号码分配背景信息。当组织通过 API 查询电话号码时，服务会返回指示该号码段最初分配给哪家运营商的数据，以及线路类型和分配地理位置。这些信息代表了编号计划所定义的行政分配，为内部路由和风险评估工作流提供稳定的电信背景。由于它反映的是初始分配而非活跃的用户网络路由，团队通过实时单次端点、多项同步查询或异步批量文件来集成 CarrierLookup，以检查基础号码参数。

核心分配数据与线路类型属性

电信编号安排遵循国际标准，例如 ITU-T Recommendation E.164，该标准定义了包含国家代码和用户号码的全球编号计划。在这些结构中，监管机构将特定的号码段分配给网络运营商。CarrierLookup 通过其原始归属运营商查询功能公开这些基础属性。

响应模式将电信背景组织为不同的数据点：

  • carrier：最初分配该号码段的通信提供商。
  • underlying_carrier：与分配范围相关的底层基础设施提供商。
  • number_type：线路分类，例如移动或固定线路分配。
  • country_code：与分配区域相匹配的国际拨号前缀。
  • region 和 city：编号分配计划中指定的行政地理区域。

这些数据点确立了静态范围属性。由于号码无论用户活动如何都会保留其初始范围定义，因此该数据可作为过滤、电信分析和内部记录组织的统一参考。

实时单次与多次检查集成

集成实时查询允许后端系统在应用程序接入或审核工作流期间同步评估电话号码。请求使用从安全应用服务器提交的 X-API-Key HTTP 标头进行身份验证。

单个号码检查工作流

要检查单个标识符，请向 POST /api/v1/check 提交请求。有效负载需要以国际标准 E.164 语法格式化的电话号码，包含前导加号、国家代码和用户数字，且不含空格或标点符号。

处理完成后，服务器将返回包含 code、msg 和扁平化 data 对象的 JSON 响应。数据有效负载包含 service_type、identifier、carrier、underlying_carrier、number_type、country_code、region 和 city。如果特定范围的详细信息未列出，可选的分配字段可能会返回为空，但查询仍会注册为已完成。

同步多次检查工作流

对于需要立即评估的批次，组织可调用 POST /api/v1/batch-check。此端点在单次调用中同步处理多个 E.164 号码。响应返回高级执行指标以及一个有序数组：

  • service_type：确认执行的查询服务。
  • total：提交的标识符总数。
  • succeeded：成功评估的项目数量。
  • failed：遇到处理失败的项目数量。
  • results：项目的有序集合，每个项目包含 identifier 和 exists。

在此同步多次响应中，exists=false 值表示未返回标准分配记录，而非断言线路已断开或格式错误。

异步批量文件处理工作流

在处理大规模电信记录清单时，团队可使用异步 carrier_batch 服务。此工作流处理基于文件的提交，而无需保持客户端连接处于打开状态。

任务提交与结构

通过 POST /api/v1/bulk-tasks 使用多部分表单数据提交批处理请求。上传需要一个纯 TXT 或 CSV 文件，每行包含一个标识符，以及指定的 ISO 国家/地区参数。任务大小受每种产品限制的约束，读者可以在官方 API 文档中查看当前的操作参数。

在摄取期间，自动预处理会审查列表内容，以过滤重复项、格式错误的条目以及与所选目标国家/地区不符的行。处理过程会将这些不符合要求的条目排除在查询统计之外。

任务生命周期与检索

客户端通过查询 GET /api/v1/bulk-tasks/{id} 来监控批处理进度。轮询计划应遵循有节奏的频率，检查间隔不应短于 30 秒。任务生命周期经历三个正式状态：

  • processing：文件正在进行系统评估。
  • failed：任务遇到执行错误或未通过摄取要求。
  • success：范围评估已完成，输出可用。

当任务以 success 结束时，端点将提供一个 CSV 文件。输出结构包含七个标准化标题：identifier、carrier、underlying_carrier、number_type、country_code、region 和 city。此文件中的标识符呈现为包含国家代码的数字，省略加号。

操作限制与覆盖范围规范

实施运营商查询集成需要将技术架构与系统并发和地理参数保持一致。

操作参数 规范详情
并发槽位 5 个共享的实时请求
单次检查超时 最长 60 秒
多次检查超时 最长 300 秒
多次请求并发 每个账户 1 个活跃的多次请求
账户余额端点 GET /api/v1/balance（返回 balance_micros）

地理覆盖范围具有不同的区域规则。实时单个号码查询可处理中国大陆 (+86)、香港 (+852) 和澳门 (+853) 的适量操作查询。但是，批量文件不接受来自这三个地区的号码。台湾 (+886) 的覆盖状态尚未确认。

要在调用检查前验证账户状态，请查询 GET /api/v1/balance 以获取当前余额，而不会消耗查询额度。此外，新注册用户可联系支持团队以获得 100 次免费检查，用于针对生产端点验证其集成工作流。

常见问题解答

API 如何处理在网络之间携号转网的号码？

CarrierLookup 报告的是行政当局最初分配该号码段的运营商。在电信领域，消费者可以在保留号码的同时更换提供商，如 Porting: Keeping Your Phone Number When You Change Providers 所述。因此，carrier 字段反映的是历史范围分配，而非当前服务运营商，从而为编号分析保持了不变的结构属性。

实时多次检查与批量批处理服务有何区别？

实时多次检查端点 POST /api/v1/batch-check 同步评估号码，返回包含 service_type、total、succeeded、failed 以及显示 identifier 和 exists 布尔值的有序结果的即时 JSON 有效负载。相比之下，批量批处理服务从提交的 CSV 或 TXT 文件中异步处理列表。后台分析完成后，批量任务提供一个可下载的 CSV，其中包含完整的分配列，包括 carrier、underlying_carrier、number_type、country_code、region 和 city。

region 和 city 字段是否指示设备的物理位置？

region 和 city 字段指定了初始编号计划分配的地理边界，对应于电话交换机的行政分配。这些值提供了用户号码段的区域背景。它们代表静态编号分配，而非实时移动设备定位、实时蜂窝塔连接或单个用户的物理所在地。

了解更多

选择适合您工作流下一步的产品信息。

参考来源