Things

In the previous walkthroughs, we've primarily discussed the structure of Places. Here we're working with the various devices and equipment - the "things" in "Internet of Things". HVAC systems, security systems, lighting, badge readers, elevators and much more.

We ingest device data in two ways:

Cloud or Physical Gateway

Our gateway, either an actual piece of hardware or a cloud based software option, gets installed in your building. It then automatically retrieves all of the device data, normalizes it, and then provides access to that data via the API.

Cloud Connectors

Many device vendors provide access to their data via APIs, which we can take advantage of - select one of the available Connectors, follow the setup instructions and the data from that vendor will start to flow into the Mapped API.

You can combine both methods to get robust, full coverage of a location's device data, or in many cases just work with Connectors alone to get just the data most important to you. In the rest of this page, we'll walk you through retrieving your device data using the Mapped API; if you're more interested in points and time series data, you can skip ahead to the docs about Points.

Note that the ID format, including the number of characters, may vary from those displayed in the samples here. Once a thing has an ID assigned, that ID will never change, however we do not recommend placing any kind of validation on format or character count.

Viewing things by place

Typically you're going to look for Things associated with a Place - whether it's looking for all thermostats on particular floor, pulling a list of all lighting in a building built by a particular manufacturer, or checking a particular data point (like whether an thermostat is set to cool or heat) in a space - most queries for Things will start with a Place.

Here's an example retrieving all the devices for a particular site using filters:

RequestLive Response
Copy
1
2
3
4
5
6
7
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things {
      name
    }
  }
}

Viewing Things by Type

If you wanted to search by a specific type, like lighting equipment at a site, you would double up on the filters:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things(filter: {type: {eq: "Lighting_Equipment"}}) {
      name
      type
    }
  }
}

There are numerous potential types available, covering a wide range of services. Majority of the types present in the Brick ontology's Equipment class are supported, though some may be renamed (and all underscores are removed). Don't see a type you're expecting, or see a device that seems mislabeled? Contact us and we'll look into it right away.

Viewing model or manufacturer

In some cases, each thing can also come with information about its model and manufacturer. While the fields themselves are always present, not all data sets will provide this level of information. If it isn't available, you'll just get a "null" response for the model set.

Manufacturer is a sub field of model, so with everything combined, you'll end up a bit deep in the fields to get there. In this example, we're pulling the model and manufacturer data for all VAVs at a particular site; we included an example response where the data is not available, so you can see how that looks as well.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  sites {
    things(filter: {type: {eq: "VAV"}}) {
      name
      type
      model {
        name
        description
        manufacturer {
          name
          description
        }
      }
    }
  }
}