Python 地理追踪 API 集成指南与 Zyla API Hub

您需要从 IP 地址解析用户的位置，根据区域限制功能，并标记风险流量——本周内完成。通过本指南，您将从 Python 查询地理追踪 API 的地理位置端点，解析您实际需要的响应（纬度/经度、城市、ISP、威胁信号），并在 Zyla API Hub 上完成有效的身份验证和计费。

地理追踪 API 提供的内容

地理追踪 API 返回给定 IP 地址的地理位置信息。它包括：

国家、地区、城市、时区
纬度和经度
ISP、组织和主机名
大陆和货币上下文
安全信号（代理/VPN/Tor 存在、威胁级别）

常见实现：区域内容控制、欺诈筛查、地方感知用户体验（时区和货币）、订单风险评估，以及基于位置的日志记录或分析。

Zyla API Hub 的身份验证和计费

Zyla API Hub 在其超过 10,000 个公共 API 的目录中使用订阅 + 配额模型。身份验证通过作为 Authorization: Bearer 头发送的单个 API 密钥进行。对于您在 Zyla 的第一个 API，您可以从 7 天的试用或 50 次请求开始（没有免费计划）。请查看 API 页面以获取当前访问选项和定价。

关键点：

每个 Zyla API 只有一个账户和一个 API 密钥。
没有按调用付费；计划为订阅 + 配额。
对每个请求应用相同的 Authorization: Bearer YOUR_API_KEY 头。

您可以在 zylalabs.com 浏览市场，或直接访问地理追踪 API 列表进行订阅。

在 Zyla API Hub 上开始

打开地理追踪 API 页面。
点击订阅（或如果可用，开始免费试用）以激活访问。
从您的仪表板复制您的 API 密钥。

当您准备好实施时，将您的密钥作为 Authorization: Bearer YOUR_API_KEY 传递到每个请求中。

端点：地理位置

地理追踪 API 暴露一个用于 IP 到地理位置解析的单一地理位置端点。

方法：GET
URL：https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation
所需查询参数：
- ip（字符串）：要解析的 IP 地址

官方 cURL 示例

curl -s -X GET "https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation?ip=181.188.132.167" \
-H "Authorization: Bearer YOUR_API_KEY"

官方示例 JSON 响应

{
"status": "success",
"country": "BO",
"countryCode": "BO",
"region": "La Paz Department",
"regionName": "Santa Cruz Department",
"city": "La Paz",
"zip": "",
"lat": -17.7834,
"lon": -63.1822,
"timezone": "America/La_Paz",
"isp": "Telefónica Celular de Bolivia S.A.",
"org": "AS27882 Telefónica Celular de Bolivia S.A.",
"as": "AS27882 Telefónica Celular de Bolivia S.A.",
"query": "181.188.132.167",
"areaCode": "",
"dmaCode": "",
"inEU": 0,
"euVATrate": false,
"continentCode": "SA",
"continentName": "South America",
"locationAccuracyRadius": "5",
"currencyCode": "BOB",
"currencySymbol": "$b",
"currencySymbol_UTF8": "$b",
"currencyConverter": 6.9324,
"flag": "🇧🇴",
"callingCode": "591",
"languageCode": null,
"security": {
"is_proxy": false,
"proxy_type": null,
"is_tor": false,
"is_tor_exit": false,
"threat_level": "Low",
"threat_score": "0",
"is_abuser": false,
"is_attacker": false,
"is_bogon": false,
"is_cloud_provider": false,
"is_relay": false,
"is_vpn": false,
"is_anonymous": false,
"is_threat": false
},
"hostname": "scz-181-188-132-00167.tigo.bo",
"classType": "class B",
"application": "Medium networks"
}

您可能会使用的字段亮点：

lat, lon：十进制度数坐标。
country, countryCode, region, regionName, city：用于政策和个性化的文本地理数据。
timezone：用于地方感知调度和格式化的 IANA 时区字符串。
isp, org, as, hostname：网络所有权和路由上下文。
security.*：用于风险评分的布尔标志和威胁元数据。
currencyCode 和 currencyConverter：货币上下文，适用于显示和转换。

Python 集成

以下 Python 示例调用地理位置端点，处理身份验证，检查 API 的状态字段，并提取用于功能限制和日志记录的最实用字段。

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation"

def geolocate_ip(ip: str) -> dict:
headers = {
"Authorization": f"Bearer {API_KEY}"
}
params = {"ip": ip}

# 调整超时以适应您的环境；使用（连接，读取）
resp = requests.get(BASE_URL, headers=headers, params=params, timeout=(5, 10))
resp.raise_for_status()
data = resp.json()

