API 文档

您的第一个 API 请求

curl --get 'https://www.geoipy.com/api/IPsInfo' \
  --data-urlencode 'ip=8.8.8.8' \
  --header 'X-API-Key: YOUR_API_KEY'

使用 HTTPS 和 X-API-Key。URL 中的密钥可能被日志记录。请求头和 URL 密钥不一致会返回 HTTP 400。

在面板创建密钥，完整值仅显示一次。保存在私密服务器配置中，不要放入浏览器代码或公开仓库。 更换会立即使旧密钥失效。撤销或到期会阻止新请求，已接受的请求可能继续完成。

响应与数据时效

HTTP 200 返回 JSON。此为简化示例，可用字段取决于提供商数据。

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "country_code": "US"
}

缓存默认有效 12 小时。X-Data-Fetched-At 表示 UTC 获取时间。刷新失败时不会返回过期数据；获取时间不代表数据本身的年龄。

X-Request-ID 用于支持人员定位请求。地理位置为网络的大致位置，并非个人的精确位置。

用量与重试

成功请求（含缓存命中）消耗额度。处理中请求预留额度，失败则释放。每月 1 日 00:00 UTC 重置。更换套餐或密钥不会重置用量。

遇到 HTTP 429 或临时 503/504 时遵循 Retry-After，并以递增延迟进行有限重试。先修复无效输入或凭据。

错误

错误会以 application/json 和 HTTP 错误状态返回。API 标识符和示例内容保持文档定义的形式。

{
  "success": false,
  "error": {
    "code": 104,
    "type": "usage_limit_reached",
    "info": "The monthly API allowance has been reached."
  }
}

服务端示例

JavaScript · 服务器

const url = new URL('https://www.geoipy.com/api/IPsInfo');
url.searchParams.set('ip', '8.8.8.8');
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.GEOIPY_API_KEY }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error.info);
console.log(data);

C#

using (var client = new System.Net.Http.HttpClient())
{
    client.DefaultRequestHeaders.Add("X-API-Key",
        System.Environment.GetEnvironmentVariable("GEOIPY_API_KEY"));
    var response = await client.GetAsync(
        "https://www.geoipy.com/api/IPsInfo?ip=8.8.8.8");
    var json = await response.Content.ReadAsStringAsync();
    // Inspect response.StatusCode and parse json before retrying.
}

Python

import os, requests
response = requests.get(
    'https://www.geoipy.com/api/IPsInfo',
    params={'ip': '8.8.8.8'},
    headers={'X-API-Key': os.environ['GEOIPY_API_KEY']},
    timeout=15)
data = response.json()
response.raise_for_status()

PHP

$url = 'https://www.geoipy.com/api/IPsInfo?' . http_build_query(['ip' => '8.8.8.8']);
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('GEOIPY_API_KEY')]]);
$json = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($json === false) { throw new RuntimeException('The request failed.'); }
curl_close($ch);
$data = json_decode($json, true);
// Inspect $status and $data['error'] when the status is not 200.