Instagram
WhatsApp
WeChat
小红书
通过 RESTful API 以编程方式查询我们的靓号库存，搜索号码、获取详情和统计数据。
使用 Bearer Token 认证，快速接入我们的号码数据库。
在请求头中添加 Authorization: Bearer YOUR_API_KEY 来认证所有 API 请求。
默认每分钟 100 次请求，可按 API Key 单独配置。超出后返回 429 状态码。
以下是所有可用的 API 端点及其参数说明。
搜索可用的靓号，支持按区号、州、类型、价格范围等条件筛选。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| area_code | string | 否 | Filter by area code (e.g. 888, 310) |
| state | string | 否 | Filter by US state (e.g. CA, NY) |
| type | string | 否 | Number type: local, tollfree |
| price_min | number | 否 | Minimum price in USD |
| price_max | number | 否 | Maximum price in USD |
| search | string | 否 | Free-text search (digits or patterns) |
| sort | string | 否 | price_asc, price_desc, newest |
| per_page | integer | 否 | Results per page, max 100 (default 25) |
{
"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 }
}
获取单个号码的完整信息，返回值包装在 data 对象中。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| number | string | 是 | 10-digit phone number (e.g. 8889998888) |
{
"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"
}
}
获取当前号码库存的汇总统计信息，包括总数、各类型数量和价格分布。结果缓存 5 分钟。
{
"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"
}
}
以下是各种编程语言的 API 调用示例。
# 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"
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"; }
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']}")
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}`);
API 使用标准 HTTP 状态码返回错误信息。
| Status | Code | Description |
|---|---|---|
| 401 | Unauthorized | 未认证 — 缺少、无效或过期的 API Key |
| 404 | Not Found | 未找到 — 请求的资源不存在 |
| 429 | Too Many Requests | 请求过多 — 超出速率限制，请在 retry_after 秒后重试 |
// 401 Unauthorized { "message": "Unauthenticated." } // 429 Rate Limited { "message": "Too Many Requests", "retry_after": 30 } // 404 Not Found { "message": "Number not found." }
