API

It is easy to connect electronic devices, data sources, and even third party APPs to your account using Tago API (Application Programming Interface).

We have a comprehensive set of APIs that give you full control to manage your accounts, data, devices, dashboards, and scripts. For example, you can use the resources available in the Admin page to create, delete, or edit your accounts and dashboards; however, you can do all the same things directly using API.

We follow RESTful principles. Before checking the API documentation, there are some details you should know.

All responses from Tago API have a pattern, and you will always receive something like this:

// For success:
{
        'status': true,
        'result': [...]
}

// For warning:
{
        'status': true,
        'result': {...},
        'message': 'Warning message'
}

// For failed:
{
        'status': false,
        'message': 'Error message'
}

status: it is always boolean. If your request is successful the response will be true, otherwise it will be false.

result: can be any object type (that is dynamic object), depends what api endpoint you called for.

message: it is message from the server. Usually it is used when has any error or warning.

Security

Tago takes the necessary steps to protect your data in the database and also during the communication between our server and your devices.

All communication between the devices, your application, and Tago server is performed through Hypertext Transfer Protocol Secure (HTTPS) to avoid the man-in-the-middle and wiretapping attacks.

Although the communication can also be performed with HTTP, Tago doesn’t recommend it. By doing so will eliminate the security of authentication and encryption provided by SSL/TLS protocols part of HTTPS. Just in case you really need to use HTTP without SSL, all you have to do is to add _ssl=false on the header or url query string.

Secret tokens for account and devices are generated by Tago system and can be individually managed by the user. Different levels of access can be granted to different users or devices.

The URL that your device should connect is https://api.tago.io/data through Port 443.

Tokens

There are two type of tokens: Account-Token and Device-Token.

You are able to generate both tokens from Tago admin or directly using API. The type of token and its expiration can also be defined.

Using tokens is simple, just add them in the header of the request.

HEADER KEY HEADER VALUE
Account-Token Only Account Token
Device-Token Only Device Token
Authentication Any Token (Account or Device)

Usage Policy

When executing a request to Tago, through POST, GET, DELETE or PUT, your account may face our blocking limit policy based on your account settings and the frequency of API requests. Such blocking system helps to prevent attacks to our servers, like DDOS, and offers a way to limit the usage for your applications.

Based on our estimation, for the majority of our users, such policy will not cause problems to their applications. The limit is based on the number of requests per certain period of time.

There are three limit levels that will be triggered based on the number of requests per hour in your account. As you reach 50%/80%/100% of your limit, Tago will automatically send you warning emails.

Token Requests per hour
Account-Token / Device-Token 10,000 requests. Both accesses share the same request limit.
Public-Token 10,000 requests

If for some reason you need to do more requests than our default account setting allows, you can contact us directly.

Send Data

A device can send data to Tago by using the POST method.

POST - https://api.tago.io/data

KEY TYPE REQUIRED
variable string * yes
unit string no
value string ** no
time string no
serie string no
location object || geojson no
metadata object no

Request

{
    "variable": "temperature",
    "unit"    : "F",
    "value"   : 55,
    "time"    : "2015-11-03 13:44:33",
    "location": {"lat": 42.2974279, "lng": -85.628292}
}

It’s possible to send more than one data at same time, using an array.

[{
    "variable": "temperature",
    "unit"    : "F",
    "value"   : 55,
}, {
    "variable": "temperature_celsius",
    "unit"    : "C",
    "value"   : 12,
}]

(*) Variable field should no contain special characters like *?!<>.-=$ or space. Also, notice that the varianle will always be converted to lowercase in our database.

(**) In order to make easier for users to see their data in charts and dials, Tago will always try to convert the value to a number format (integer), even if it came as string. However, due to the range limitation, the automatic conversion will be done only for strings shorter than 15 characters. If a value originally is formed by a string longer than this length limitation, it will NOT be converted to a number.

Delete Data

DELETE - https://api.tago.io/data/:id

DELETE - https://api.tago.io/data
DELETE - https://api.tago.io/data?qty=:qty

DELETE - https://api.tago.io/data/:variable_name
DELETE - https://api.tago.io/data/:variable_name?qty=:qty

Each time you insert a data, an ID is associated with it. You can read this ID by using the GET method.

Delete method can be used in 3 forms: without argument, with variable, or with ID.  If no argument is specified at all, the most recent data inserted into your bucket will be removed.

You can pass a query parameter qty to specify a number of records you want to delete. It will not work when deleting by ID, only for variable or without a parameter:

Examples:
Delete the last 10 records in the variable temperature
https://api.tago.io/data/temperature?qty=10

