>

REST API Reference

What is a RESTful API?

Although most software developers already know this, many of us -hardware people- don’t know what a REST API means.

In the Internet of People, we navigate the web through web browsers and a screen. Meanwhile, in the Internet of Things, devices are limited in terms of battery, visual interfaces or processing power, so they need a special way to interact with the web. This “web interface for devices” is what we call an API, which stands for “Application Programming Interface”.

On the other hand, “RESTful” means, among other things, that this API talks HTTP (the same protocol browsers use to communicate with web pages), a very standard way to communicate in the World Wide Web. The Ubidots API supports four HTTP methods:

  • GET - Used to retrieve information from the cloud
  • POST - Used to create a new element inside the cloud
  • PUT - Used to edit existing elements
  • DELETE - Used to delete existing elements

This API Documentation specifies the structure of the data that is exchanged between your devices and the Ubidots Cloud, along with code examples and libraries to speed up your project.

Authentication

API access can be over HTTP or HTTPS, using the following URLs:

http://things.ubidots.com/api/v1.6/

or

https://things.ubidots.com/api/v1.6/

The relative path prefix /v1.6/ indicates that we are currently using version 1.6 of the API.

Http Request

POST /api/v1.6/auth/token HTTP/1.1
Host: things.ubidots.com
X-Ubidots-ApiKey: YOUR-API-KEY

Example request

# Request

curl -X POST "http://things.ubidots.com/api/v1.6/auth/token" -H "X-Ubidots-ApiKey: ab2ee82d3a50cb8f1d2567eb8bd3a10528494426"

# Response
{
    "token": "f6j9QGZqzsobNHZMFZ8UNWpPXOa0v8LCtu3UuZyS32KbUwJyA"
}

Every request requires a TOKEN. The easiest way to get yours is clicking on “API Credentials” under your profile tab:

You’ll notice there are two types of keys in your Ubidots account:

  • Tokens: Temporary and revocable keys to be used in your API requests.
  • API Key: This is your “Master Key”; a unique and inmutable key that is used only to generate your account’s tokens.

To create tokens through the API, make a POST request to:

http://things.ubidots.com/api/v1.6/auth/token

  • Tokens created through the /auth/token endpoint will expire after 6 hours if not used. This is a standard security measure.
  • Tokens created in your account profile will never expire

How to use your TOKEN

Http Request with token in URL

GET /api/v1.6/variables?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG HTTP/1.1
Host: things.ubidots.com

Http Request with token in headers

GET /api/v1.6/variables HTTP/1.1
Host: things.ubidots.com
X-Auth-Token: MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

Both requests are equivalent

Let’s make a simple request to get the variables in our account. There are two ways to send a TOKEN in a request:

  • Send the token inside the URL using the ?token= parameter. This is the easiest one to implement.
  • Send the token as a header using the X-Auth-Token header

Both requests are equivalent.

Values

Send values

Http Request to send values to a Device

POST /api/v1.6/devices/{LABEL_DEVICE}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 76

{"temperature": 10, "luminosity": {"value":10}, "wind_speed": [{"value": 11, "timestamp":10000}, {"value": 12, "timestamp":13000}]}

Example request

# Request

curl -X POST -H "Content-Type: application/json" -d '{"temperature": 10, "luminosity": {"value":10}, "wind_speed": [{"value": 11, "timestamp":10000}, {"value": 12, "timestamp":13000}]}' http://things.ubidots.com/api/v1.6/devices/weather-station?token=c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5

# Response
{
    "wind_speed": [{"status_code": 201}, {"status_code": 201}],
    "luminosity": [{"status_code": 201}],
    "temperature": [{"status_code": 201}]
}

The easiest way to send values to Ubidots is specifying your Device label in the URL and making a POST request to it:

http://things.ubidots.com/api/v1.6/devices/{LABEL_DEVICE}/

The Http body should be a JSON dictionary where every key corresponds to the unique label of each variable, and every value can be any of the following:

  • A float or integer number. For example:

{"temperature": 10, "humidity": 50}

  • A JSON object containing the “value”, “timestamp” and “context” of the data point. For example:

