Wiwiz Query API Manual and Specification

[Modification Logs]
Ver 1.1 : magic_code_flag is added for Inquiry of Mobile phone numbers. (Feb 2, 2014)
Ver 1.2 : Interface for making inquery of a hotspot’s WAN IP. (Sep 14, 2015)
Ver 1.3 : tokencode is added for CONN. (Oct 16, 2015)
Ver 1.4 : Time format is supportted for date_from, date_to in connlog. webadlog is added. (Dec 31, 2015)

Description
Wiwiz Query API is an Application Programming Interface based on Web technology, which is provided by Wiwiz HotSpot Builder. It is used to make inquiries of the following data:
1. Current connections of a hotspot
2. Connection log of a hotspot
3. Mobile phone numbers entered in the Authentication Page of a hotspot
4. A hotspot’s Internet/WAN IP
5. Inquiry of views and clicks of AD Injection

Conditions and Requirements
1. A Wiwiz Professional Account is required.
2. Get your User Key of your Wiwiz account. (*Remark 1)

General Instruction
When calling Wiwiz Query API, an HTTP request is sent to the given URL with the specified parameters(GET or POST). The inquiry result is returned in XML format with the HTTP response

Sample of inquiry result, in case of no error:

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



Sample of inquiry result, in case of error:

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



Specifications
1. Inquiry of current connections of a hotspot
URL request to: http://cp.wiwiz.com/as/qapi/conn/
Request parameters:

Parameter Name Required/Optional Description
userkey Required Your own User Key (*Remark 1)
hotspotid Required HotSpot ID



XML node in inquiry result:

Node Name Description
result/status/code Status Code (*Remark 2)
result/status/message Description of Status Code
result/data/record/ip IP address of the client
result/data/record/mac MAC address of the client
result/data/record/start_time Starting Time
result/data/record/end_time Ending Time
result/data/record/incoming Incoming Data Bytes
result/data/record/outgoing Outgoing Data Bytes
result/data/record/username User Name
result/data/record/usertype User Type
0: Registered user of Wiwiz.com, 1: Private Account
result/data/record/voucher Voucher
result/data/record/mobile Mobile Number
result/data/record/userstring Track Data
result/data/record/tokencode Token of an authentication



2. Inquiry of connection log of a hotspot
URL request to: http://cp.wiwiz.com/as/qapi/connlog/
Request parameters:

Parameter Name Required/Optional Description
userkey Required Your own User Key (*Remark 1)
hotspotid Required HotSpot ID
date_from Optional Starting Date, format: YYYY-MM-DD or YYYY-MM-DD HH:mm:SS, default: current time
date_to Optional Ending Date, format: YYYY-MM-DD or YYYY-MM-DD HH:mm:SS, default: current time



XML node in inquiry result:

Node Name Description
result/status/code Status Code (*Remark 2)
result/status/message Description of Status Code
result/data/record/ip IP address of the client
result/data/record/mac MAC address of the client
result/data/record/start_time Starting Time
result/data/record/end_time Ending Time
result/data/record/incoming Incoming Data Bytes
result/data/record/outgoing Outgoing Data Bytes
result/data/record/username User Name
result/data/record/usertype User Type
0: Registered user of Wiwiz.com, 1: Private Account
result/data/record/voucher Voucher
result/data/record/mobile Mobile Number
result/data/record/userstring Track Data



3. Inquiry of Mobile phone numbers entered in the Authentication Page of a hotspot
URL request to: http://cp.wiwiz.com/as/qapi/mobile/
Request parameters:

Parameter Name Required/Optional Description
userkey Required Your own User Key (*Remark 1)
hotspotid Required HotSpot ID
date_from Optional Starting Date, format: YYYY-MM-DD, default: current date
date_to Optional Ending Date, format: YYYY-MM-DD, default: current date
verified Optional Verification Flag, true: verified, false: not verified



XML node in inquiry result:

Node Name Description
result/status/code Status Code (*Remark 2)
result/status/message Description of Status Code
result/data/record/country Country Code (*Remark 3)
result/data/record/phonenum Mobile Phone Number
result/data/record/time Date and Time
result/data/record/verified Verification Flag, true: verified, false: not verified
result/data/record/magic_code_flag Magic Code Flag, 1: Magic Code used, NULL: Magic Code not used


4. Inquiry of a hotspot’s WAN IP
URL request to: http://cp.wiwiz.com/as/qapi/hotspotip/
Request parameters:

Parameter Name Required/Optional Description
userkey Required Your own User Key (*Remark 1)
hotspotid Required HotSpot ID
show_updatetime Required fixed value “1″



XML node in inquiry result:

Node Name Description
result/status/code Status Code (*Remark 2)
result/status/message Description of Status Code
result/data/wan_ip Internet IP
result/data/updatetime Update Time


5. Inquiry of views and clicks of AD Injection
URL request to: http://cp.wiwiz.com/as/qapi/hotspotip/
Request parameters:

Parameter Name Required/Optional Description
userkey Required Your own User Key (*Remark 1)
hotspotid Required HotSpot ID
ad_id Optional AD ID
event_type Optional Event Type (1:view 2:click)
date_from Optional Starting Date, format: YYYY-MM-DD or YYYY-MM-DD HH:mm:SS, default: current time
date_to Optional Ending Date, format: YYYY-MM-DD or YYYY-MM-DD HH:mm:SS, default: current time

*Note: Interval between date_from and date_to cannot exceed 30 days.


XML node in inquiry result:

Node Name Description
result/status/code Status Code (*Remark 2)
result/status/message Description of Status Code
result/data/record/ad_id AD ID
result/data/record/event_type Event Type (1:view 2:click)
result/data/record/uuid User Identifier
result/data/record/ua User Agent of Browser
result/data/record/site web site which AD is viewed or clicked
result/data/record/event_time Time


Remarks
Remark 1: You can get your User Key from “Menu” -> “Upgrade Options” -> “User Key” in Wiwiz Web Panel.

Remark 2: Status Code

Status Code Description
OK Success
ERR001 Parameter ‘userkey’ is empty
ERR002 Parameter ‘hotspotid‘ is empty
ERR003 Invalid userkey
ERR004 Need to upgrade to Professional Edition
ERR005 No permission or invalid hotspotid
ERR006 Invalid date



Remark 3: Country Code
AR:Argentina
AT:Austria
AU:Australia
BE:Belgium
BR:Brazil
CA:Canada
CH:Switzerland
CN:China
DE:Germany
DK:Denmark
ES:Spain
FR:France
GB:United Kingdom
HK:Hong Kong
ID:Indonesia
IE:Ireland
IL:Israel
IN:India
IT:Italy
JO:Jordan
JP:Japan
KR:Korea
KY:Cayman Islands
LU:Luxembourg
MO:Macao
MX:Mexico
MY:Malaysia
NL:Netherlands
NO:Norway
NZ:New Zealand
PH:Philippines
PK:Pakistan
PL:Poland
SE:Sweden
SG:Singapore
TH:Thailand
TR:Turkey
TW:Taiwan
US:United States
ZA:South Africa

Comments are closed.