1. 接口说明

对外提供 IP 地址查询的服务接口

2. 接口方式

接口地址：https://api.ipdatacloud.com

请求方式	输出格式	字符集
HTTPS GET/POST	Json	UTF-8

3. 请求说明

3.1 请求参数

字段名称	字段类型	是否必填	字段描述	备注
ip	String	是	IP地址	同时支持 IPV4 和 IPV6
key	String	是	产品密钥	根据所选产品分配，权限校验用

3.2请求实例

4. 输出说明

字段名称	字段类型	字段描述	备注
code	String	状态码	参考附录 4.2 状态码
message	String	状态信息	请求成功时内容为success
data	JsonObject	输出信息	请求失败时内容为空，参考 4.1.1 data 输出参数

4.1 data 输出参数
4.1.1 IPv4 归属地返回字段

字段名称	字段类型	字段描述	备注
version	String	IP 类型	IPv4 或 IPv6
continent	String	所属七大洲
country	String	国家
country_code	String	国家英文简写
province	String	省份
city	String	城市
district	String	区县	海外 IP 为空
street	String	街道
multi_street	JsonObject	历史街道位置	详情参考multi_street说明
longitude	String	经度
latitude	String	纬度
area_code	String	行政区码	海外 IP 为空
isp	String	运营商
time_zone	String	时区
elevation	String	海拔	海外 IP 为空
weather_station	String	气象站	海外 IP 为空
zip_code	String	邮编
city_code	String	城市代码	海外 IP 为空

4.1.2 multi_street说明

字段名称	字段类型	字段描述	备注
lng	String	经度
lat	String	纬度
province	String	省份
city	String	城市
district	String	区县
street	String	街道
district	String	区县
street	String	街道
multi_street	JsonObject	历史街道位置	详情参考multi_street说明
longitude	String	经度
latitude	String	纬度
area_code	String	行政代码
isp	String	运营商
time_zone	String	时区
elevation	String	海拔	海外 IP 为空
weather_station	String	气象站	海外 IP 为空
zip_code	String	邮编
is_proxy	String	是否代理	当无代理时为空
proxy_type	String	代理类型	详情参考proxy_type说明
city_code	String	国际直拨电话和区号	海外 IP 为空
asn	String	asn
usage_type	String	应用场景	详情参考usage_type说明
risk_tag	JsonObject	风险标签	详情参考risk_tag说明

4.1.3 IPv6 归属地返回字段

字段名称	字段类型	字段描述	备注
version	String	IP 类型	IPv4 或 IPv6
continent	String	所属七大洲
country	String	国家
country_english	String	国家英文	国内 IP 为空
country_code	String	国家英文简写	国内 IP 为空
province	String	省份
city	String	城市
district	String	区县	海外 IP 为空
longitude	String	经度
latitude	String	纬度
area_code	String	行政区码	海外 IP 为空
isp	String	运营商
time_zone	String	时区
elevation	String	海拔	海外 IP 为空
weather_station	String	气象站	海外 IP 为空
zip_code	String	邮编
city_code	String	城市代码	海外 IP 为空

4.1.4 IP 应用场景返回字段

字段名称	字段类型	字段描述	备注
isp	String	运营商
usage_type	String	应用场景类型	详情参考 usage_type 说 明
ASN	String	ASN号

4.1.4.1 usage_type 说明