{"temperature": {"value":10, "timestamp": 1464661369000, "context":{"lat":-6.2, "lng":75.4, "my-key":"hello there"}}, "humidity": 50}

  • A list of JSON objects, each one containing the “value” key, and optionally the “timestamp” and “context” of the data point. For example:

{"temperature":[{"value": 10, "timestamp":1464661369000}, {"value": 12, "timestamp":1464661369999}], "humidity": 50}

Accepted values for “value”, “timestamp” and “context” keys are:

value
required
Float or integer number.
Example: "value": "35.8" or "value": 35.8
context A JSON object with optional meta data as “key”:“value” pairs.
Example: "context": {"lat": 6.1, "lng": -35.1, "status": "driving"}
timestamp Optional timestamp in milliseconds, according to the POSIX standard.
Example: "timestamp":1376056359000

Send values to one variable

Http Request to send values to a variable

POST /api/v1.6/devices/{LABEL_DEVICE}/{VARIABLE_LABEL}/values/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 76

{"value":11.21, "context":{"lat":1.12, "lng":2.019}, "timestamp":1000199992}

Example request to send a single value using the variable’s label

# Request

curl -X POST -H "Content-Type: application/json" -d '{"value":11.21, "context":{"lat":1.12, "lng":2.019}, "timestamp":1000199992}' http://things.ubidots.com/api/v1.6/devices/lora-device/temperature/values?token=c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5

# Response
{
    "url":
    "http://things.ubidots.com/api/v1.6/values/5735e81d5753c953fdfc54c3",
    "value": 11.21,
    "timestamp": 1000199992,
    "context": {"lat": 1.12, "lng": 2.019},
    "created_at": "2016-05-13T14:43:41.693"
 }

Example request to send multiple values using the variable’s label

# Request

curl -X POST -H "Content-Type: application/json" -d '[{"value":11.21, "context":{"lat":1.12, "lng":2.019}, "timestamp":1000199992}, {"value":5.21, "context":{"lat":1.12, "lng":2.019}, "timestamp":1000199999}]' http://things.ubidots.com/api/v1.6/devices/lora-device/temperature/values?token=c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5

# Response
[
    {"status_code": 201},
    {"status_code": 201}
]

To send a value to a variable, specify the datasource and variable labels in the URL and make a POST request to:

http://things.ubidots.com/api/v1.6/devices/{LABEL_DEVICE}/{VARIABLE_LABEL}/values

The body of the POST request can be either:

  • A JSON object containing the “value” key, and optionally the “timestamp” and “context” of the data point. For example:

{"value":10}

or

{"value":10, "timestamp": 1464661369000, "context":{"lat":-6.2, "lng":75.4}}

  • A list of JSON objects, each one containing the “value” key, and optionally the “timestamp” and “context” of the data point:

[{"value": 10, "timestamp":1464661369000}, {"value": 12, "timestamp":1464661369999}]

Accepted values for “value”, “timestamp” and “context” keys are:

value
required
Float or integer number.
Example: "value": "35.8" or "value": 35.8
context A JSON object with optional meta data as “key”:“value” pairs.
Example: "context": {"lat": 6.1, "lng": -35.1, "status": "driving"}
timestamp Optional timestamp in milliseconds, according to the POSIX standard.
Example: "timestamp":1376056359000

Http Request to send a value using the variable’s ID

POST /api/v1.6/variables/{VAR_ID}/values/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 17

{"value": "35.8"}

Example request to send a value using the variable’s ID

# Request

curl -X POST -H "Content-Type: application/json" -d '{"value": "35.8"}' http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "url": "http://things.ubidots.com/api/v1.6/values/568442e77625426cd410eec0",
  "value": 35.8,
  "timestamp": 1451508455551,
  "context": {},
  "created_at": "2015-12-30T20:47:35.551"
}

Example request adding “context” with GPS location

curl -X POST -H "Content-Type: application/json" -d '{"value": "35.8", "context": {"lat": 6.1, "lng": -35.1, "status": "driving"}}' http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

Example request specifying a “timestamp”

curl -X POST -H "Content-Type: application/json" -d '{"value": "52.1", "timestamp": 1376056359000}' http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

Http Request to send several values using the variable’s ID

POST /api/v1.6/variables/{VAR_ID}/values/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 82

