Wiwiz Query API参考手册与接口规范

[修改履历]
Ver 1.1 : 查询手机号码功能接口的返回数据增加了magic_code_flag。(2014.2.2)
Ver 1.2 : 增加查询热点公网IP接口。(2015.9.14)
Ver 1.3 : conn接口查询结果中增加tokencode。（2015.10.16）
Ver 1.4 : connlog接口的date_from、date_to参数增加时间格式；增加webadlog接口。(2015.12.31)
Ver 1.5 : 新增conninfo接口。用于查询指定tokencode的单连接信息。(2018.2.11)

功能描述

Wiwiz Query API是Wiwiz HotSpot Builder提供的基于Web的外部开发接口。调用它可以用于查询以下信息：
1. 热点的当前所有连接信息
2. 热点的某个单连接信息
3. 热点的连接履历
4. 热点使用者在使用热点认证时输入的手机号码
5. 热点的公网IP地址
6. 查询热点的插播广告投放效果数据

使用条件与要求
1.已拥有Wiwiz专业版账户。
2.查询Wiwiz账户的User Key（*注1）

调用概要
调用Wiwiz Query API时，用户需向指定URL发送HTTP请求，发送请求时应根据接口规范指定参数（GET或POST方式皆可）。查询的结果数据以HTTP响应的形式（XML格式）返回。

无报错情况下的HTTP响应数据的格式样例：

?View Code XML
<?xml version="1.0" encoding="UTF-8"?>
<result>
    <status>
        <code>OK</code>
        <message>Query Completed</message>
    </status>
    <data>
        <record>
            ……
        </record>
        <record>
            ……
        </record>
        ……
    </data>
</result>



有报错情况下的HTTP响应数据的格式样例：

?View Code XML
<?xml version="1.0" encoding="UTF-8"?>
<result>
    <status>
        <code>STATUS CODE</code>
        <message>STATUS CODE DESCIRPTION</message>
    </status>
    <data></data>
</result>



接口规范

1. 查询热点的当前所有连接信息

请求URL: http://cp.wiwiz.com/as/qapi/conn/

请求参数说明:

参数名 必须/可选 说明
userkey 必须 设为用户自己的User Key（*注1）
hotspotid 必须 热点的HotSpot ID



返回数据说明:

数据项目 说明
result/status/code 状态码（*注2）
result/status/message 状态码说明
result/data/record/ip 终端IP地址
result/data/record/mac 终端MAC地址
result/data/record/start_time 接入时间
result/data/record/end_time 预定截止时间
result/data/record/incoming 接收数据字节数
result/data/record/outgoing 发出数据字节数
result/data/record/username 用户名
result/data/record/usertype 用户类型。0：Wiwiz注册用户；1：自定义账户
result/data/record/voucher 电子招待券
result/data/record/mobile 手机号码
result/data/record/userstring 自定义追踪信息
result/data/record/tokencode 认证令牌码



2. 查询热点的某个单连接信息

请求URL: http://cp.wiwiz.com/as/qapi/conninfo/

请求参数说明:

参数名 必须/可选 说明
userkey 必须 设为用户自己的User Key（*注1）
t 必须 终端认证时的tokencode



返回数据说明:

数据项目 说明
result/status/code 状态码（*注2）
result/status/message 状态码说明
result/data/record/ip 终端IP地址
result/data/record/mac 终端MAC地址
result/data/record/start_time 接入时间
result/data/record/end_time 预定截止时间
result/data/record/incoming 接收数据字节数
result/data/record/outgoing 发出数据字节数
result/data/record/username 用户名
result/data/record/usertype 用户类型。0：Wiwiz注册用户；1：自定义账户
result/data/record/voucher 电子招待券
result/data/record/mobile 手机号码
result/data/record/userstring 自定义追踪信息
result/data/record/tokencode 认证令牌码



3. 查询热点的连接履历

请求URL: http://cp.wiwiz.com/as/qapi/connlog/

请求参数说明:

参数名 必须/可选 说明
userkey 必须 设为用户自己的User Key（*注1）
hotspotid 必须 热点的HotSpot ID
date_from 可选 查询起始日期。格式：YYYY-MM-DD或YYYY-MM-DD HH:mm:SS。如省略则默认为当前时间
date_to 可选 查询截止日期。格式：YYYY-MM-DD或YYYY-MM-DD HH:mm:SS。如省略则默认为当前时间



返回数据说明:

数据项目 说明
result/status/code 状态码（*注2）
result/status/message 状态码说明
result/data/record/ip 终端IP地址
result/data/record/mac 终端MAC地址
result/data/record/start_time 接入时间
result/data/record/end_time 截止时间
result/data/record/incoming 接收数据字节数
result/data/record/outgoing 发出数据字节数
result/data/record/username 用户名
result/data/record/usertype 用户类型。0：Wiwiz注册用户；1：自定义账户
result/data/record/voucher 电子招待券
result/data/record/mobile 手机号码
result/data/record/userstring 自定义追踪信息



4. 查询热点使用者在使用热点认证时输入的手机号码

请求URL: http://cp.wiwiz.com/as/qapi/mobile/

请求参数说明:

参数名 必须/可选 说明
userkey 必须 设为用户自己的User Key（*注1）
hotspotid 必须 热点的HotSpot ID
date_from 可选 查询起始日期。格式：YYYY-MM-DD。如省略则默认为当前日期
date_to 可选 查询截止日期。格式：YYYY-MM-DD。如省略则默认为当前日期
verified 可选 手机号码验证标识。true：已验证；false：未验证



返回数据说明:

数据项目 说明
result/status/code 状态码（*注2）
result/status/message 状态码说明
result/data/record/country 手机号码所在国家地区的代码（*注3）
result/data/record/phonenum 手机号码
result/data/record/time 日期时间
result/data/record/verified 手机号码验证标识。true：已验证；false：未验证
result/data/record/magic_code_flag 万能验证码标识。1：使用万能验证码；空：未使用万能验证码


5. 查询热点的公网IP地址

请求URL: http://cp.wiwiz.com/as/qapi/hotspotip/

请求参数说明:

参数名 必须/可选 说明
userkey 必须 设为用户自己的User Key（*注1）
hotspotid 必须 热点的HotSpot ID
show_updatetime 必须 固定值”1″



返回数据说明:

数据项目 说明
result/status/code 状态码（*注2）
result/status/message 状态码说明
result/data/wan_ip 热点的公网IP地址
result/data/updatetime 更新时间


6. 查询热点的插播广告投放效果数据

请求URL: http://cp.wiwiz.com/as/qapi/webadlog/

请求参数说明:

参数名 必须/可选 说明
userkey 必须 设为用户自己的User Key（*注1）
hotspotid 必须 热点的HotSpot ID
ad_id 可选 广告编号
event_type 可选 事件类型（1代表广告被展示；2代表被点击）
date_from 可选 查询起始日期。格式：YYYY-MM-DD或YYYY-MM-DD HH:mm:SS。如省略则默认为当前时间
date_to 可选 查询截止日期。格式：YYYY-MM-DD或YYYY-MM-DD HH:mm:SS。如省略则默认为当前时间

*注意：date_from和date_to的间隔不可大于60日。


返回数据说明:

数据项目 说明
result/status/code 状态码（*注2）
result/status/message 状态码说明
result/data/record/ad_id 广告编号
result/data/record/event_type 事件类型（1代表广告被展示；2代表被点击）
result/data/record/uuid 用户识别信息
result/data/record/ua 浏览器标识（User Agent）
result/data/record/site 广告被展示或点击时所在的网站
result/data/record/event_time 时间


注解
注1：User Key可在Wiwiz Web面板的“用户菜单”->“升级选项”->“查询User Key”中查询。

注2：状态码说明：

状态码 说明
OK 查询成功
ERR001 参数userkey为空
ERR002 参数hotspotid为空
ERR003 错误的userkey
ERR004 无权限调用API，需升级至专业版
ERR005 无权限查询此热点，或HotSpotID错误
ERR006 日期错误



注3：国家地区代码的含义：
AR:阿根廷
AT:奥地利
AU:澳大利亚
BE:比利时
BR:巴西
CA:加拿大
CH:瑞士
CN:中国
DE:德国
DK:丹麦
ES:西班牙
FR:法国
GB:英国
HK:中国香港特别行政区
ID:印度尼西亚
IE:爱尔兰
IL:以色列
IN:印度
IT:意大利
JO:约旦
JP:日本
KR:韩国
KY:开曼群岛
LU:卢森堡
MO:中国澳门特别行政区
MX:墨西哥
MY:马来西亚
NL:荷兰
NO:挪威
NZ:新西兰
PH:菲律宾
PK:巴基斯坦
PL:波兰
SE:瑞典
SG:新加坡
TH:泰国
TR:土耳其
TW:台湾
US:美国
ZA:南非

Comments are closed.