• Ubidots Javascript Library
• Supported entities
• Supported field filters
• Installing
• Examples
  • Get devices
  • Get variables
  • Send data
• Ubidots API
  • Authentication
  • Usage
    • Methods syntax
    • Filters syntax
  • Methods
    • all
    • first
    • paginate
    • addRawParam
    • addRawParams
  • Field filters
  • Ubidots objects

This JS Library provides an intuitive and easy-to-use interface to interact with Ubidots' API. It allows sending data to devices and/or perform CRUD (Create, Read, Update, Delete) operations over the API-avaiable entities.

For the time being, the supported entities are:

• devices
• variables

The library supports all of Ubidots Field filters

Install the package running either:

npm install ubidots

or

yarn add ubidots

• Get all devices in the account:

  const allDevices = await Ubidots.devices.all();

• Get the first device in the account:

  const firstDevice = await Ubidots.devices.first();
  // This is equivalent to
  const firstDevice = (await Ubidots.devices.all())[0];

• Get the first 1000 devices in the account:

  const devicesPaginated = (await Ubidots.devices.paginate(1, 1000)).results;

• Get lastActivity field from all devices

  const allDevicesLastActivity = await Ubidots.devices.addRawParam('fields', 'lastActivity').get();

• Get lastActivity and variablesCount fields from all devices

  const devices = await Ubidots.devices.addRawParams({ fields: ['lastActivity', 'variablesCount'] }).get();

• Get lastActivity and variablesCount fields from a specific device

  const device = await Ubidots.devices
    .addRawParams({ label: 'temperature_device_1', fields: ['lastActivity', 'variablesCount'] })
    .get();

• Get a device by label or id:

  // By label
  const temperatureDevice = await Ubidots.devices.where('label').is('temperature_device_1').first();
  
  //By id
  const temperatureDevice = await Ubidots.devices.where('id').is('some-id').first();

• Get a set of devices based on their type:

  const devicesByType = await Ubidots.devices.where('deviceType').exact('temperature-devices').get();

• Get all variables in the account:

  const allVariables = await Ubidots.variables.all();

• Get the first variable in the account:

  const firstVariable = await Ubidots.variables.first();
  // This is equivalent to
  const firstVariable = (await Ubidots.variables.all())[0];

• Get the first 100 variables in the account:

  const variablesPaginated = (await Ubidots.variables.paginate(1, 100)).results;
  //Equivalent to
  const variablesPaginated = (await Ubidots.variables.paginate()).results;

• Get lastActivity field from all variables

  const allVariablesLastActivity = await Ubidots.variables.addRawParam('fields', 'lastActivity').get();

• Get lastActivity and label fields from all variables

  const variables = await Ubidots.variables.addRawParams({ fields: ['lastActivity', 'label'] }).get();

• Get lastActivity and label fields from a specific variable

  const variables = await Ubidots.variables
    .addRawParams({ id: '6452a727df1a8e000c103fce', fields: ['lastActivity', 'label'] })
    .get();

• Get a variable by id:

  const variableById = await Ubidots.variables.where('id').exact('6595770b9de79b000dce0eae').first();

• Get a set of variables based on their label:

  const devicesByType = await Ubidots.devices.where('deviceType').exact('temperature-devices').get();

Get the device object and the variable object:

// Get the device object
const temperatureDevice = await Ubidots.devices.where('label').exact('temperature_device_1').first();
// Get the variable object
const temperatureVariable = await temperatureDevice.variables.where('label').exact('temperature').first();

• Send a value

  temperatureVariable.sendDot(34);

• Send a value with timestamp

  temperatureVariable.sendDot(40, new Date().getTime());

• Send a value with timestamp and context

  temperatureVariable.sendDot(4, new Date().getTime(), { status: 'cold' });

Authentication using a valid Ubidots token is mandatory:

Ubidots.authenticate('BBFF-ubidots-token');

The following syntax provides access to the methods exposed by an Entity

Ubidots.<entity>.<method>(args)

Filters are also available for each entity, and the syntax is as follows:

Ubidots.<entity>.where(<entity-property>).<filter>(<value>)
//Ubidots.<entity>.<filter>.<modifier>.<method>(args)

• Description: Returns a list containing all the objects of an entity
• Arguments: None
• Signature: Ubidots.<entity>.all()
• Return: [{<entity_1>}, {<entity_2>}....{<entity_n>}]
• Examples:
  • Get all devices
  • Get all variables

• Description: Returns the first element in a list containing all the objects of the selected entity
• Arguments: None
• Signature: Ubidots.<entity>.first()
• Return: <entity>
• Examples
  • Get the first device
  • Get the first variable

• Description: Returns a paginator object corresponding to a paginated request to the selected entity, similar as all() but paginated.
• Arguments:
  • page: int [optional. Default -> 1] => The page number to retrieve.
  • size: int [optional. Default -> 100] => The maximum number of results per page.
• Signature: Ubidots.<entity>.paginate(, [page, size])
• Return: paginator object
• Examples
  • Get the first 1000 devices in the account
  • Get the first 100 variables in the account

• Description: Creates a custom request by adding a Query param to it.
• Arguments:
  • parameter: str [Mandatory] => The Query param to add to the request.
  • value: str | bool | int [Mandatory] => The match criteria for the Query param.
• Signature: Ubidots.<entity>.addRawParam(<parameter>, <value>)
• Return: <entity>
• Examples
  • Get last activity field from all devices
  • Get last activity field from all variables

• Description: Creates a custom request by adding multiple a Query params and their values to the request.
• Arguments:
  • queryObject: Object => An object containing on the root level, keys representing they Query params, and their respective values is the matching criteria for the corresponding query param:

  {
    "queryParam1" : matchingCriteria1,
                    .
                    .
                    .
    "queryParamN" : matchingCriteriaN,
  }

• Signature: Ubidots.<entity>.addRawParams(<queryObject>)
• Return: <entity>
• Examples
  • Get lastActivity and variablesCount fields from all devices
  • Get lastActivity and variablesCount fields from a specific device
  • Get lastActivity and label fields from all variables
  • Get lastActivity and label fields from a specific variable

By applying Field filters on entitie's properties, it is possible to perform requests on a particular set of such entities.

For example, if it is required to retrieve data from all of the devices whose label start with the

When invoked, the paginate method returns a paginator object with the following properties and methods:

{
  next(): `<paginator>`,    // Returns a new instance of the paginator object, with the page property set to the next page (one ahead of the current page).
  previous(): `<paginator>`,  // Returns a new instance of the paginator object, with the page property set to the previous page (one less than the current page).
  refresh(): `<paginator>`,   // Re-executes the current request and returns the updated paginator object with refreshed data.
  page: `int`,                // Represents the current page number in the pagination sequence.
  results: `Array[<entity>]`,  // An array of entity objects present on the current page.
  size: `int`,                // Indicates the count of entity objects in the current page.
}