[{"value":22, "timestamp":1383497090000}, {"value":23, "timestamp":1383497090001}]

Example request to send several values using the variable’s ID

# Request

curl -X POST -H "Content-Type: application/json" -d '[{"value":22, "timestamp":1383497090000}, {"value":23, "timestamp":1383497090001}]' http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
[{"status_code": 201}, {"status_code": 201}]

Example request adding the “?force=true” parameter

# Request

curl -X POST -H "Content-Type: application/json" -d '[{"value":"xxx", "timestamp":1383497090000}, {"value":23, "timestamp":1383497090001}]' http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?force=true&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
[{"status_code": 400, "errors": {"value": ["'xxx' value must be a float."]}}, {"status_code": 201}]







You can also send values to a variable using its ID instead of its label. To do this, make a POST request to:

http://things.ubidots.com/api/v1.6/variables/{VAR_ID}/values

With an Http body as explained above.

This endpoint accepts the force parameter; when false (default), the system will reject all values if there’s one of them with an error. When true, the system will create the valid values and reject only the ones with errors.

Send values to many variables

Http Request

POST /api/v1.6/collections/values/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 112

[{"variable": "{VAR-ID-1}", "value":41.2}, {"variable": "{VAR-ID-1}", "value":88.3}]

Example request

# Request

curl -X POST -H "Content-Type: application/json" -d '[{"variable": "568405d376254261ef114f35", "value":41.2}, {"variable": "56843ac776254258956b9c05", "value":88.3}]' http://things.ubidots.com/api/v1.6/collections/values/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
[{"status_code": 201}, {"status_code": 201}]

Example request adding the “?force=true” parameter

# Request

curl -X POST -H "Content-Type: application/json" -d '[{"variable": "568405d376254261ef114f35", "value":41.2}, {"variable": "56843ac776254258956b9c05", "value": "xxx"}]' "http://things.ubidots.com/api/v1.6/collections/values/?force=true&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG"

# Response
[{"status_code": 201}, {"status_code": 400, "errors": {"value": ["'xxx' value must be a float."]}}]

To update several variables at the same time make a POST request to:

http://things.ubidots.com/api/v1.6/collections/values

Indicating the IDs of the variables to update and their values:

[{"variable": "{VAR_ID_1}", "value":41.2}, {"variable": "{VAR_ID_1}", "value":88.3}]

This endpoint also accepts the “timestamp” and “context” keys.

Accepted parameters in the URL:

force When false (default), the system will reject all values if there’s one of them with an error.

When true, the system will create the valid values and reject only the ones with errors.

Get values

Http Request to get values using the variable’s label

GET /api/v1.6/devices/{LABEL_DEVICE}/{VARIABLE_LABEL}/values?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request to get values using the variable’s label

# Request: Retrieve all the values of a variable with label "Temperature" and datasource with label "WiFi-Device":

curl -X GET http://things.ubidots.com/api/v1.6/devices/WiFi-Device/Temperature/values?token=c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5

# Sample Response
[
    {
        "url": "http://things.ubidots.com/api/v1.6/values/573644685753c902de57d125",
        "value": 21.21,
        "timestamp": 1463174248257,
         "context": {"lat": 1.12, "lng": 2.019},
         "created_at": "2016-05-13T21:17:28.257"},
    {
        "url": "http://things.ubidots.com/api/v1.6/values/573644265753c902de57d124",
        "value": 11.21,
        "timestamp": 1463174182784,
        "context": {"lat": 1.12, "lng": 2.019},
        "created_at": "2016-05-13T21:16:22.784"
    }
]

Http Request to get values using the variable ID

GET /api/v1.6/variables/{VAR_ID}/values?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request

# Request: Retrieve the last 10 values of the variables with ID = "568405d376254261ef114f35"

curl "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?page_size=10&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG"

# (Sample response omitted - too long to print here!)

Example request #2: Export the values as CSV

# Request: Retrieve the last 10 values of the variables with ID = "568405d376254261ef114f35"

curl "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?page_size=10&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG&format=csv"

