GeoIP2 Precision 网络服务

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

客户端 API

MaxMind API

如果您使用下表中列出的语言,我们强烈建议您使用官方支持库。 无需与 REST API 界面直接互动。

语言或框架 包存储库 文档 版本控制
.NET (C#) NuGet GitHub Pages GitHub
Java Maven Central Repository GitHub Pages GitHub
JavaScript(浏览器) API 文件
Perl CPAN MetaCPAN GitHub
PHP Packagist GitHub Pages GitHub
Python PyPI 阅读文档 GitHub

第三方 API

警告!MaxMind 为这些 API 提供支持,也并未审核其代码。 使用者请自行承担风险。
语言或框架 API 名称 包存储库 文档 版本控制
Go geoip2 GoDoc GitHub
Node.js geoip2ws npm npm GitHub
Ruby Geoip2 RubyGems.org RubyDoc.info GitHub

每项服务的URI

每项服务所使用的 URI 如下所示。请用您所查询的地址替代 {ip_address}。所有 API 呼叫均应采用 HTTP GET

服务 URI 内容 – 类型
Country https://geoip.maxmind.com/geoip/v2.1/country/{ip_address} application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1
City https://geoip.maxmind.com/geoip/v2.1/city/{ip_address} application/vnd.maxmind.com-city+json; charset=UTF-8; version=2.1
Insights https://geoip.maxmind.com/geoip/v2.1/insights/{ip_address} application/vnd.maxmind.com-insights+json; charset=UTF-8; version=2.1

geoip.maxmind.com 主机名将自动挑选地理位置离您最近的数据中心。 在某些情况下,该数据中心未必能向您提供最佳服务。 您可以直接试用以下主机名,查看哪个对您来说性能最佳:

  • geoip-us-east.maxmind.com (美国弗吉尼亚州)
  • geoip-us-west.maxmind.com (美国加州圣何塞)
  • geoip-eu-west.maxmind.com (英国伦敦)
  • geoip-as-southeast.maxmind.com (新加坡)

IP 地址

IP 地址可以采用 IPv4 或 IPv6 地址。Ipv4 地址应该采用标准的点分四段格式传送,例如 1.2.3.4。 IPv6 也应该以字符串传送。 我们建议采用 RFC 5952 中描述的规范形式,例如 2001:db8::1:0:0:1;不过,我们会处理任何有效的 Ipv6 字符串表达。

您也可以使用字符串 me 作为 IP 地址。 在这种情况下,将会返回您发出查询的 IP 地址的记录。 如果您的应用缺少访问自己公共 IP 地址的简便途径(例如,当进行查询的系统处于一个 NAT 后时),会很有用。

请求头

Accept 请求头完全属于选填项。 如果您确实要加入这个请求头,则必须接受以下规定中的一种:

  • application/json
  • application/vnd.maxmind.com-country+json
  • application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1

用适当的服务类型替代“country”。任何其他 MIME 类型的请求均将导致 415 Unsupported Media Type 错误。

如果您在自己的客户端代码中设定 Accept-Charset 请求头,则必须接受 UTF-8 字符集。 如果不接受,您将得到 406 Not Acceptable 的响应,因为该数据只能通过 UTF-8 提供。

授权

必须使用 HTTP 授权头进行授权。 用户名是您的 MaxMind 用户 ID。 密码是您的 MaxMind 许可证密钥。 您必须就我们的某项网络服务申请试用账户或进行订购,才能获得用户 ID 和许可证密钥。

我们使用 HTTP 基本验证,但是要求验证的 API 仅能通过 HTTPS 获取,因此绝对不会以未加密方式传输凭证信息。 如果您试图通过 HTTP 使用该服务,您将得到 403 Forbidden HTTP 响应。

响应头

根据您所使用的服务,其成功响应有不同的Content-Type 头。

也可能随 Content-Type 返回错误信息,设定为 application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.1。 如果是这种情况,响应体中将包含带有 codeerror 两个键的 JSON 文档。 如需更多信息,请参阅 错误部分

响应中也总会含有一个 Content-Length 头。

响应体

所有服务均以 JSON 文档返回数据。所返回的文档均由一个对象(亦即映像或哈希)构成。 对象中的每个键也相应地映射一个对象或对象数组。 文件的顶层结构看起来会与下文类似:

具体的顶层键组将根据您所使用的 GeoIP2 Precision 服务而有所不同。 如果一个键映射一个未定义值或空值,则不会包括在 JSON 对象中。 这同时适用于顶层键及其映射对象。

文档中返回的数据将采用 UTF-8 编码。

IP 地理定位的使用

IP 地理定位在本质上缺乏准确性。地点通常接近人口的中心。 由 GeoIP 数据库提供的任何地点均不应用来确认某个具体的地址或住户。

语言

下面列出的许多对象都包括一个 names 键。 该键的值是一个相应的对象,会将区域代码映射到采用适当语言和脚本的名称。

目前,该网络服务可以返回下列区域代码:

代码 语言 备注
de 德语
en 英语 英语名称中可能仍然包括重音符号,前提是这些符号属于英语接受的拼写方式。 换言之,英语不表示 ASCII。
es 西班牙语
fr 法语
ja 日语
pt-BR 巴西葡萄牙语
ru 俄语
zh-CN 中文(简体)

如果一个对象有任何名称数据,则 en 将是 names 对象中的键之一。 不会保证其他任何语言。 但是,对于一个给定对象,我们也可能根本没有任何名称数据。

city

一个JSON 对象,含有 IP 地址相关城市的细节信息。

包括在……
值类型 描述 Country? City? Insights?
confidence 整数 0 – 100之间的某个值,代表我们对城市是否正确的置信度。
geoname_id 整数

GeoNames 为城市指定的独特标识符。

names JSON 对象(映射)

从区域代码(例如 en)到该功能的本地化名称的映射。

continent

一个JSON 对象,含有 IP 地址相关大洲的信息。

包括在……
值类型 描述 Country? City? Insights?
code 字符串(2)

IP 地址相关大洲的两位字符代码。 可能的代码包括:

  • AF – 非洲
  • AN – 南极洲
  • AS – 亚洲
  • EU – 欧洲
  • NA – 北美洲
  • OC – 大洋洲
  • SA – 南美洲
geoname_id 整数

GeoNames 为大洲指定的独特标识符。

names JSON 对象(映射)

从区域代码(例如 en)到该功能的本地化名称的映射。

country

一个JSON 对象,含有 MaxMind 认定的终端用户所在国家的细节信息。

包括在……
值类型 描述 Country? City? Insights?
confidence 整数 0 – 100之间的某个值,代表我们对国家是否正确的置信度。
iso_code 字符串(2) IP 地址相关国家的两位字符 ISO 3166-1 国家代码。
geoname_id 整数

GeoNames 为国家指定的独特标识符。

names JSON 对象(映射)

从区域代码(例如 en)到该功能的本地化名称的映射。

location

一个 JSON 对象,含有 IP 地址相关地点的具体信息。

包括在……
值类型 描述 Country? City? Insights?
accuracy_radius 整数 与 IP 地址相关的地理实体(所在国家、分区、城市或邮政编码)经纬度周边的大致准确性半径(以公里为单位)。我们有 67% 的置信度,相信终端用户会处于准确性半径以及经纬度坐标所界定的区域内。
average_income 整数 与 IP 地址相关的平均年收入(以美元计)。
latitude 十进制 与 IP 地址相关的邮政编码、城市、分区或所在国家的大致纬度。*
longitude 十进制 与 IP 地址相关的邮政编码、城市、分区或所在国家的大致经度。*
metro_code 整数 与 IP 地址相关的大城市代码。这仅限于美国的 IP 地址。 MaxMind 返回的 大城市代码与 DoubleClick 所用代码相同
population_density 整数 每平方公里人口数量估测。
time_zone 字符串 与地点相关的时区,具体则根据 IANA 时区数据库规定,例如“美国/纽约”。

* 坐标不够准确,不应用来确认某个具体的街道地址或住户。 为了更好地呈现准确性,在显示经纬度时请包含 accuracy_radius(准确性半径),并且标明坐标信息是指较大的地理区而非确切地点。

postal

一个 JSON 对象,含有 IP 地址相关邮政编码的细节信息。

包括在……
值类型 描述 Country? City? Insights?
code 字符串 与 IP 地址相关的邮政编码。可以为处于澳大利亚、加拿大、法国、德国、意大利、西班牙、瑞士、英国和美国的部分 IP 地址提供这项信息。 对于加拿大的邮政编码,我们返回前三个字符。 对于英国的邮政编码,我们返回前 2-4 个字符(去程代码)。
confidence 整数 0 – 100之间的某个值,代表我们对邮政编码是否正确的置信度。

registered_country

一个JSON 对象,含有 ISP 为 IP 地址注册所在国家的细节信息。

包括在……
值类型 描述 Country? City? Insights?
iso_code 字符串(2) IP 地址相关国家的两位字符 ISO 3166-1 国家代码。
geoname_id 整数

GeoNames 为国家指定的独特标识符。

names JSON 对象(映射)

从区域代码(例如 en)到该功能的本地化名称的映射。

represented_country

一个JSON 对象,含有 IP 地址用户所代表国家的细节信息。 例如,某个海外军事基地所代表的国家。

包括在……
值类型 描述 Country? City? Insights?
iso_code 字符串(2) IP 地址相关国家的两位字符 ISO 3166-1 国家代码。
geoname_id 整数

GeoNames 为国家指定的独特标识符。

names JSON 对象(映射)

从区域代码(例如 en)到该功能的本地化名称的映射。

type 字符串 代表国家的类型目前仅限于军事,但今后可能包括其他类型。

subdivisions

一个 JSON 对象的数组。其中每个对象都包含 IP 地址所在国家中某个分区的细节信息。 从最大到最小安排分区顺序。

例如,对英国牛津的响应中,将为“英格兰”创建一个对象,作为 subdivisions 数组中的第一个要素,而“牛津郡”的对象则是第二个要素。 美国明尼安波利斯的 subdivisions 数组中则将含有为“明尼苏达州”创建的单独对象。

包括在……
值类型 描述 Country? City? Insights?
confidence 整数 0 – 100之间的某个值,代表我们对区域是否正确的置信度。
geoname_id 整数

GeoNames 为区域指定的独特标识符。

iso_code 字符串 一个最多三个字符的字符串,针对与 IP 地址相关的区域,提供其 ISO 3166-2 代码中的区域部分。
names JSON 对象(映射)

从区域代码(例如 en)到该功能的本地化名称的映射。

traits

一个JSON 对象,含有与 IP 地址相关的一般特征。

包括在……
值类型 描述 Country? City? Insights?
autonomous_system_number 整数 与 IP 地址相关的 自治系统号
autonomous_system_organization 字符串 与 IP 地址的注册自治系统号相关的组织。
domain 字符串 与 IP 地址相关的二级域名。 这些域名类似于“example.com”或“example.co.uk”,但不会是“foo.example.com”。
ip_address 字符串 所请求的 IP 地址。
is_anonymous 布尔 如果 IP 地址属于任何类型的匿名网络,则该值为真。
is_anonymous_proxy 布尔 已被弃用。请考虑使用我们的匿名工具服务输出项,例如 is_anonymousis_anonymous_vpnGeoIP2 Anonymous IP 数据库GeoIP2 Precision Insights 服务均可提供这些匿名服务输出项。
is_anonymous_vpn 布尔 如果 IP 地址属于某个匿名 VPN 网络,则该值为真。
is_hosting_provider 布尔 如果 IP 地址属于某个托管提供商,则该值为真。
is_public_proxy 布尔 如果 IP 地址属于某个公共代理,则该值为真。
is_satellite_provider 布尔 已被弃用。
is_tor_exit_node 布尔 如果 IP 地址是一个 Tor 出口节点,则该值为真。
isp 字符串 与 IP 地址相关的 ISP 名称。
organization 字符串 与 IP 地址相关的机构名称。
user_type 字符串

与 IP 地址相关的用户类型。这将是下列的某个值。

  • business
  • cafe
  • cellular
  • college
  • content_delivery_network
  • dialup
  • government
  • hosting
  • library
  • military
  • residential
  • router
  • school
  • search_engine_spider
  • traveler

maxmind

一个 JSON 对象,包含与您的 MaxMind 账户相关的信息。

包括在……
值类型 描述 Country? City? Insights?
queries_remaining 整数 可供被呼叫端点使用的剩余查询的大概数量。

作为数据库、映射、字典或哈希键的返回值

我们强烈建议,请不要将任何 names 字段中的值用作数据库或映射/字段/哈希数据结构中的键。

这些名称在不同的发布版本中可能会有所修改。我们建议从下列各项中选择一项使用:

数据对象 建议使用的键
city geoname_id
continent codegeoname_id
Country、registered_country 以及 represented_country iso_codegeoname_id
postal code
subdivisions iso_codegeoname_id

输出项示例

以下是一个含有所有可能字段的 Insights 输出项示例。

命令行(curl)示例

可以使用简单的命令行 HTTP 客户端 curl 去访问网络服务。 用 -u 旗标传送 HTTP 基本验证头,向网络服务提供您的凭据信息。

请用您的 用户 ID 与许可证密钥 替代 {user_id}{license_key}

就您的 IP 地址检索数据

就任意一个 IP 地址检索数据

用您希望查询的 IP 地址替代 {ip_address}

请用您的 用户 ID 与许可证密钥 替代 {user_id}{license_key}

就您的 IP 地址检索数据

就任意一个 IP 地址检索数据

用您希望查询的 IP 地址替代 {ip_address}

请用您的 用户 ID 与许可证密钥替代 {user_id}{license_key}

就您的 IP 地址检索数据

就任意一个 IP 地址检索数据

用您希望查询的 IP 地址替代 {ip_address}

错误

当服务器返回错误信息(4xx 或 5xx)时,响应体中可能包括一个 JSON 文档。 该文件是带有 codeerror 键的单个对象。 code 字段是一个机用的静态错误代码。 任何给定代码的价值永远都不会变化,虽然代码可以添加或移除。 error 字段是人类可读的错误描述,随时可以修改。

并非所有错误都包括一个 JSON 体。内容协商中的错误不会包括主体,很多 5xx 错误也不会,通常这些错误都发生在我们网络服务请求处理代码之外。 在试图将主体作为 JSON 解码之前,您应该先检查错误响应的 Content-Type 类型。

除了下文记录的错误外,客户端代码也应该做好处理任何有效的 HTTP 4xx 或 5xx 状态码的准备。

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

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

IP_ADDRESS_REQUIRED 400 请求无效

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

IP_ADDRESS_RESERVED 400 请求无效

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

IP_ADDRESS_NOT_FOUND 404 无法找到文件

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

AUTHORIZATION_INVALID 401 未授权

您在授权页头中提供的 MaxMind 用户 ID 及/或许可证密钥无效。

LICENSE_KEY_REQUIRED 401 未授权

您没有在 授权页头中提供 MaxMind 许可证密钥

USER_ID_REQUIRED 401 未授权

您没有在授权页头中提供 MaxMind 用户 ID

OUT_OF_QUERIES 402 需要付款

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

PERMISSION_REQUIRED 403 禁止访问

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

(none) 415 不支持媒体类型

您的请求包括一个不受支持的 Content-Type 页头。 对于 GET 请求,这意味着网络服务无法返回该类型的内容。 对于 PUTPOST 查询,这意味着网络服务无法解析该类型的请求体。

(none) 503 服务不可用

网络服务服务器出现问题。您可以稍后再次尝试这一请求。

发布说明

我们的《发布说明》记录了 GeoIP2 Precision 网络服务的有关修改。

版本

GeoIP2 Precision 网络服务使用由两部分组成的版本号。我们目前的发布是版本2.1。 在可见的将来,主版本号将保持为2;除非我们发布一个全新产品(“GeoIP3”),否则不会修改。

只会在网络服务出现重大修改时,才会修改次版本号。 重大修改是破坏遵循本页文档规定的客户端代码的修改。 重大修改包括修改现有字段的类型、完全删除一个字段或修改 URI。

对网络服务的所有修改均将在 GeoIP2 发布说明 中记录,无论版本号码是否变化。

下列修改 被视为重大修改,也不会随之修改版本号码。

  • 在结构的顶层或在某个具体对象(例如 country 或 city)中增加一个新的字段。 写客户端代码时应该允许新字段的出现。
  • user_type 这类的枚举字段添加新的值。 请注意,这也适用于国家代码、国家分区代码、时区等字段。
  • 为本地化名称添加一个新语言。我们今后可能添加其他的区域代码。
  • 添加或去除错误代码,及/或修改错误的主体类型。 客户端代码应该随时检查 Content-Type 页头,查找任何错误响应。 客户端代码还应该做好处理任何有效的 HTTP 4xx 或 5xx 状态码的准备。
  • 添加一项新服务。如果我们添加一项 GeoIP2 Inter-Galactic 服务,我们将使用 /geoip/v2.1/inter-galactic 之类的新路径。 这应该不会破坏任何现有的客户端代码。