返回参数	描述	备注
ANY	任播网络	属于数据中心的一部分，任播网络
CDN	内容分发	属于数据中心的一部分，内容分发网络
COM	商业公司	以盈利为目的的公司
DNS	域名解析	用户提供域名解析服务的IP
EDU	教育机构	学校/教育机构使用的IP
GTW	企业专线	固定IP，中大型公司专线上网的IP
GOV	政府机构	政府单位使用的IP
DYN	动态IP	家庭住宅用户使用的IP
IDC	数据中心	机房/云服务商使用的IP
IXP	交换中心	网络交换中心使用的IP
MOB	移动网络	基站出口IP（2G/3G/4G/5G）
NET	基础设施	网络设备骨干路由使用的IP
ORG	组织机构	非营利性组织机构
SAT	卫星通信	通过卫星上网的出口IP
BOGON	保留 IP	用于确保在特定情况下，计算机或设备可以在局域网中保持相同的IP地址，而不会被分配给其他设备
AUR	已分配-未路由	在网络设置中分配了IP地址，但这些IP地址不会被路由器或网络设备用于转发数据包
RNU	已路由-未使用	在网络中分配了可以路由的IP地址，但目前尚未用于任何设备或通信
UND	未分配 IP	在特定网络中尚未被分配给任何设备或用途的IP地址
WLA	WLAN 热点	无线局域网（WLAN）中的一个区域，其中提供无线网络连接，允许设备通过Wi-Fi连接到互联网或局域网
DDT	专用出口	专门用于将数据从一个封闭的网络环境（如公司内部网络）安全地传输到外部网络
USE	已使用	在网络中已经分配给特定设备或用途的IP地址或资源

4.1.5 IP 风险画像返回字段

字段名称	字段类型	字段描述	备注
proxy	String	代理类型	详情参考 proxy 说 明
risk_tag	JsonObject	风险标签	采集 IP 在使用中疑似发 生风险行为， 详情参考risk_tag 说明
risk_score	String	风险评分	根据风险证据、风险标签、代理类型发生时间及风险类型综合评分（可根 据行业风控定制打分）
risk_level	String	风险等级	根据风险评分进行等级划分，（可根据行业要求定制评级）
mb_rate	String	秒拨概率	评估IP地址产生的网络访问是否具有秒速拨号等异常特征，提供0%至100%的数值，值越高，表明该IP地址越有可能存在秒速拨号行为
real	String	真人概率	判别IP流量是否由真实人类产生，0%至99%进行真人概率打分，接近0%意味着更趋近机器行为

4.1.5.1 proxy 输出参数

返回参数	描述
tor	代理节点快速动态变化的加密三重代理
vpn	通过使用专用线路或在现有网络上使用隧道协议创建一个虚 拟的点对点连接而形成。
proxy	⽹络代理，是⼀种特殊的⽹络服务，允许⼀个⽹络终端通过这 个服务与另⼀个⽹络终端进⾏⾮直接的连接。
relay	指示专用中继服务是否为存在于 IP 上（Apple Private Relay 等）

4.1.5.2 risk_tag输出参数

字段名称	字段类型	字段描述	备注
label	String	风险证据	参考 label 说明
label_name	String	风险标签名称	参考 label 说明
last_time	String	最近一次发生时间	格式：yyyy-MM-dd HH:mm:ss

label 说明

返回参数	描述	备注
fraudulentSignup	垃圾注册	使用机器、脚本、虚假号码注册等符合风险注册特征的行为
SMSBombing	短信轰炸	申请短信验证码次数、频次过高
scalping	黄牛	使用机器、脚本、相似地址重复参与下单的行为
wool	薅羊毛	在营销实践中作弊、批量、重复领取优惠的行 为
spam	垃圾信息	该 IP 对应的账号频繁发布垃圾信息（涉政、色情、广告等文本或图片）
abnormalNetworkDevice	网络异常设备	该 IP 曾被网络信息异常的设备持有使用过
tamperedDevice	篡改设备	该 IP 曾被篡改设备（设备参数被篡改、改机工具等）持有使用过
fakeDevice	虚假设备	该 IP 曾被虚假设备（虚假设备、虚拟浏览器等）持有使用过
highRiskDevice	高危设备	该 IP 曾被高危设备（群控、检测绕过等）持有使用过
suspectFakeMobile	疑似虚假号码	该 IP 曾被疑似虚假号码持有使用过
suspectRiskStatusMobile	疑似高危状态号码	该 IP 曾被疑似高危状态号码持有使用过
highRiskMobile	高风险手机号	该 IP 曾被高风险手机号持有使用过

4.1.6 IP 代理识别返回字段

字段名称	字段类型	字段描述	备注
is_proxy	String	是否代理	当无代理时为空
proxy	String	代理类型	详情参考 proxy 说明
proxy_time	String	代理时间	代理发生时间，无代理时为空

4.1.7 IP 真人识别

