查看全局 API 说明（请求/响应头、通用 JSON 格式）

手机号段 API

根据手机号或前 7 位号段查询归属省、市与运营商

Base URL https://www.resapi.cn/v1/phone

简介

基于本地号段库（约 52 万条）返回归属地与运营商；支持物联网 143 号段补录数据。仅作号段参考，不提供实名或在网核验。

GET /v1/phone/lookup

根据 11 位手机号码 或 7 位号段 查询归属地及运营商信息。

查询逻辑：对 11 位号码取前 7 位，在号段库中精确匹配；虚拟运营商号段会返回归类后的基础运营商（移动/联通/电信/广电）及 virtual_operator 品牌名（如有）。

仅根据号段静态库返回结果，不代表实名登记、在网状态或携号转网后的实际运营商。数据来源于公开号段库及 Excel 补录，截止约 2026 年 5 月。

查询参数

名称	类型	必填	说明	示例
number	string	是	11 位手机号，或 7 位号段（可含空格、横线，会自动去除）	`13213000000`

响应字段

字段	说明
number	输入号码；11 位输入时返回完整号码，仅 7 位号段输入时返回该 7 位
prefix7	匹配用的前 7 位号段
province	省份
city	城市
operator	基础运营商（移动/联通/电信/广电等）
virtual_operator	虚拟运营商品牌名，非虚拟号段时为空字符串
carrier_id	库内运营商编码（与数据源一致，仅供参考）
note	使用说明与免责提示

响应示例

{
  "data": {
    "number": "13213000000",
    "prefix7": "1321300",
    "province": "河南",
    "city": "郑州",
    "operator": "联通",
    "virtual_operator": "",
    "carrier_id": 2,
    "note": "仅根据号段库返回归属地与运营商信息，不代表实名登记或实时在网状态"
  }
}

通用错误码

以下错误码适用于平台全部 /v1/* 接口（各接口在「错误代码」Tab 中另有本接口补充说明）。

错误响应格式

HTTP 状态码非 2xx 时，响应体一般为：

{
  "error": {
    "code": "错误码",
    "message": "错误信息"
  }
}

错误码一览

HTTP	code	message	说明
400	invalid_params	参数无效	必填参数缺失、格式不合法或超出允许范围
404	not_found	资源不存在	按编码或 ID 查询时无匹配记录
429	rate_limit_exceeded	请求过于频繁	超过当前 IP 的访问频率限制
500	internal_error	服务器内部错误	服务端或数据库异常，请稍后重试

限流、缓存等 HTTP 响应头含义见上文「响应头说明」。

本接口补充

HTTP	code	message	说明
400	invalid_params	number 不能为空	未传 `number`
400	invalid_params	号码须为 11 位手机号或 7 位号段	去非数字后长度不是 7 或 11
404	not_found	未找到对应的手机号段：xxxxxxx	号段不在库中

请求根地址为 https://www.resapi.cn。每个场景含 7 种语言（cURL → JavaScript → Python → Go → Java → PHP → C#）。

手机号归属地查询

GET /v1/phone/lookup?number=13213000000

cURL

curl -s "https://www.resapi.cn/v1/phone/lookup?number=13213000000" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/phone/lookup?number=13213000000", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests
r = requests.get(
    "https://www.resapi.cn/v1/phone/lookup",
    params={"number": "13213000000"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

package main
import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
)
func main() {
  url := "https://www.resapi.cn/v1/phone/lookup?number=13213000000"
  req, _ := http.NewRequest(http.MethodGet, url, nil)
  req.Header.Set("Accept", "application/json")
  resp, err := http.DefaultClient.Do(req)
  if err != nil { log.Fatal(err) }
  defer resp.Body.Close()
  var out map[string]any
  json.NewDecoder(resp.Body).Decode(&out)
  fmt.Printf("%+v\n", out)
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
  public static void main(String[] args) throws Exception {
    String url = "https://www.resapi.cn/v1/phone/lookup?number=13213000000";
    HttpRequest req = HttpRequest.newBuilder().uri(URI.create(url)).header("Accept", "application/json").GET().build();
    HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}

PHP

<?php
$url = "https://www.resapi.cn/v1/phone/lookup?number=13213000000";
$ctx = stream_context_create(["http" => ["header" => "Accept: application/json\r\n"]]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;
var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var json = await client.GetStringAsync("https://www.resapi.cn/v1/phone/lookup?number=13213000000");
Console.WriteLine(json);

物联网号段（7 位）

GET /v1/phone/lookup?number=1430029

与上相同，将 URL 中 number 换为 1430029 即可（仅 7 位号段时 data.number 返回该 7 位）。