IR21Data · 通信数据，清晰可循

GET/v1/operators

用途与边界

真实匿名响应隐藏 network_ids 与 source；登录会话或 API Key 返回完整投影，demo 可匿名展示完整合成结构。运营商不等于单一网络，不定义默认 MCCMNC。无生效时间筛选，需解读 source.effective_at；网络身份可能是一对多。

请求参数

参数	类型 / 位置	说明
`q`	string · query	匹配 ID、名称、简称、TADIG、MCCMNC；保持前导零。
`country / operator`	string · query	地区 ISO2/ISO3/名称；运营商 ID 或名称筛选。
`cursor / limit`	string / integer · 选填 · query	默认 50 条，limit 为 1–500。保持筛选不变并使用 next_cursor；400 INVALID_CURSOR 时检查参数，409 CURSOR_VERSION_MISMATCH 时重建快照。

请求示例

cURL / 合成示例

curl 'https://YOUR_IR21DATA_HOST/api/v1/operators?q=DEMO1&limit=20' -H "X-API-Key: $IR21DATA_API_KEY"

成功响应示例

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

JSON

{
  "code": 0,
  "data": {
    "items": [
      {
        "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"
        }
      }
    ],
    "total": 1,
    "next_cursor": 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 字段语义

字段	类型	说明
`items / total / next_cursor`	array / number / string \| null	当前页、匹配总数、下一页游标；null 表示结束，未命中为 items:[]。
`id / name / short_name / country_iso2`	string	运营商身份；无法对应现代地区时 country_iso2 为空字符串。
`gsma_country_code`	string · optional	保留特殊或历史地区代码，不强行归入国家。
`network_ids / source`	string[] / SourceInfo	授权后返回网络关联与来源；网络详情通过 PLMN、TADIG 或能力接口获取。

响应、鉴权与错误

数据接口支持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"
}