字段名称	字段类型	字段描述	备注
mb_rate	String	秒拨概率	评估IP地址产生的网络访问是否具有秒速拨号等异常特征，提供0%至100%的数值，值越高，表明该IP地址越有可能存在秒速拨号行为
real	String	真人概率	判别IP流量是否由真实人类产生，0%至99%进行真人概率打分，接近0%意味着更趋近机器行为
asn	String	ASN号	通过ASN号可以判断当前IP互联网提供商、IP所有者。
isp	String	互联网供应商	通过识别互联网提供商的IP分配情况，帮助识别用户的网络连接特征。

4.2 状态码

code	message	备注
200	success	请求调用成功
500	失败信息	请求失败原因（过期、次数不足、IP 类型错误等）

1. 注册和获取秘钥

获取SDK接入的流程大致可分为如下四个步骤：（1）前往IP数据云官网获取SDK （2）选择需要数据维度 （3）创建相关应用 （4）获取专属秘钥

2. Android接入指南

2.1 下载jar文件
(1)从官网下载jar文件
(2)将jar文件拷贝到lib目录中

2.2 在项目中使用
2.2.1 在您调用该SDK之前初始化该SDK，推荐在MainActivity中完成

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        IpUtil.getInstance().init(this, "您的app应用名称","您申请的密钥");
    }
}
                    

2.2.2 使用SDK获取您需要的IP数据

IpUtil.getInstance().request(,"您要查询的ip", new IpInfoCallback() {
    @Override
    public void onSuccess(String responseData) {
    }
    @Override
    public void onError(int code, String message) {
    }
});
                    

2.3 加入混淆

-keep class com.sdk.ip.bean.** {*;}
-keep class com.sdk.ip.util.IpInfoCallback {*;}
-keep class com.sdk.ip.IpUtil{*;}
                    

3. Ios接入指南

3.1 Cocoapods 自动集成(推荐)
(1)在您的项目工程（.xcodeproj）文件同目录下创建一个名为Podfile文件
(2)编辑Podfile内容，iOS版本IP数据云SDK的Pod库名称为“IpTrace”

platform:ios,'9.0'
target "IPDataCloudSDKDemo" do
use_frameworks!
  pod 'IpTrace'
end
                    

（3）.执行安装命令

pod install
                    

(4)安装成功后，打开项目文件夹，选择.xcworkspace文件启动工程

3.2 在项目中使用
3.2.1 (1)在AppDeledate.m中引入头文件，调用初始化接口，第一个参数sdkKey传入购买SDK套餐专属密钥SDKKEY，第二个参数传入渠道

#import "IpTrace.h"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [[IpTrace shared] registersdkKey:@"SDKKEY" withChannel:@"appstore"];
    return YES;
}

                    

3.2.2调用ip查询方法
在需要查询ip的.m文件中引入头文件，调用查询接口，searchIP传入要查询的ip

#import "IpTrace.h"
    [[IpTrace shared] searchWithIP:@"1.1.0.1" success:^(NSDictionary * _Nullable resultDic) {
        NSLog(@"success resultdic----->%@", resultDic);
    } fail:^(NSError * _Nullable error) {
        NSLog(@"error%@", error);
    }];
                    

4. 输出说明

4.1 输出参数

字段名称	字段类型	字段描述	备注
code	String	状态码	参考附录 4.2 状态码
message	String	状态信息	请求成功时内容为success
data	JsonObject	输出信息	请求失败时内容为空，参考 4.1.1 data 输出参数

4.1.1data输出参数

字段名称	字段类型	字段描述	备注
location	JsonObject	IP归属地数据详情	参考4.1.1.1 location输出参数
scenes	JsonObject	IP应用场景数据详情	参考4.1.1.2 scenes输出参数
risk	JsonObject	IP风险画像数据详情	参考4.1.1.3 risk输出参数

4.1.1.1 location输出参数

