GeoIP2 JavaScript 客户 API

如果您是 GeoIP Legacy 客户,请参考我们的 《GeoIP2 的新特点》 文件,了解从 GeoIP Legacy 到 GeoIP2 之间变化的总体概况。

服务计划

要购买使用 API 的查询次数,请访问我们的网络服务订购页面

注册

使用服务的所有域名均需进行注册。新用户可以购买网络服务查询次数,从而获取账户并注册域名。现有账户持有者可以直接注册域名

JavaScript

为了使用这项服务,您的页面上必须包括以下 JavaScript:

教程

如果需要逐步了解如何使用这个 API 完成几项不同任务,请参阅我们的 GeoIP2 JavaScript 教程

API

导入 geoip2.js 脚本后,您的命名空间中将出现 geoip2 模块。该模块提供三个函数:

函数 描述
geoip2.country(onSuccess, onError, options) 使用所在运行机器的相关可路由 IP 地址,呼叫 GeoIP2 Precision:Country 终端。
geoip2.city(onSuccess, onError, options) 使用所在运行机器的相关可路由 IP 地址,呼叫 GeoIP2 Precision:City 终端。
geoip2.insights(onSuccess, onError, options) 使用所在运行机器的相关可路由 IP 地址,呼叫 GeoIP2 Precision:Insights 终端。

参数

所有函数均使用同样三个变量:

  • 如果成功,该函数呼叫 onSuccess。传给回调的第一个参数中含有一个与 MaxMind Precision 网络服务 API 的某个响应的输出项匹配的对象。

    除了网络服务 API 文件中列出的属性外,该对象还具有 most_specific_subdivision 性质,可以访问最具体的可用分区对象。在 Internet Explorer 8 之外的浏览器上,则使用 defineProperty,将其作为非枚举类性质来实施。

  • 如果出现错误,该函数将以错误对象作为参数,呼叫 onError
  • options 参数是一个含有用于服务的旗标的对象。该参数被预留供今后使用。目前并没有选填项。

成功响应

一个成功响应由单个 JavaScript 对象组成。该对象含有一组键/值对,其中的键是 countrytraits 之类,值则是对象或对象数组。

虽然按照记录,我们的 REST API 将省略有关键,但我们会为 JavaScript API 填入缺失的数据结构。这极大地简化了围绕响应的工作,因为你无需在使用前检查数据结构是否存在。

当性质的值可以是对象或数组时,我们将根据需要添加一个空对象或数组。例如,如果你呼叫 city() 方法,而来自 MaxMind 服务器的响应根本没有 city 键,将用下列方式填入响应:

如果响应中没有 subdivisions 键,您将得到以下响应:

样本代码

错误

所有错误均被纳入一个 JavaScript 对象,作为第一个参数传给 onError 函数。该对象含有两个键:codeerrorcode 是一个不会更改的机读错误代码。error 是人类可读的错误描述。

代码 HTTP 状态 描述
IP_ADDRESS_INVALID 400 请求无效

你没有提供一个有效的 IPv4 或 IPv6 地址。

IP_ADDRESS_REQUIRED 400 请求无效

您没有提供 IP 地址,而这是必填字段。

IP_ADDRESS_RESERVED 400 请求无效

您所提供的 IP 地址属于保留或私有的范围。

IP_ADDRESS_NOT_FOUND 404 无法找到文件

所提供的 IP 地址不在数据库中。

DOMAIN_REGISTRATION_REQUIRED 401 未授权

您网站的域名尚未注册

QUERY_FORBIDDEN 401 未授权

您试图访问的服务或特点超出了您的服务计划范围。

OUT_OF_QUERIES 402 需要付款

您提供的许可证密钥的查询次数已经用尽。请 购买更多查询,以使用这项服务。

PERMISSION_REQUIRED 403 禁止访问

您无权使用该服务。请联系 support@maxmind.com 获取更多信息。

HTTP_TIMEOUT (无)

向 GeoIP2 网络服务的请求已经超时。

HTTP_ERROR (无)

向 GeoIP2 网络服务提出请求时出现错误。

版本

本文件包括 GeoIP2 JavaScript API 的版本 2.1。MaxMind 发布 JavaScript API 的新版本时,均将使用一个新路径,这样旧的 JavaScript 文件始终可以访问。例如,假如我们发布 JavaScript API 的版本 42.6,其路径将是 /js/apis/geoip2/v42.6/geoip2.js

不过,在任何时候,我们都仅为最新版本的 JavaScript API 提供支持。

请注意,JavaScript API 和网络服务 REST API 分别采用不同版本。当我们添加新的特性或是需要打破与 JavaScript API 此前版本的向后兼容性时,我们会对 JavaScript API 的版本进行跳跃编号。

JavaScript API 的 2.1 版所使用的是 GeoIP2 Precision 网络服务 REST API的 2.1 版。

发布说明

我们的《发布说明》记录了 JavaScript API 中的有关修改。

浏览器支持

对于目前由其创始人支持的所有浏览器版本,MaxMind 承诺予以支持。如果创始人提供多个层面的支持,我们对浏览器的支持只会贯穿首个支持阶段。例如,微软有两个支持阶段:主流和扩展。我们承诺会在整个主流支持阶段为浏览器提供支持。对于任何不再得到其创始人支持的浏览器,我们保留随时停止支持的权利。

以下是我们用来测试过这个 API 的浏览器列表:

浏览器 平台 版本
Chrome Windows XP, 7, 8 最近发布的两个稳定版
Linux
OS X 10.6
Firefox Windows XP, 7, 8, 8.1 4+
Linux
OS X 10.6
Internet Explorer Windows XP 8
Windows 7 8, 9, 10, 11
Windows 8 10
Windows 8.1 11
Safari Windows 7 5
OS X 10.6 5
OS X 10.8 6
OS X 10.9 7
Opera Windows XP, 7 11-12
Linux 12
(本机浏览器) iOS 4.3, 5, 5.1, 6, 6.1, 7, 7.1
(本机浏览器) Android 4.0, 4.1, 4.2, 4.3