如何使用BigDataCloud：API、密钥与首次请求

BigDataCloud是一个位置智能平台，提供IP地理定位、反向地理编码、电话和电子邮件验证以及网络智能API。该平台围绕一个简单的理念构建：您应该能够在几分钟内开始使用准确的位置数据，而无需信用卡。本指南将带您了解使用BigDataCloud的实际步骤，从理解API包到发出第一个请求并避免常见的合理使用错误。

BigDataCloud提供什么

如何使用BigDataCloud：API、密钥与首次请求 - BigDataCloud提供什么.

如何使用BigDataCloud：API、密钥与首次请求 - BigDataCloud提供什么。

BigDataCloud将其服务组织为四个重点API包：

• IP地理定位 — 将IP地址映射到城市、国家、坐标、置信区域、ISP、ASN以及VPN、代理或Tor检测等危险标志。
• 反向地理编码 — 将纬度和经度坐标转换为人类可读的地址或位置描述。
• 验证 — 验证电话号码和电子邮件地址。
• 网络智能 — 探索网络数据，如前缀、ASN和相关基础设施。

每个包都包含免费层级，每个计划都包含所有端点和所有响应字段。您只需为数量付费，而不是为功能解锁付费。该平台还提供REST和GraphQL访问，这在IP地理定位提供商中并不常见。

第1步：无需账户即可探索免费客户端API

如何使用BigDataCloud：API、密钥与首次请求 - 第1步：无需账户即可探索免费客户端API。

BigDataCloud提供一组免费的客户端API，无需账户和API密钥。这些API旨在直接在浏览器或移动应用中运行。主要的免费客户端端点包括：

• 客户端反向地理编码
• 客户端IP检测
• 漫游检测

要尝试这些，请访问BigDataCloud网站上的API包页面，打开API端点部分，然后点击所需端点上的查看文档。文档包含示例请求和响应格式，您可以立即测试。

免费的客户端反向地理编码API对于已经使用HTML5 Geolocation API的Web项目特别有用。您可以在客户端检索用户的当前坐标，并将其转换为位置描述，而无需任何服务器端基础设施。

免费客户端反向地理编码API的合理使用规则

免费的客户端反向地理编码端点有严格的使用规则，很容易意外违反：

• API必须仅转换从调用客户端设备获得许可的当前地理坐标。
• 您不得传递预先存储的坐标或属于其他用户的坐标。
• 坐标必须反映调用设备的最佳已知位置，通过客户端地理定位服务（如GPS或Wi-Fi定位）检索。
• API调用必须源自检索坐标的同一客户端。您不得在客户端检索坐标，将其发送到服务器，然后从该服务器调用API。

违反这些规则可能导致您的IP地址被禁止使用BigDataCloud的所有免费API，请求将返回402错误。如果您需要服务器端反向地理编码，请改用专用的服务器端端点。它返回相同的数据，每月包含50,000次免费查询，并且需要API密钥。

第2步：注册免费API密钥

如何使用BigDataCloud：API、密钥与首次请求 - 第2步：注册免费API密钥。

要访问全套端点，请使用BigDataCloud网站右上角的注册按钮创建一个免费账户。注册过程大约需要30秒，不需要信用卡。

注册后，您将收到一个唯一的API密钥。BigDataCloud指出，密钥在其API服务器网络中传播可能需要长达10分钟。当密钥激活时，您将收到电子邮件通知。如果您在传播完成之前尝试发出请求，可能会看到身份验证错误，因此值得等待确认电子邮件。

免费层级对于开发和适度生产使用来说足够慷慨。根据API包的不同，免费配额从每月10,000到50,000次调用不等。

第3步：发出您的第一个IP地理定位请求

如何使用BigDataCloud：API、密钥与首次请求 - 第3步：发出您的第一个IP地理定位请求.

一旦您的密钥激活，您就可以向IP地理定位端点发出REST请求。基本请求如下所示：

GET /data/ip-geolocation?ip=1.1.1.1&key=YOUR_KEY

完整的REST响应返回约2 KB的数据，包含50多个字段，包括：

• IP地址
• 位置详细信息，如城市、国家代码、纬度和经度
• 置信度分数
• 网络信息，包括ISP、ASN和前缀
• 标记VPN、代理或Tor使用的危险报告

如果您只需要几个字段，GraphQL端点可以显著减小响应大小。例如，仅请求城市、国家代码和置信度，返回约200字节而不是2 KB：

query {
  ipGeolocation(ip: "1.1.1.1") {
    location { city countryCode }
    confidence
  }
}

REST和GraphQL以相同的价格返回相同的底层数据。GraphQL只是一种请求您确切需要的字段的方式，这对于移动应用或响应大小很重要的大批量集成非常有价值。

第4步：使用官方SDK和AI集成

BigDataCloud为主要编程语言提供官方SDK，带有类型化模型和工作示例。这减少了将API集成到生产应用程序中所需的样板代码。