字段名称	字段类型	字段描述	备注
version	String	IP类型
continent	String	七大洲
country	String	国家
country_code	String	国家英文简写
province	String	省份
city	String	城市
district	String	区县
street	String	街道
longitude	String	经度
latitude	String	纬度
area_code	String	行政代码
isp	String	运营商
local_time	String	本地时间
elevation	String	海拔
weather_station	String	气象站
zip_code	String	邮编
is_proxy	String	是否代理	当无代理时为空
proxy_type	String	代理类型	详情参考proxy_type说明
city_code	String	国际直拨电话和区号
asn	String	asn
usage_type	String	应用场景	详情参考usage_type说明
risk_proof	JsonObject	风险证据	详情参考risk_proof说明
risk_tag	JsonObject	风险标签	详情参考risk_tag说明

4.1.1.2 scenes输出参数 proxy_type说明

返回参数	备注
hosting
http
socks4
socks5
pptp
l2tp
sstp
proxy
tor
vpn
relay

4.1.1.2usage_type说明

返回参数	描述	备注
ANY	任播网络	属于数据中心的一部分，任播网络
CDN	内容分发	属于数据中心的一部分，内容分发网络
COM	商业公司	以盈利为目的的公司
DNS	域名解析	用户提供域名解析服务的IP
EDU	教育机构	学校/教育机构使用的IP
GTW	企业专线	固定IP，中大型公司专线上网的IP
GOV	政府机构	政府单位使用的IP
DYN	动态IP	家庭住宅用户使用的IP
IDC	数据中心	机房/云服务商使用的IP
IXP	交换中心	网络交换中心使用的IP
MOB	移动网络	基站出口IP（2G/3G/4G/5G）
NET	基础设施	网络设备骨干路由使用的IP
ORG	组织机构	非营利性组织机构
SAT	卫星通信	通过卫星上网的出口IP

4.1.1.3 risk_proof输出参数

字段名称	字段类型	字段描述	备注
evidence	String	风险证据	参考 evidence 说明
evidence_name	String	风险证据名称	参考 evidence 说明
last_time	String	最近一次发生时间	格式：yyyy-MM-dd HH:mm:ss

evidence 说明

返回参数	描述	备注
anonymizers	匿名服务器	该 IP 因为长期运行开放式匿名代理服务而被标记
attacks	网络攻击源	该 IP 因为频繁进行网络攻击而被标记（漏洞攻击、暴力破解等）
bots	肉鸡	该 IP 被确认为已经被特定的恶意程序控制
c2	远程控制服务器	该 IP 被确认为一个用于控制僵尸网络或傀儡主机的 IP
malware	恶意软件	该 IP 被确认与特定的恶意程序相关（发布、下载、更新等）
phishing	钓⻥	该 IP 因为被用于进行钓鱼攻击而被标记
scanning	端口扫描	该 IP 因为频繁进行端口扫描、漏洞扫描而被标记
spam	垃圾信息	该 IP 因为频繁发送垃圾信息而被标记（垃圾邮件、垃圾评论等）
spider	爬虫	该 IP 因为大量进行网页爬取和信息收集而被标记

label 说明

返回参数	描述	备注
fraudulentSignup	垃圾注册	使用机器、脚本、虚假号码注册等符合风险注册特征的行为
SMSBombing	短信轰炸	申请短信验证码次数、频次过高
scalping	黄牛	使用机器、脚本、相似地址重复参与下单的行为
wool	薅羊毛	在营销实践中作弊、批量、重复领取优惠的行为
spam	垃圾信息	该 IP 对应的账号频繁发布垃圾信息（涉政、色情、广告等文本或图片）
abnormalNetworkDevice	网络异常设备	该 IP 曾被网络信息异常的设备持有使用过
tamperedDevice	篡改设备	该 IP 曾被篡改设备（设备参数被篡改、改机工具等）持有使用过
fakeDevice	虚假设备	该 IP 曾被虚假设备（虚假设备、虚拟浏览器等）持有使用过
highRiskDevice	高危设备	该 IP 曾被高危设备（群控、检测绕过等）持有使用过
suspectFakeMobile	疑似虚假号码	该 IP 曾被疑似虚假号码持有使用过
suspectRiskStatusMobile	疑似高危状态号码	该 IP 曾被疑似高危状态号码持有使用过
highRiskMobile	高风险手机号	该 IP 曾被高风险手机号持有使用过

