GeoIP2 精准服务(网络API)

如果您是老客户,请前往 “GeoIP新特性”

客户端 API

MaxMind API

如果您使用的语言在以下列表中,我们建议您使用我们的官方版本。

语言/框架 存储 开发者文档 版本控制
.NET (C#) NuGet GitHub Pages GitHub
Java Maven Central Repository GitHub Pages GitHub
Perl CPAN MetaCPAN GitHub
PHP Packagist GitHub Pages GitHub
Python PyPI Read the Docs GitHub

第三方 API

警告! MaxMind不对下列API负责以及提供技术支持。
语言/构架 API 名字 存档 开发者文档 版本控制
Node.js nodejs-geoip2ws npm npm GitHub
Ruby Geoip2 RubyGems.org RubyDoc.info GitHub

HTTP 请求URI

HTTP请求的URI如下。请用您需要查询的IP替换 {ip_address}。所有的API 呼叫都需要用 HTTP GET.

服务类型 URI 回复格式
国家 https://geoip.maxmind.com/geoip/v2.1/country/{ip_address} application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1
城市 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

IP 地址

IPv4 应该使用如下格式:1.2.3.4. IPv6 应该用string输出,我们推荐  RFC 5952, 例如: 2001:db8::1:0:0:1

您也可以用me作为IP输入,这样将使用您的当前IP地址。

请求 Header

接受 header 不是必须包含的. 如果您决定添加一个,必须是如下中的一个:

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

 “country” 可以替换为任何您需要的服务类型. 一个不存在的服务类型会返回 415 Unsupported Media Type 错误.

如果您使用了 Accept-Charset header ,您必须支持 UTF-8。 如果您不支持,会返回 406 Not Acceptable,因为这部分数据都是 UTF-8.

权限/认证

 HTTP 权限 header 是必须包含的. 用户名为您的 MaxMind 用户 ID. 密码是您的 MaxMind 序列号. 此两者可以在购买或者申请试用之后获得。

我们使用 基础 HTTP 认证,但是有的 API 的认证只能通过HTTPS 。如果您使用HTTP链接这些服务,我们会返回 404 Not Found

返回 Headers

Content-Type header 会返回一个符合您舒服的返回值。

错误会用 Content-Type 中的 application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.1. 这种情况下,会返回一个JSON 文档,包含两组 keys, codeerror.请参阅    错误

The response will always include a Content-Length header as well.

返回主体

所有服务均返回 JSON 文档. 文档都会包含一个物件对象(哈希). 每个key对应一个或者一个array的物件,如下

具体情况将视您使用的服务而定。空白的array或者物件将不被包括在JSON文档中。

数据将使用UTF-8格式。

语言

很多如下的key包含一个names物件,对应为各个院。

目前,我们可以返回如下语言:

代码 语言 Notes
de German德语
en English英语 可以包含非ASCII字符。
es Spanish西班牙语
fr French法语
ja Japanese日语
pt-BR Brazilian Portuguese葡萄牙语
ru Russian俄语
zh-CN Chinese (Simplified)简体中文

如果一个返回包含names物件,那么必然包含英语。其他语言都是可能出现的,当然返回中也可能不包含任何names物件。

城市

一个包含IP相关城市信息的JSON物件。

包含在。。
Key 参数类型 说明 国家? 城市? Insights?
confidence integer 我们对于该对应的确信程度0-100.
geoname_id integer

 GeoNames 的ID

names JSON object (map)

本地化名称。

大洲

一个包含IP所在大洲的JSON物件。

包含在。。
Key 参数类型 说明 国家? 城市? Insights?
code string (2)

IP所在大洲的代码:

[xyz-ihs snippet=”ContinentCodeUL”]

geoname_id integer

 GeoNames 代码

names JSON object (map)

大洲名字.

国家

IP所在国家的JSON物件

包含在。。。
Key 参数类型 说明 国家? 城市? Insights?
confidence integer 我们对于国家正确的确信度0-100
iso_code string (2)  ISO 3166-1标准的国家代码
geoname_id integer

 GeoNames 代码

names JSON object (map) 名字

地理位置

IP所在地理位置的JSON物件。

包含在。。。
Key 参数类型 说明 国家? 城市? Insights?
accuracy_radius integer 准确半径
latitude decimal 经度
longitude decimal 纬度
metro_code integer 美国IP的 MetroCode。 我们使用的代码和Google相同
time_zone string 时区 IANA Time Zone Database标准 例如: “America/New_York”.

邮编

IP所在邮编的JSON物件

包含在…
Key 参数类型 说明 国家? 城市? Insights?
code string IP所在邮编。只在少数选择地区包含。
confidence integer 对于邮编正确的确信度0-100.

注册国家

IP所在ISP的注册国家。

包含在…
Key 参数类型 说明 国家? 城市? Insights?
iso_code string (2) ISO 3166-1标准国家代码
geoname_id integer

GeoNames 国家代码

names JSON object (map)

名称

代表国家

IP所在终端用户的代表国家. 例如,美驻韩军事基地的IP代表国家为美国。

包含在。。。
Key 参数类型 说明 国家? 城市? Insights?
iso_code string (2) ISO 3166-1 标准国家代码
geoname_id integer

 GeoNames 国家代码

names JSON object (map)

名称

type string 类型,例如“军事”

属地

JSON 物件的一个array.  IP所在国家所在属地,从大到小。

比如成都为四川-成都。

包含在。。
Key 参数类型 说明 国家? 城市? Insights?
confidence integer 我们的确信程度0-100
geoname_id integer

 GeoNames 代码

iso_code string ISO 3166-2 代码
names JSON object (map)

名称

相关信息

IP相关信息的JSON物件

包含在
Key 参数类型 说明 国家? 城市? Insights?
autonomous_system_number integer The autonomous system number associated with the IP address.
autonomous_system_organization string The organization associated with the registered autonomous system number for the IP address.
domain string IP所在二级域名.
ip_address string IP
is_anonymous_proxy boolean true 如果IP是一个匿名代理,否则不显示。
is_satellite_provider boolean true 如果IP是一个卫星IP
isp string IP所在ISP
organization string IP所属公司
user_type string

IP用户类型

  • business (商业)
  • cafe (餐厅)
  • cellular (手机)
  • college (大学)
  • content_delivery_network (服务网络)
  • dialup
  • government (政府)
  • hosting (服务器)
  • library (图书馆)
  • military (军事)
  • residential (居民)
  • router (网络分流)
  • school (学校)
  • search_engine_spider (搜索引擎)
  • traveler (游客)

maxmind

MaxMind账户相关信息。

包含在。。。
Key 参数类型 说明 国家? 城市? Insights?
queries_remaining integer 剩余查询数额

输出范例:

下面是一个案例:

命令行呼叫

网络服务可以用curl 命令行呼叫。加一个 -u 后缀即可输入您的账户相关信息以便查询。

请用你的用户ID和序列号替代: {user_id} 以及{license_key}。

获取您自己IP的相关信息

获取任意IP的相关信息

Replace {ip_address} with the IP address you wish to look up.

请用你的用户ID和序列号替代: {user_id} 以及{license_key}。

获取您自己IP的相关信息

获取任意IP的相关信息

Replace {ip_address} with the IP address you wish to look up.

请用你的用户ID和序列号替代: {user_id} 以及{license_key}。

获取您自己IP的相关信息

获取任意IP的相关信息

Replace {ip_address} with the IP address you wish to look up.

错误

有的错误会返回JSON 文档,包含两个keys code 以及 error. Code是错误代码,Error是错误原因。

 

除了以下的错误,您还应该因对任何相关的 HTTP 4xx 以及 5xx 错误代码。

代码 HTTP状态 说明
IP_ADDRESS_INVALID 400 Bad Request

非法IP地址

IP_ADDRESS_REQUIRED 400 Bad Request

没有IP地址

IP_ADDRESS_RESERVED 400 Bad Request

IP地址属于专有类型

IP_ADDRESS_NOT_FOUND 404 Not Found

IP不在数据库中

AUTHORIZATION_INVALID 401 Unauthorized

MaxMind 用户ID或者 序列号非法

LICENSE_KEY_REQUIRED 401 Unauthorized

没有提供MaxMind 序列号

USER_ID_REQUIRED 401 Unauthorized 没有提供MaxMind 用户ID
OUT_OF_QUERIES 402 Payment Required

查询数额已经用完

(none) 415 Unsupported Media Type

您的获取参数超越范围

(none) 503 Service Not Available 链接出现问题

更新日志

更新日志

版本

GeoIP2 精准服务当前版本为 2.1. 我们在可预见的未来都会使用2.x版,除非我们推出全心服务 (“GeoIP3”).

我们版本号会在大型改动时变化。大型改动包括 改动URI,改变当前数据的类型以及删除一种数据。

GeoIP2 更新日志 将会记录所有更新,不伦大小。

下列改动不会是大型改动:

  • 添加一种数据
  • 添加一个用户类型
  • 添加一种语言
  • 添加一种错误代码
  • 添加一种服务,例如GeoIP2 星际