GreatNumber
首页 靓号搜索 常见问题 过户指导 更多资讯 ▾
查询运营商 号码估价 代理合作 号码能量 区号资讯 推荐有奖 运营商指南 开发者 API
关于我们 联系我们
登录 免费注册
开发者 API

GreatNumber Developer API

通过 RESTful API 以编程方式查询我们的靓号库存,搜索号码、获取详情和统计数据。

加州注册企业 美国正规注册 SSL 加密支付
API 概览

API Overview

使用 Bearer Token 认证,快速接入我们的号码数据库。

🔑

认证方式

Include Authorization: Bearer YOUR_API_KEY in the request header to authenticate all API requests.

🌐

基础 URL

https://www.greatnumber.com/api/v1

速率限制

Default 100 requests per minute, configurable per API key. Returns 429 status when exceeded.

API 端点

API Endpoints

以下是所有可用的 API 端点及其参数说明。

GET /api/v1/numbers

搜索号码

Search available premium numbers with filters for area code, state, type, price range, and more.

请求参数
参数 类型 必填 说明
area_codestringFilter by area code (e.g. 888, 310)
statestringFilter by US state (e.g. CA, NY)
typestringNumber type: local, tollfree
price_minnumberMinimum price in USD
price_maxnumberMaximum price in USD
searchstringFree-text search (digits or patterns)
sortstringprice_asc, price_desc, newest
per_pageintegerResults per page, max 100 (default 25)
响应示例
JSON Response
{
  "data": [
    {
      "number": "8889998888",
      "formatted": "(888) 999-8888",
      "area_code": "888",
      "state": null,
      "city": null,
      "type": "tollfree",
      "line_type": "voip",
      "pattern_type": "repeating",
      "price": 4999.00,
      "original_price": 5999.00,
      "status": "available",
      "is_featured": true,
      "label": "Repeating",
      "url": "https://www.greatnumber.com/en/number/8889998888"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 10, "per_page": 25, "total": 245 }
}
GET /api/v1/numbers/{number}

号码详情

Retrieve full details for a single number, wrapped in a data object.

路径参数
参数 类型 必填 说明
numberstring10-digit phone number (e.g. 8889998888)
响应示例
JSON Response
{
  "data": {
    "number": "8889998888",
    "formatted": "(888) 999-8888",
    "area_code": "888",
    "state": null,
    "city": null,
    "type": "tollfree",
    "line_type": "voip",
    "pattern_type": "repeating",
    "price": 4999.00,
    "original_price": 5999.00,
    "status": "available",
    "is_featured": true,
    "label": "Repeating",
    "url": "https://www.greatnumber.com/en/number/8889998888"
  }
}
GET /api/v1/stats

库存统计

Get aggregated inventory statistics including totals, counts by type/pattern, and price range distribution. Cached for 5 minutes.

响应示例
JSON Response
{
  "data": {
    "total": 80245312,
    "by_type": {
      "local": 72180000,
      "tollfree": 8065312
    },
    "by_pattern": {
      "repeating": 12450,
      "sequential": 8320,
      "double_repeating": 45200,
      "ending_0000": 3210
    },
    "price_ranges": {
      "under_100": 68000000,
      "100_to_500": 9800000,
      "500_to_2000": 1900000,
      "2000_to_10000": 420000,
      "over_10000": 125312
    },
    "cached_at": "2026-06-01T12:00:00Z"
  }
}
代码示例

Code Examples

以下是各种编程语言的 API 调用示例。

cURL
# Search toll-free numbers under $5000
curl -X GET "https://www.greatnumber.com/api/v1/numbers?type=tollfree&price_max=5000&sort=price_desc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

# Get details for a specific number
curl -X GET "https://www.greatnumber.com/api/v1/numbers/8889998888" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

# Get inventory stats
curl -X GET "https://www.greatnumber.com/api/v1/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
PHP (Guzzle)
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://www.greatnumber.com/api/v1/',
    'headers'  => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept'        => 'application/json',
    ],
]);

// Search numbers
$response = $client->get('numbers', [
    'query' => [
        'type'      => 'tollfree',
        'price_max' => 5000,
        'sort'      => 'price_desc',
        'per_page'  => 25,
    ],
]);

$data = json_decode($response->getBody(), true);

foreach ($data['data'] as $number) {
    echo $number['formatted'] . ' — $' . $number['price'] . "\n";
}
Python (requests)
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://www.greatnumber.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json",
}

# Search numbers
resp = requests.get(f"{BASE_URL}/numbers", headers=headers, params={
    "type": "tollfree",
    "price_max": 5000,
    "sort": "price_desc",
})
data = resp.json()

for number in data["data"]:
    print(f"{number['formatted']} — ${number['price']}")
JavaScript (fetch)
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://www.greatnumber.com/api/v1';

// Search numbers
const params = new URLSearchParams({
  type: 'tollfree',
  price_max: 5000,
  sort: 'price_desc',
});

const response = await fetch(`${BASE_URL}/numbers?${params}`, {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Accept': 'application/json',
  },
});

const { data, meta } = await response.json();

data.forEach(number => {
  console.log(`${number.formatted} — $${number.price}`);
});

console.log(`Page ${meta.current_page} of ${meta.last_page}`);
错误响应

Error Responses

API 使用标准 HTTP 状态码返回错误信息。

Status Code Description
401 Unauthorized 未认证 — 缺少、无效或过期的 API Key
404 Not Found 未找到 — 请求的资源不存在
429 Too Many Requests 请求过多 — 超出速率限制,请在 retry_after 秒后重试
Error Response Format
// 401 Unauthorized
{
  "message": "Unauthenticated."
}

// 429 Rate Limited
{
  "message": "Too Many Requests",
  "retry_after": 30
}

// 404 Not Found
{
  "message": "Number not found."
}

Ready to Integrate?

联系我们获取您的 API Key,立即开始集成。

Instagram Instagram
WhatsApp WhatsApp
WeChat WeChat
小红书 Xiaohongshu
Numi · 靓号顾问
您的专属选号 · 过户助手
即将跳转至第三方平台
前往主页 →
微信扫码添加
扫描下方二维码添加微信好友
Scan to add GreatNumber on WeChat
WeChat ID: GreatNumber2