4.2 状态码

code	message	备注
200	success	请求调用成功
500	失败信息	请求失败原因（过期/次数不足等）

IP数据云SDK合规指南

尊敬的开发者：

为有效治理App强制授权、过度索权、超范围收集个人信息等现象，落实《网络安全法》《消费者权益保护法》的要求，保障个人信息安全，2019年1月，中央网信办、工信部、公安部、市场监管总局等四部委发布了《关于开展App违法违规收集使用个人信息专项治理的公告》，在全国范围组织开展App违法违规收集使用个人信息专项治理，并陆续出台完善了《App违法违规收集使用个人信息行为认定方法》、《GB/T 35273-2020 信息安全技术 个人信息安全规范》等标准规范。

近年来，随着工信部纵深推进App专项整治行动，以及陆续检测通报App违规情况，监管部门、各行业参与方、终端用户都越来越关注App和SDK的安全问题。

为帮助使用IP数据云SDK的开发者更清楚地了解监管要求、高效落实个人信息保护相关事宜，IP数据云（公司全称：江苏舍恩伯格信息科技有限公司）特编写了本合规指南（以下简称“指南”），供开发者们参考。

一、App个人信息保护合规基本要求

首先需制定一份《隐私政策》，并确保在产品界面中 显著展示。《隐私政策》须 单独成文，而不是作为用户协议、用户说明等文件中的一部分存在。App应在《隐私政策》中 明示收集使用个人信息的目的、方式和范围，并确保《隐私政策》链接正常有效，易于访问和阅读。

App应在《隐私政策》中将收集个人信息的业务功能以及每个业务功能所收集的个人信息类型进行 逐项列举，不应使用“等、例如” 等方式概括说明；同时，App须 对个人敏感信息类型进行显著标识（如字体加粗、标星号、下划线、斜体、颜色等）。如果通过嵌入第三方代码、插件等方式将个人信息传输至第三方服务器，应通过弹窗提示等方式明确告知用户

二、App使用IP数据云的合规指引

您应确保在App首次运行时通过明显方式提示终端用户阅读您的《隐私政策》，并取得终端用户的合法授权后，再初始化IP数据云SDK进行信息收集与处理。如果终端用户不同意您的隐私政策，则不能初始化IP数据云SDK，也无法使用IP数据云SDK的对应功能。

如果您的App在终端用户首次运行时，需要注册用户账号才能使用，则可以在账号注册环节提示终端用户同意您的《隐私政策》，之后完成注册；如果您的App并不一定需要终端用户注册用户账号才能使用，那么如果终端用户不同意您的《隐私政策》，按照最新的政策和法规，您不应禁止终端用户使用您的App，仍需保留用户的基本使用权利。若终端用户将使用到需收集相关个人信息才能使用的功能，可以再次提醒终端用户需要同意您的《隐私政策》才能正常使用相关功能，若终端用户仍不同意，则不对用户提供相应的功能，可在终端用户下次需要使用时再提示同意您的《隐私政策》。

2.【重要】在使用IP数据云SDK时，您需在自己开发的App所制定的《隐私政策》文本中“与授权合作伙伴共享”或“第三方SDK”等相关条款中，将

IP数据云的用户隐私政策

加入其中，并向终端用户明示IP数据云SDK收集使用其个人信息的目的、方式和范围。并在APP的隐私政策恰当位置中添加如下IP数据云SDK的隐私政策模版。

SDK名称	SDK厂商	合作目的	收集个人信息字段及用途	SDK隐私政策链接
IP数据云SDK	江苏舍恩伯格信息科技有限公司	为用户提供IP地址所在国家省份城市的转换服务。比如根据中国《互联网用户账号信息管理规定》，要求在用户公众页面中展示IP地址的归属地	（1）网络信息：用户使用的IP地址，此数据为IP数据云SDK提供IP地址转换服务所需的必须信息，否则无法提供业务服务。 （2）位置信息：用于纠正为用户提供的IP地址转换服务的错误。注意：IP数据云SDK不主动要求用户授予位置权限，仅在APP本身已具有位置权限时才收集。	https://www.ipdatacloud.com/agreement/privacy.html