Tanaza provides APIs to read in real-time the status of your networks in cloud.tanaza.com.
In this document we describe the Tanaza Cloud Public REST APIs, that allow a user to get the description and the status of all the networks and access points on his Tanaza account.
Tanaza provides APIs to read in real-time the status of your networks in cloud.tanaza.com.
In this document we describe the Tanaza Cloud Public REST APIs, that allow a user to get the description and the status of all the networks and access points on his Tanaza account.
Authentication
The authentication system of the Tanaza Cloud Public REST APIs is based on tokens. If you want to use these APIs you needs to generate a token on cloud.tanaza.com.
In the account menu, access the section "APIs".
The first time a user asks for a token generation, the following values are created: Unique user ID Token
By clicking on the button "Generate new token", a new token is generated. Starting from that moment on, all the previous tokens are not valid anymore. Only one token at a time can be used.
To authenticate via API, you need both user ID and token. The user ID is unique and it's always the same, while you can generate as many tokens as you want (but only the last one is valid).
The user can also disable the APIs on his account (this is the default state).
Endpoint
To access the access point information a simple HTTP GET request needs to be performed to the following URL:
For Version 1
Endpoint: https://cloud.tanaza.com/apis/v1/
For Version 2
Endpoint: https://cloud.tanaza.com/apis/v2.0/
Actions
An action needs to be specified when accessing the API.
As for version 1 and 2.0 of the APIs, only the "status" action is available.
Request
The request is performed using the following URL structure:
Version 1
https://cloud.tanaza.com/apis/v1/USERID/TOKEN/ACTION
Supposing the user id is "hhiillmmnnooppqqrr" and the generated token is "aabbccddeeffgg", if the user wants to request the "status" action on his account the following request must be executed:
URL for GET REQUEST: https://cloud.tanaza.com/apis/v1/hhiillmmnnooppqqrr/aabbccddeeffgg/status
Version 2
https://cloud.tanaza.com/apis/v2.0/USERID/TOKEN/ACTION
Supposing the user id is "hhiillmmnnooppqqrr" and the generated token is "aabbccddeeffgg", if the user wants to request the "status" action on his account the following request must be executed:
URL for GET REQUEST: https://cloud.tanaza.com/apis/v2.0/hhiillmmnnooppqqrr/aabbccddeeffgg/status
Response
For each request a response with content-type "application/json" is returned with the following structure:
JSON Object properties:
Property name
Type
Description
errorCode
number
If equals to 0 the request was successfully executed and the response can be found in the "payload" property.
If not equals 0 an error occurred. Please refer to the errorCode in the next paragraph.
errorMessage
string
Explains the error occurred and gives more details.
payload
JSON Object
It is the response payload, coded in a json object. It varies based on the action required.
"Status" Action Response V1
The "status" action allows you to know the following data about your account:
Networks
Access Points
SSIDs currently active on the Access Points
The users (client MAC addresses) that are connected to the Access Points
Status of each access point
"Status" Action Response V2.0
The "status" action allows the user to know the following data about his account:
1. Networks
2. Access Points
3. Ssids currently active on the Access Points
4. The users (client mac address) that are connected to the Access Points
5. Status of each Access Point
An example of the payload data structure for V1
As for the structure it contains:
A list of networks.
For each network: its label and a list of devices.
For each device: its label, its MAC address (where the first MAC address of the list is the WAN MAC address), a list of SSIDs, the timestamp of the latest packet received by Tanaza from the device (expressed in milliseconds UTC), current status of the access point (it can be "online" or "offline")
For each SSID: its label, a list of clients connected to that SSID
For each client: the client MAC address, the strenght of the signal expressed in dBm
An example of the complete response resulting data structure
An example of the payload data structure for V2.0
As for the structure it contains:
A list of networks.
For every network: its label and a list of devices.
For every device: its label, its mac addresses (where the first mac address of the list is the wan
mac address), a list of ssids,the timestamp of the latest packet received by tanaza from the
device (expressed in milliseconds UTC), current status of the access point (can be "online" or
"offline")
For every ssid: its label, a list of clients connected to that ssid
For every client: the client mac address, the strenght of the signal expressed in dBm
This is the specification of all the fields in the JSON output, with an example.
Object
Property
type
Description
Networks
array of objects (Network)
Array containing objects that describe all the networks
Network
label
string
The label assigned to the network
Network
devices
array of objects (Device)
Array of all the devices associated to this network
Device
id
long
Unique identifier for access point on tanaza
Device
label
string
The label assigned to the access point
Device
mac_address
array of string
All the mac addresses of the interfaces of the device in the following format “00:11:22:33:44:55” The first mac address is the WAN mac_address and is the one identifying the access point in tanaza
Device
Status
string
Status of the access point, one of:
● “online” , if the access point was seen online in the last 60 seconds
● “alert” , if not in “online” state and less then 5 minutes have passed
● “offline” , it the access point was seen online the last time more then 5 minutes ago
Device
last_timestamp
long
Last time the access point sent information or stats or was last seen. Expressed as unix time seconds.
All information with prefix “last_” are referring to this timestamp.
Device
last_uptime
long
Number of minutes of uptime (power on from last reboot) of the access point, regardless of connection problems.
Device
last_bytes_tx
long
Number of bytes transmitted by the access point.
Device
last_bytes_rx
long
Number of bytes received by the access point
Device
last_pkts_rx
long
Number of packets sent by the access point
Device
last_load_percentage
long
Number from 0 to 100, expressing the percentage of load on the access point. Higher value indicates higher load on the access point.
Device
last_total_ram
long
Number of total available bytes of ram memory on the access point, regardless of how much is used now.
Device
last_free_ram
long
Number of free bytes of ram memory on the access point.
Device
last_used_ram
long
Number of used bytes of ram memory on the access point.
Device
ssids
array of object (Ssid)
Ssids enabled on the access points with relative information
Ssid
label
string
The broadcasting Ssid name, corrisponds to the Ssid profile name in tanaza
Ssid
clients
array of object (Client)
List of clients connected to the ssid
Client
mac
string
The unique mac address identifier of the client connected to the access point.
Client
strength
long
The strength of the signal communicating with the client, expressed in dBm
Client
idle_time
long
The amount of time the client is being idle
Client
bytes_rx
long
Number of bytes received by the client
Client
bytes_tx
long
Number of bytes sent by the client
Client
pkts_tx
long
Number of packets received by the client
Client
pkts_tx
long
Number of packets sent by the client
Client
connection_time
long
Number of seconds the client is connected to this ssid
Client
tx_retries
long
Number of transmission retries
Client
tx_failed
long
Number of transmission failed
An example of the complete response resulting data structure:
Based on the error code in the response, you can understand if the request was executed correctly.
ErrorCode Value
Description
What to do
200
Everything ok. No error occured.
The payload property contains the response.
400
Bad request. Wrong parameters specified in the request
The request was not executed correctly. Check the URL structure.
403
Authentication error
The token / user ID supplied is not valid or the user disabled the API access on its account. Or a new token was generated, invalidating the token in the request.
405
User blocked.
Contact support.
500
Request rate exceeded
Wait until the timeout of the rate exceeded ends. In the errorMessage you will find how long you should wait.
Consider that this happens only because you request too often the data from the server.
Request Rates
The APIs are not meant to be used more than once a minute.
If two or more requests are made within the same minute, the response will the previous one (Request rate exceeded), and no updated data will be sent.
So consider to request an update only once a minute, as all the other requests will be useless.
To activate the Network API on your account, please refer to sales@tanaza.com
Network Status APIs
Tanaza provides APIs to read in real-time the status of your networks in cloud.tanaza.com.
In this document we describe the Tanaza Cloud Public REST APIs, that allow a user to get the description and the status of all the networks and access points on his Tanaza account.
Tanaza provides APIs to read in real-time the status of your networks in cloud.tanaza.com.
In this document we describe the Tanaza Cloud Public REST APIs, that allow a user to get the description and the status of all the networks and access points on his Tanaza account.
Authentication
The authentication system of the Tanaza Cloud Public REST APIs is based on tokens. If you want to use these APIs you needs to generate a token on cloud.tanaza.com.
In the account menu, access the section "APIs".
The first time a user asks for a token generation, the following values are created:
Unique user ID
Token
By clicking on the button "Generate new token", a new token is generated. Starting from that moment on, all the previous tokens are not valid anymore. Only one token at a time can be used.
To authenticate via API, you need both user ID and token. The user ID is unique and it's always the same, while you can generate as many tokens as you want (but only the last one is valid).
The user can also disable the APIs on his account (this is the default state).
Endpoint
To access the access point information a simple HTTP GET request needs to be performed to the following URL:
For Version 1
Endpoint: https://cloud.tanaza.com/apis/v1/
For Version 2
Endpoint: https://cloud.tanaza.com/apis/v2.0/
Actions
An action needs to be specified when accessing the API.
As for version 1 and 2.0 of the APIs, only the "status" action is available.
Request
The request is performed using the following URL structure:
Version 1
https://cloud.tanaza.com/apis/v1/USERID/TOKEN/ACTION
Supposing the user id is "hhiillmmnnooppqqrr" and the generated token is "aabbccddeeffgg", if the user wants to request the "status" action on his account the following request must be executed:
URL for GET REQUEST: https://cloud.tanaza.com/apis/v1/hhiillmmnnooppqqrr/aabbccddeeffgg/status
Version 2
https://cloud.tanaza.com/apis/v2.0/USERID/TOKEN/ACTION
Supposing the user id is "hhiillmmnnooppqqrr" and the generated token is "aabbccddeeffgg", if the user wants to request the "status" action on his account the following request must be executed:
URL for GET REQUEST: https://cloud.tanaza.com/apis/v2.0/hhiillmmnnooppqqrr/aabbccddeeffgg/status
Response
For each request a response with content-type "application/json" is returned with the following structure:
JSON Object properties:
If not equals 0 an error occurred. Please refer to the errorCode in the next paragraph.
"Status" Action Response V1
The "status" action allows you to know the following data about your account:
Networks
Access Points
SSIDs currently active on the Access Points
The users (client MAC addresses) that are connected to the Access Points
Status of each access point
"Status" Action Response V2.0
The "status" action allows the user to know the following data about his account:
1. Networks
2. Access Points
3. Ssids currently active on the Access Points
4. The users (client mac address) that are connected to the Access Points
5. Status of each Access Point
An example of the payload data structure for V1
As for the structure it contains:
A list of networks.
For each network: its label and a list of devices.
For each device: its label, its MAC address (where the first MAC address of the list is the WAN MAC address), a list of SSIDs, the timestamp of the latest packet received by Tanaza from the device (expressed in milliseconds UTC), current status of the access point (it can be "online" or "offline")
For each SSID: its label, a list of clients connected to that SSID
For each client: the client MAC address, the strenght of the signal expressed in dBm
An example of the complete response resulting data structure
An example of the payload data structure for V2.0
As for the structure it contains:
A list of networks.
For every network: its label and a list of devices.
For every device: its label, its mac addresses (where the first mac address of the list is the wan
mac address), a list of ssids,the timestamp of the latest packet received by tanaza from the
device (expressed in milliseconds UTC), current status of the access point (can be "online" or
"offline")
For every ssid: its label, a list of clients connected to that ssid
For every client: the client mac address, the strenght of the signal expressed in dBm
This is the specification of all the fields in the JSON output, with an example.
● “online” , if the access point was seen online in the last 60 seconds
● “alert” , if not in “online” state and less then 5 minutes have passed
● “offline” , it the access point was seen online the last time more then 5 minutes ago
Example: 1461644434 Stands for: 20160426T04:20:34Z
All information with prefix “last_” are referring to this timestamp.
An example of the complete response resulting data structure:
Based on the error code in the response, you can understand if the request was executed correctly.
ErrorCode Value
Description
What to do
200
Everything ok. No error occured.
The payload property contains the response.
400
Bad request. Wrong parameters specified in the request
The request was not executed correctly. Check the URL structure.
403
Authentication error
The token / user ID supplied is not valid or the user disabled the API access on its account. Or a new token was generated, invalidating the token in the request.
405
User blocked.
Contact support.
500
Request rate exceeded
Wait until the timeout of the rate exceeded ends. In the errorMessage you will find how long you should wait.
Consider that this happens only because you request too often the data from the server.
Request Rates
The APIs are not meant to be used more than once a minute.
If two or more requests are made within the same minute, the response will the previous one (Request rate exceeded), and no updated data will be sent.
So consider to request an update only once a minute, as all the other requests will be useless.
To activate the Network API on your account, please refer to sales@tanaza.com