# API 返回一个 "status" 字段；在信任字段之前检查它
if data.get("status") != "success":
raise RuntimeError(f"Geo lookup failed for {ip}: {data}")

return {
"ip": data.get("query"),
"country": data.get("country"),
"countryCode": data.get("countryCode"),
"region": data.get("region"),
"regionName": data.get("regionName"),
"city": data.get("city"),
"lat": data.get("lat"),
"lon": data.get("lon"),
"timezone": data.get("timezone"),
"isp": data.get("isp"),
"org": data.get("org"),
"as": data.get("as"),
"hostname": data.get("hostname"),
"security": data.get("security", {}),
"currencyCode": data.get("currencyCode"),
"currencyConverter": data.get("currencyConverter"),
}

if __name__ == "__main__":
target_ip = "181.188.132.167"
try:
result = geolocate_ip(target_ip)
print("解析的地理数据：")
for k, v in result.items():
print(f" {k}: {v}")
# 示例用法：
# if result["security"].get("is_proxy") or result["security"].get("is_vpn"):
# 标记用户/会话以进行额外验证。
except Exception as e:
# 生产：与您的日志/警报集成
print(f"地理位置错误：{e}")

节省您时间的生产注意事项

身份验证头：始终发送 Authorization: Bearer YOUR_API_KEY。不要将密钥作为查询参数附加到地理位置端点。
超时：对外部服务的网络调用可能会停滞；设置合理的连接/读取超时。在 Python 请求中，传递 timeout=(connect, read)。
缓存：许多 IP 在会话中重复。根据您的风险姿态缓存每个 IP 的查找（例如，在 Redis 中），并设置适当的 TTL。这可以减少延迟并保留配额。
时区：时区返回一个 IANA 字符串（例如，America/La_Paz）。直接与 Python 的 zoneinfo 等库一起使用进行时间计算和格式化。
坐标：lat/lon 是十进制度数。如果您在地图上显示它们，请相应地投影并防御性地处理缺失字段。
安全标志：将 is_proxy、is_vpn、is_tor 和 threat_level 视为信号，而不是唯一证据。在执行之前与您自己的启发式结合。
数据完整性：某些字段（zip、areaCode、dmaCode、languageCode）可能为空或为 null。使用之前始终检查 null。
使用计划：Zyla 使用订阅 + 配额。对于您在 Zyla 的第一个 API，您可以从 7 天的试用或 50 次请求开始。跟踪您的使用情况并根据需要扩展您的计划。

您本周可以交付的常见地理位置用例

欺诈和滥用检查：
- 当 security.is_proxy、security.is_vpn 或 security.is_tor 为真时，阻止或挑战注册。
- 当区域与过去的行为不匹配时，对登录进行更高风险评分。
区域功能限制：
- 按 countryCode 或 continentName 启用/禁用功能。
- 根据城市/地区为高流量市场重定向到本地化内容。
地方和货币：
- 应用时区以进行计划通知和日期格式化。
- 使用 currencyCode 和 currencyConverter 显示大致的本地定价（明确标记为指示性费率）。
操作分析：
- 使用国家、regionName、isp 增强日志以进行流量报告和容量规划。

通过 MCP 从 AI 代理调用 API

Zyla 上的每个 API 也可以从兼容 MCP 的工具（例如，Claude Code、Cursor、Windsurf）调用。使用 MCP 端点：MCP。

高级步骤：

使用 Zyla MCP 端点配置您的 MCP 客户端：https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
使用您的 Zyla API 密钥进行授权。
从您的兼容 MCP 的环境中，通过指定上述相同的请求路径和参数调用地理追踪 API 的地理位置端点。

这使得 AI 编码代理能够在您的开发工作流程中协调对地理位置端点的调用，同时重用相同的 API 密钥。

故障排除清单

401/403 错误：验证您是否在地理追踪 API 页面上订阅，并发送 Authorization: Bearer YOUR_API_KEY。
意外字段：并非所有属性都是保证的。防止 null 或空字符串，特别是 zip、areaCode、dmaCode、languageCode。
响应处理：在消费字段之前检查 data["status"] == "success"。
吞吐量：为每个 IP 添加缓存，并为瞬态网络问题添加回退/重试逻辑。监控您的订阅使用情况，以避免达到配额。

快速参考

市场：zylalabs.com
地理追踪 API 页面：地理追踪 API
身份验证：Authorization: Bearer YOUR_API_KEY
端点（GET）：https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation?ip=YOUR_IP
首次 API 访问：7 天试用或 50 次请求（无免费计划）。有关详细信息，请参阅 API 页面。