# Response
context.lat,context.lng,context.status,created_at,timestamp,value
,,,2015-12-30 21:39:55.036000,1451511595036,41.2
,,,2015-12-30 21:33:41.524000,1451511221524,41.2
,,,2015-12-30 21:31:00.197000,1451511060197,41.2
,,,2015-12-30 21:16:02.630000,1451510162630,41.2
,,,2015-12-30 21:15:01.612000,1451510101612,41.2
,,,2015-12-30 21:14:03.723000,1451510043723,41.2
,,,2015-12-30 21:13:55.147000,1451510035147,41.2
,,,2015-12-30 21:13:41.187000,1451510021187,41.2
,,,2015-12-30 21:09:10.527000,1451509750527,41.2

Example request #3: Send the values to an Email

# Request

curl "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values/?page_size=10&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG&action=send_by_email&email=info@ubidots.com"

# Response
{
    "status": "sent_via_email"
}

To get the values of a variable using its label, make a GET request to:

http://things.ubidots.com/api/v1.6/devices/{LABEL_DEVICE}/{VARIABLE_LABEL}/values

To get the values of a variable using its ID, make a GET request to:

http://things.ubidots.com/api/v1.6/variables/{VAR_ID}/values

It is possible to retrieve a subset of values given their time range. Use the start and end parameters to do this:

start Returns values after this timestamp, inclusive with this timestamp. May be used in conjunction with the end parameter. Example:
?start=1451170441000
end Returns values before this timestamp, inclusive with this timestamp. May be used in conjunction with the start parameter. Example:
?end=1451570441000
format Specifies the format of the returned values:
?format=csv: Returns a CSV file.
?format=json: Returns a JSON formated text.
action &
email
Queues the request to be sent per Email to the specified Email address as a CSV file - useful when requesting a large subset of values. Both parameters are to be used together. Example:
?action=send_by_email&email=johndoe@email.com
page_size Specifies the amount of elements to list per page (30 by default). Example:
?page_size=100 will return a hundred values.
page Specifies the page number to retrieve. Example:
?page_size=100&page=2 will return a hundred values, from #101 to #200.

Delete values

Http Request

DELETE /api/v1.6/variables/{VAR_ID}/values/{START}/{END}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request

# Request: Delete all values between timestamps 1447136223927 and 1449419580541:

curl -X DELETE "http://things.ubidots.com/api/v1.6/variables/561ecb647625425fd0dfec9c/values/1447136223927/1449419580541/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG"

# Response
{
    "count": 7200
}

To delete a set of values in your account make a DELETE request to:

http://things.ubidots.com/api/v1.6/variables/{VAR_ID}/values/{START}/{END}/

Values between the {START} timestamp and the {END} timestamp will be deleted.

Variables

Create a variable

Http Request

POST /api/v1.6/datasources/{DS_ID}/variables/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 35

{"name":"Temperature", "unit":"ºC"}

Example request

# Request

curl -X POST -H "Content-Type: application/json" -d '{"name": "Temperature", "unit":"ºC"}' http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4/variables/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "id": "568405d376254261ef114f35",
  "name": "Temperature",
  "icon": "",
  "unit": "\u00baC",
  "datasource":
    {
      "id": "5683fae97625424a4d8e17b4",
      "name": "My Datasource #2",
      "url": "http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4"
    },
  "url": "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35",
  "description": null,
  "properties": {},
  "tags": [],
  "values_url": "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values",
  "created_at": "2015-12-30T16:26:59.684",
  "last_value": {},
  "last_activity": null,
  "type": 0,
  "derived_expr": ""
}

The easiest way to create a variable is sending a value directly to it as explained in the Send values section. This will automatically create a variable if it doesn’t exist.

To create a variable using the Device ID, make a POST request to:

http://things.ubidots.com/api/v1.6/datasources/{ds_id}/variables

Indicating at least the name of the Variable in a JSON object in the Http body:

{"name":"Temperature"}

Accepted fields are:

name
required
String with the name of the variable.
Example: "name":"Temperature"
unit String with the unit of the variable.
Example: "unit":"ºC"
description String describing the variable.
Example: "description":"This is a DS18B20 sensor"
properties An object with optional meta data as “key”:“value” pairs.
Example: "properties": {"place": "House"}
tags A list of tags separated by commas.
Example: "tags":["factory", "Main tank"]

