通过 RESTful API 以编程方式查询我们的靓号库存,搜索号码、获取详情和统计数据。
使用 Bearer Token 认证,快速接入我们的号码数据库。
Include Authorization: Bearer YOUR_API_KEY in the request header to authenticate all API requests.
Default 100 requests per minute, configurable per API key. Returns 429 status when exceeded.
以下是所有可用的 API 端点及其参数说明。
Search available premium numbers with filters for area code, state, type, price range, and more.
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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 }
}
Retrieve full details for a single number, wrapped in a data object.
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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"
}
}
Get aggregated inventory statistics including totals, counts by type/pattern, and price range distribution. Cached for 5 minutes.
{
"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." }