该平台还支持MCP（模型上下文协议）集成，允许AI助手（如Claude、Cursor和VS Code）直接对IP进行地理定位、反向地理编码坐标和验证数据。基本的MCP配置如下所示：

{
  "bigdatacloud": {
    "command": "npx",
    "args": ["-y", "@bigdatacloudapi/mcp-server"]
  }
}

这对于构建需要位置上下文而无需编写自定义API粘合代码的AI驱动应用程序的开发人员非常有用。

实际用例

BigDataCloud的API适用于几种常见工作流程：

• 欺诈预防 — 在处理交易之前，使用危险报告标记与VPN、代理或Tor退出节点关联的IP。
• 本地化 — 对访问者的IP进行地理定位，以提供特定区域的内容、货币或语言。
• 日志分析 — 使用位置和网络智能丰富服务器日志，以了解流量来源。
• 移动应用 — 使用客户端反向地理编码将GPS坐标转换为可读位置，而无需服务器往返。
• AI助手 — 连接MCP服务器，为AI工具提供实时位置智能能力。

验证您自己的IP和网络数据

当您使用IP地理定位API时，值得检查您自己的浏览器和网络揭示了什么。像BrowserScan这样的工具允许您运行浏览器指纹分析、DNS和WebRTC泄漏测试，以及IP地址查找，包括地理定位、ISP和代理检测。这对于确认VPN没有泄漏您的真实IP或您的浏览器指纹看起来真实非常有用，然后再在生产中依赖地理定位数据。要更深入地了解位置数据如何用于分析和决策，请参阅本指南：位置智能。

在免费客户端和服务器端API之间选择

场景	推荐API
使用HTML5 Geolocation的Web应用，无后端	免费客户端反向地理编码
具有原生位置SDK的移动应用，无后端调用	免费客户端反向地理编码
服务器需要对存储的或第三方坐标进行反向地理编码	带API密钥的服务器端反向地理编码
大批量生产IP地理定位	带API密钥的服务器端IP地理定位
移动或嵌入式系统的最小响应大小	GraphQL端点

关键区别在于坐标来自哪里以及API调用发生在哪里。如果两者都发生在同一客户端设备上，并且使用用户的当前位置，则免费客户端端点适用。任何其他模式都需要服务器端API。

相关阅读

• 什么是个人VPN？如何选择和测试 - 了解个人VPN的作用、如何保护您的IP和流量、如何选择正确的服务以及如何验证您的连接是否泄漏。

来源和进一步阅读

• BigDataCloud API入门 - 获得专利的IP地理定位，每日公开准确性基准。免费开始，可扩展到数十亿。
• 免费客户端反向地理编码API：使用指南和合理使用政策 - 了解如何负责任地使用BigDataCloud的免费客户端反向地理编码API。遵循我们的合理使用政策以获得可靠访问，或探索服务器端替代方案。
• BigDataCloud - 精确IP地理定位和反向地理编码API - 获得专利的IP地理定位，每日公开准确性基准。置信区域、危险检测、ASN智能。免费开始。

常见问题解答

开始使用BigDataCloud需要信用卡吗？

不需要。免费层级不需要信用卡，也没有承诺。您可以注册、接收API密钥，并在几分钟内发出您的第一个请求。

API密钥激活需要多长时间？

BigDataCloud指出，密钥在其服务器网络中传播可能需要长达10分钟。当您的密钥激活时，您将收到电子邮件。

如果我违反免费客户端反向地理编码API的合理使用政策会怎样？

您的IP地址可能会被禁止使用BigDataCloud的所有免费API，请求将返回402错误。您可以联系BigDataCloud请求审查。

我可以从服务器使用免费客户端反向地理编码API吗？

不可以。调用必须源自检索坐标的同一客户端设备。对于服务器端使用，请切换到服务器端反向地理编码API，该API每月包含50,000次免费查询。

BigDataCloud上的REST和GraphQL有什么区别？

两者以相同的价格返回相同的数据。REST返回包含50多个字段的完整响应对象，而GraphQL允许您仅请求所需的字段，将响应大小从约2 KB减少到低至200字节。

BigDataCloud提供什么免费配额？

免费配额根据API包的不同，从每月10,000到50,000次调用不等。付费计划从青铜级的每月19.95美元起。

结论

BigDataCloud旨在让您在几分钟内从注册到工作API调用。首先使用免费客户端端点探索数据而无需账户，然后在需要服务器端访问或更高容量时注册密钥。注意免费客户端反向地理编码API的合理使用政策，因为违规可能导致IP禁令。设置完成后，选择REST获取完整响应或GraphQL获取最小负载，如果您正在构建更大的应用程序，请考虑官方SDK或MCP集成。

有关IP和网络工具更广泛生态系统的更多信息，请参阅此BrowserLeaks定价和免费工具的比较，或了解如何运行您自己的Nmap端口扫描。