Get a variable

Http Request to get a variable using its label

GET /api/v1.6/devices/{LABEL_DEVICE}/{VARIABLE_LABEL}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request to get a variable using its label

# Request

curl -X GET http://things.ubidots.com/api/v1.6/devices/wifi-module/temperature/?token=c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5

# Response
{
    "id": "573644265753c902de57d123",
    "name": "temperature",
    "icon": "",
    "unit": null,
    "label": "temperature",
    "datasource":
    {
        "id": "573644265753c902de57d121",
        "name": "wifi-module",
        "url": "http://things.ubidots.com/api/v1.6/datasources/573644265753c902de57d121"
     },
     "url": "http://things.ubidots.com/api/v1.6/variables/573644265753c902de57d123",
     "description": null,
     "properties": {"_last_value": {"timestamp": 1463174248257, "value": 21.21,
     "context": {"lat": 1.12, "lng": 2.019}},
     "_last_activity": 1463174248000}, "tags": [],
     "values_url": "http://things.ubidots.com/api/v1.6/variables/573644265753c902de57d123/values",
     "created_at": "2016-05-13T21:16:22.772",
     "last_value": {"timestamp": 1463174248257, "value": 21.21,
     "context": {"lat": 1.12, "lng": 2.019}},
     "last_activity": 1463174248000, "type": 0, "derived_expr": ""
}

Http Request to get a variable using its ID

GET /api/v1.6/variables/{VAR_ID}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request to get a variable using its ID

# Request

curl http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "id": "568405d376254261ef114f35",
  "name": "Temperature",
  "icon": "",
  "unit": "\u00baC",
  "datasource":
  {
    "id": "5683fae97625424a4d8e17b4",
    "name": "My Datasource #2",
    "url": "http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4"
  },
  "url": "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35",
  "description": null,
  "properties":
  {
   "_last_value":
   {
    "timestamp": 1383497090001,
     "value": 23.0,
     "context": {}
   },
   "_last_activity": 1451513333000
  },
  "tags": [],
  "values_url": "http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/values",
  "created_at": "2015-12-30T16:26:59.684",
  "last_value":
  {
    "timestamp": 1383497090001,
    "value": 23.0,
    "context": {}
  },
  "last_activity": 1451513333000,
  "type": 0,
  "derived_expr": ""
}

To get the details of a variable, make a GET request to:

http://things.ubidots.com/api/v1.6/devices/{LABEL_DEVICE}/{VARIABLE_LABEL}/

To can also get the details of a variable using its ID, and making a GET request to:

http://things.ubidots.com/api/v1.6/variables/{VAR_ID}/

List variables

Http Request to list variables of a Device

GET /api/v1.6/datasources/{DS_ID}/variables/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request to list variables of a Device

# Request

curl http://things.ubidots.com/api/v1.6/datasources/5683f80476254244b1ad2b01/variables/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# (Sample response omitted - too long to print here!)

Example request filtered by tags

# Request

curl "http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4/variables/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG&tag=weather"

# (Sample response omitted - too long to print here!)

Http Request to list all variables

GET /api/v1.6/variables/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request to list two vraiables

# Request (retrieve 2 variables with parameter "page_size=2")

curl "http://things.ubidots.com/api/v1.6/variables/?page_size=2&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG"

# (Sample response omitted - too long to print here!)

Example request to list variables filtered by tags

# Request

curl "http://things.ubidots.com/api/v1.6/variables/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG&tag=weather&tag=sky"

# Response
{
  "count": 1,
  "next": null,
  "previous": null,
  "results":
  [{
    "id": "5683faf576254248ffd9e46f",
    "name": "Var B",
    "icon": "",
    "unit": "",
    "datasource":
    {
      "id": "5683fae97625424a4d8e17b4",
      "name": "My Datasource #2",
      "url": "http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4"
    },
  "url": "http://things.ubidots.com/api/v1.6/variables/5683faf576254248ffd9e46f",
  "description": "",
  "properties": {},
  "tags": ["sky", "weather"],
  "values_url": "http://things.ubidots.com/api/v1.6/variables/5683faf576254248ffd9e46f/values",
  "created_at": "2015-12-30T15:40:37.617",
  "last_value": {},
  "last_activity": null,
  "type": 0,
  "derived_expr": ""
  }]
}