Delete the all records for variable temperature
https://api.tago.io/data/temperature?qty=all

Delete the all records from the device
https://api.tago.io/data?qty=all

Delete the record by its ID
https://api.tago.io/data/579a3c22861e23d02162e87f

Get Data

GET - https://api.tago.io/data

KEY TYPE DESCRIPTION
variable || s string || array Get variables
query string Query pre-defined by Tago
qty string Maximum number of data to be returned
start_date string Start date
end_date string End date
detail bool Add more JSON fields on result

Response - Below is the data returned without any parameters. https://api.tago.io/data

{
    "status" : true,
    "result": [
        {
            "id": "547e42847dbf3af122c02582",
            "location": {
                "coordinates": [
                    41.878876,
                    -87.635915
                ],
                "type": "Point"
            },
            "time": "2014-12-02T22:51:48.005Z",
            "variable": "location"
        }, {
            "id": "547e353d7dbf3af122c0257d",
            "time": "2014-12-02T21:55:09.301Z",
            "unit": "%",
            "value": 32,
            "variable": "fuel_level"
        },  {
            "id": "547e41f97dbf3af122c02580",
            "time": "2014-12-02T22:49:29.777Z",
            "unit": "psi",
            "value": 25,
            "variable": "oil_pressure"
        }
    ]
}

Variables

variable - using parameter variable you define the variable that should be returned with the GET method.

For example, to get data with the variable = temperature, use: https://api.tago.io/data?variable=temperature.

Also, you can use the array to get more variables: https://api.tago.io/data?variable[]=temperature&variable[]=pressure

Query

query - query parameter returns some predefined functions to help you to obtain certain processed data. Note that you can not use two queries concurrently.

QUERY DESCRIPTION
max Get data with the highest value
min Get data with the lowest value
count Return the number of data located in the bucket
last_value Get the last data with field value not empty
last_location Get the last data with field location not empty
last_item Get the last data, not checking if the fields location or value is empty

* Need additional parameters

Quantity

qty - Limit the number of results that will be returned from a query. The default value is 15.

Start Date - End Date

start_date - Define the start time for the data search. Only the data containing ‘time’ information newer than start_date will be returned.

end_date - Define the end time for the data search. Only the data containing ‘time’ information older than end_date will be returned.

Start/End date parameters accept different formats, which include selection based on relative time (e.g. to get data from the last 1 hour). Below are some examples:

DATE FORMATS
“2014-12-25”
“2014-12-25 23:33:22”
“Thu Dec 25 2014 23:33:22 GMT+1300 (NZDT)”
“1 hour”
“1 day”
“1 month”
“1 year”
  • Relative dates will be subtracted or added to the current time.

Devices

Using the account-token, you can manage your devices through API requests. It’s possible to create, edit, delete, and get info of it.

Create

Create a device through POST method.

POST - https://api.tago.io/device

KEY TYPE REQUIRED
name string yes
description string no
active boolean no
visible boolean no
configuration_params* array no
tags * array no
* configuration_params and tags are expected to receive an array of objects.
For tags it is expected to receive an object containing key (string) and value (string).
For configuration_params it is expected to receive an object containing sent (bool), key (string) and value (string).

Request

{
    "name":        "My first device",
    "description": "Creating my first device",
    "active":      true,
    "visible":     true,
    "tags": [
        {"key": "client", "value": "John"}
    ]
    "configuration_params": [
        {"sent": false, "key": "check_rate", "value": 600}
        {"sent": false, "key": "measure_time", "value": 0}
    ]
}

Info

Retrieve informations for a device, using it’s ID.

GET - https://api.tago.io/device/:id

Response

{
    "status": true,
    "result": {
        "created_at": "2016-11-03T23:24:19.787Z",
        "updated_at": "2016-11-03T23:24:19.787Z",
        "last_access": "2016-11-03T23:24:19.787Z",
        "visible": true,
        "active": true,
        "tags": [
            {"key": "client", "value": "John"}
        ],
        "name": "My Device",
        "id": "581bc7233148f62587e2d507",
        "configuration_params": [
            {"sent": false, "key": "check_rate", "value": "600"}
            {"sent": false, "key": "measure_time", "value": ""}
        ],
        "bucket": {
            "name": "My Bucket",
            "id": "577bdd94567190920cfe9cfd"
        }
    }
}

List

Retrieve a list of all devices in the account

GET - https://api.tago.io/device

Delete

DELETE - https://api.tago.io/device/:id

Response

{
    "status": true,
    "result": "Successfully Removed"
}