IR21Data通信基础数据

DEVELOPER DOCS / API V1

号码原始归属 · Carrier Dipping

标准化国际号码，检查编号规则，并查询当前有效 MSISDN 号段的原始归属声明。

GET/v1/e164/:number/range-owner

用途与边界

示例号码仅用于说明响应结构，实际结果取决于数据集。生产日志应对带号码的 API 路径脱敏。浏览器工具使用 POST /v1/number/validate 将号码放入请求体，避免写入页面地址。 真实匿名响应隐藏号段明细、网络身份及来源；登录或 API Key 返回完整投影，demo 例外。单次查询不分页；未命中为 unknown，未来声明为 scheduled，归属冲突或无法唯一判断为 ambiguous；多个网络关联本身不代表歧义。无匹配不能认定为固话。

请求参数

参数类型 / 位置说明
numberstring · 必填 · path完整国际号码，E.164 使用字符串。
default_regionstring · 选填 · query解析本地格式时的默认 ISO2 地区；不作为未命中号码的默认归属。

请求示例

cURL / 合成示例
curl 'https://YOUR_IR21DATA_HOST/api/v1/e164/%2B12025550123/range-owner' \
  -H "X-API-Key: $IR21DATA_API_KEY"

成功响应示例

以下是结构示例，不是当前在线目录的查询结果。

JSON
{
  "code": 0,
  "data": {
    "input": "+12025550123",
    "e164": "+12025550123",
    "country_code": "1",
    "country_iso2": "US",
    "country_name_cn": "美国",
    "country_name_en": "United States",
    "number_type": "FIXED_LINE_OR_MOBILE",
    "possible": true,
    "valid": true,
    "match_status": "matched",
    "matches": [
      {
        "range": {
          "id": "example-range",
          "country_iso2": "US",
          "operator_id": "example-operator",
          "network_id": "example-network",
          "kind": "msisdn",
          "country_code": "1",
          "ndc": "202",
          "sn_start": "5550100",
          "sn_end": "5550199",
          "prefix": "1202",
          "start": "12025550100",
          "end": "12025550199",
          "number_length": 11,
          "owner_type": null,
          "source": {
            "source": "synthetic-example",
            "source_published_at": null,
            "effective_at": null,
            "ingested_at": "2026-09-08T00:00:00Z"
          }
        },
        "operator": {
          "id": "example-operator",
          "name": "Synthetic carrier",
          "short_name": "Example",
          "country_iso2": "US",
          "network_ids": [
            "example-network"
          ],
          "source": {
            "source": "synthetic-example",
            "source_published_at": null,
            "effective_at": null,
            "ingested_at": "2026-09-08T00:00:00Z"
          }
        },
        "network": {
          "id": "example-network",
          "operator_id": "example-operator",
          "name": "Synthetic network",
          "tadig": "DEMO1",
          "mcc": "001",
          "mnc": "01",
          "network_type": null,
          "roles": [],
          "capabilities": {
            "number_portability_supported": false
          },
          "e214": [
            {
              "country_code": "1",
              "network_code": "001",
              "prefix": "1001",
              "source": {
                "source": "synthetic-example",
                "source_published_at": null,
                "effective_at": null,
                "ingested_at": "2026-09-08T00:00:00Z"
              }
            }
          ],
          "source": {
            "source": "synthetic-example",
            "source_published_at": null,
            "effective_at": null,
            "ingested_at": "2026-09-08T00:00:00Z"
          }
        }
      }
    ],
    "original_carrier": "Synthetic carrier",
    "current_carrier": null,
    "is_ported": null,
    "portability_checked": false,
    "numbering_metadata_valid": true,
    "validation_basis": "numbering_metadata",
    "attribution_warning": null
  },
  "meta": {
    "request_id": "example-request-id",
    "dataset_version": "example-v1",
    "source_mode": "demo",
    "source_published_at": null,
    "ingested_at": "2026-09-08T00:00:00Z"
  }
}

data 字段语义

字段类型说明
input / e164string / string | null原始输入与标准化结果。
country_code / country_iso2string | null国家码与地区；共享国家码不得直接默认某一地区。
country_name_cn / country_name_enstring | null地区中英文名称。
possible / valid / number_typeboolean / boolean / string编号长度可能性、依据编号库或已生效号段声明的有效性和类型，不代表活跃或可达。
match_statusenummatched / unknown / ambiguous / invalid / scheduled。
matchesarray并列的 range、operator、network 候选，不擅自选择默认候选。
original_carrierstring | null原始声明归属；未知或无法确定时为 null。
current_carrier / is_portednull / null当前版本未查询携转，不返回 false 冒充验证。
portability_checkedfalse明确表示未查询单号携转状态。
numbering_metadata_validboolean · 可选编号库是否匹配；false 不应否定已生效的明确号段声明。
validation_basisenum · 可选numbering_metadata 编号库规则；range_declaration 已生效号段声明；unconfirmed 未确认。未来声明仍为 scheduled，不能提前确认有效。
attribution_warningstring | null归属判断限制或冲突提示，不替代 match_status。
matches[].network.e214[]E214Identity[] · optional关联网络的 E.214 声明数组：country_code、network_code、prefix、source。不是号码国家码或唯一默认网络，缺失不推算；旧目录尚未回填也可能缺失，不代表网络没有 E.214。

响应、鉴权与错误

数据接口支持X-API-Key 或同源 Cookie 会话。匿名访问为受限公共投影，完整字段权限由 API 服务执行。JSON 成功响应统一为{code:0,data,meta}；文件导出直接返回文件。

字段说明
meta.request_id本次请求标识，用于排查错误，不包含密钥。
meta.dataset_version / source_mode当前数据版本与 demo / ir21 / reference / mixed 来源模式。
meta.source_published_at源发布时间；未知为 null。
meta.ingested_at平台导入时间，ISO 格式 UTC。

400 表示参数不符，401 表示需要有效凭证，403 表示权限不足，409 表示目录或游标版本冲突，429 表示调用限制，503 表示服务或数据源暂不可用。请读取错误响应的 code、message、request_id，详见错误与重试。

ERROR / 示意结构
{
  "code": "EXAMPLE_ERROR_CODE",
  "message": "具体错误原因由服务端返回",
  "request_id": "example-request-id"
}