To list the variables in your account make a GET request to:

http://things.ubidots.com/api/v1.6/variables/

To list the variables of a Device make a GET request to:

http://things.ubidots.com/api/v1.6/datasources/{DS_ID}/variables/

This endpoint accepts the pagination parameters, plus a “tag” parameter for filtering purposes:

page_size Specifies the amount of elements to list per page (30 by default). Example:
?page_size=100 will return the first hundred variables.
page Specifies the page number to retrieve. Example:
?page_size=100&page=2 will return a hundred variables, from #101 to #200.
tag Filter results to variables containing the specified tags (you can use one or more filters). Example:
?tag=weather&tag=sky will return variables containing the tags “weather” AND “sky”.

Delete a variable

Http Request

DELETE /api/v1.6/variables/{VAR_ID}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request

# Request

curl -X DELETE http://things.ubidots.com/api/v1.6/variables/5683faf17625424c0bc280ed/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
# * The response does not contain a BODY, only a response code is returned meaning the item was successfully deleted:

204 NO CONTENT

To delete a variable, make a DELETE request to:

http://things.ubidots.com/api/v1.6/variables/{VAR_ID}/

Devices

Create a Device

Http Request

POST /api/v1.6/datasources/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com
Content-Type: application/json
Content-Length: 21

{"name":"Water Tank"}

Example request

# Request

curl -X POST -H "Content-Type: application/json" -d '{"name": "Water Tank"}' http://things.ubidots.com/api/v1.6/datasources/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "id": "5684415076254267da0414cf",
  "owner": "http://things.ubidots.com/api/v1.6/users/7061",
  "parent": null,
  "name": "Water Tank",
  "url": "http://things.ubidots.com/api/v1.6/datasources/5684415076254267da0414cf",
  "context": {},
  "tags": [],
  "created_at": "2015-12-30T20:40:48.676",
  "variables_url": "http://things.ubidots.com/api/v1.6/datasources/5684415076254267da0414cf/variables",
  "number_of_variables": 0,
  "last_activity": null,
  "description": null
}

The easiest way to create a Device is sending a value directly to it as explained in the Send values section. This will automatically create a Device if it doesn’t exist.

You can also create an empty Device by making a POST request to:

http://things.ubidots.com/api/v1.6/datasources/

and indicating at least the name of the Device in a JSON object in the Http body:

{"name":"Water Tank"}

Accepted fields are:

name
required
String with the name of the Device.
Example: "name":"Water Tank"
description String describing the Device.
Example: "description":"This is a water tank"
context An object with optional meta data as “key”:“value” pairs.
Example: "context": {"customer": "ABC Systems"}
tags A list of tags separated by commas.
Example: "tags":["factory", "Main tank"]

Get a Device

Http Request

GET /api/v1.6/datasources/{DS_ID}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request

# Request

curl http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "id": "5683fae97625424a4d8e17b4",
  "owner": "http://things.ubidots.com/api/v1.6/users/7061",
  "parent": null,
  "name": "My Datasource #2",
  "url": "http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4",
  "context": {
    "_last_activity": 1451513333000,
    "_icon": "generic-ds"
  },
  "tags": [],
  "created_at": "2015-12-30T15:40:25.180",
  "variables_url": "http://things.ubidots.com/api/v1.6/datasources/5683fae97625424a4d8e17b4/variables",
  "number_of_variables": 8,
  "last_activity": 1451513333000,
  "description": ""
}

To get the details of a Device, make a GET request to:

http://things.ubidots.com/api/v1.6/datasources/{DS_ID}/

List Devices

Http Request

GET /api/v1.6/datasources/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request

# Request (retrieve 20 Devices with parameter "page_size=20" and "tag=car")

curl "http://things.ubidots.com/api/v1.6/datasource/?page_size=20&tag=car&token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG"

# (Sample response omitted - too long to print here!)

To list a set of Devices in your account make a GET request to:

http://things.ubidots.com/api/v1.6/datasources/

This endpoint accepts the pagination parameters, plus a “tag” parameter for filtering purposes:

page_size Specifies the amount of elements to list per page (30 by default). Example:
?page_size=100 will return the first hundred items.
page Specifies the page number to retrieve. Example:
?page_size=100&page=2 will return a hundred items, from #101 to #200.
tag Filter results to items containing the specified tags (you can use one or more filters). Example:
?tag=car&tag=DFT361 will return items containing the tags “car” AND “DFT361”.

Delete a Device

Http Request

DELETE /api/v1.6/datasources/{DS_ID}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request

# Request

curl -X DELETE http://things.ubidots.com/api/v1.6/datasources/5684415076254267da0414cf/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
# * The response does not contain a BODY, only a response code is returned meaning the item was successfully deleted:

204 NO CONTENT

To delete a Device, make a DELETE request to:

http://things.ubidots.com/api/v1.6/datasources/{DS_ID}/

Statistics

Get a statistic over a subset of values

Http Request

GET /api/v1.6/variables/{VAR_ID}/statistics/{FIG}/{START}/{END}/?token={TOKEN} HTTP/1.1
Host: things.ubidots.com

Example request: Obtaining the main of all values

# Request

NOW=$(date +%s)000
curl -X GET http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/statistics/mean/0/$NOW/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "mean": 39.01176470588236
}

Example request: Computing multiple figures in a single request

# Request

NOW=$(date +%s)000
curl -X GET http://things.ubidots.com/api/v1.6/variables/568405d376254261ef114f35/statistics/mean,variance,min,max,count,sum/0/$NOW/?token=MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

# Response
{
  "count": 17,
  "min": 22.0,
  "max": 52.1,
  "sum": 663.2,
  "variance": 57.21986159169533,
  "mean": 39.01176470588236
}

To compute a statistic over a subset of values, make a GET request to:

http://things.ubidots.com/api/v1.6/variables/{VAR_ID}/statistics/{FIG}/{START}/{END}/

The figure is given by {FIG} and the subset is given by the values between {START} and {END}.

figure A comma seperated value list of statistical figures to be computed. Supported operations are:
- mean
- variance
- min
- max
- count
- sum
start The starting timestamp in milliseconds. The range is inclusive with this value.
end The ending timestamp in milliseconds. The range is inclusive with this value.

Get resampled values

The rolling window endpoint allows you to compute an operation (mean, max, min, sum or count) over a rolling time window: every 5 minutes, 1 hour, 1 week, etc. It can either return a set of values, or create a new variable in your account with the new re-sampled values, so it can be used in dashboards, events or future API calls.

This endpoint’s documentation is not public yet. If you’d like more details, drop us an email at support@ubidots.com.

Pagination

Http Request

GET /api/v1.6/variables?page_size=5&page=2 HTTP/1.1
Host: things.ubidots.com
X-Auth-Token: MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG

Example request

# Will list variables from #6 to #10 (page size = 5, page number = 2)

curl "http://things.ubidots.com/api/v1.6/variables?page_size=5&page=2" -H "X-Auth-Token: MtRbM7ipKUsjRh6RwJE0ofIQo0KqoG"

API calls listing multiple items will return 30 items by default. You can change this number using the pagination parameters inside the URL of the request:

page_size Specifies the amount of elements to list per page (30 by default). Example:
?page_size=100 will return the first hundred items.
page Specifies the page number to retrieve. Example:
?page_size=100&page=2 will return a hundred items, from #101 to #200.

In the response, the count field will tell you the total number of items available.

Response Codes

The Ubidots API uses the following response codes:

Code Meaning
200 Ok – Successful request.
201 Created – Successful request + an item was created.
400 Bad Request – Error due to an invalid body in your request. Please verify it’s a valid JSON string and that the fields are the ones expected by the endpoint (string, object or float).
403 Forbidden – This token is not valid. Please verify your token.
404 Not Found – We couldn’t find the variable or Device you are trying to access. Verify your token and item’s ID.
405 Method Not Allowed – This API endpoint does not accept the method used. Check our API docs to see the allowed methods.
50* Internal Error – We’re having issues with our servers. Please check our status page.



GET STARTED
Join thousands of fellow IoT developers using Ubidots to build production-ready IoT solutions.

Sign up for free