QuantAQ Cloud

QuantAQ Cloud API

The QuantAQ Cloud API allows you to manage your air quality sensors and data in a simple, programmatic way using conventional HTTP requests. Each endpoint is intuitive and allows you to obtain data and execute various actions easily. If you notice something that can be made more clear or more intuitive, please let us know!

This documentation will begin with a general overview of the API and how it works, followed by details on each endpoint that is available in *v1* of the API. Throughout this documentation, there will be code examples using httpie - an easy-to-use command line client for making HTTP requests. The names of specific resources will be represented by variables which are wrapped in "<>".

Getting Started

Obtaining an API key

Authentication is handled using HTTP Basic Auth which consists of sending an API key that is unique to your account with each request. This key should be kept secret and not shared with anyone. This API key is tied to your user account and will only allow you to take actions within your assigned scope of permissions.

You can generate an API key for your account by visiting the Developer section within the QuantAQ Cloud and clicking Generate New Key in the upper right-hand corner of your screen. It is recommended that you set this key as an environment variable on your computer with the name QUANTAQ_APIKEY.

To include your API key in your request, add an HTTP Authorization header, consisting of a usernameand password. When using httpie, you can use the -aflag to indicate authorization. The API key serves as the username and the password should be left blank.

Sending your first API call

To make an API call, you need four pieces of information:

  1. api_key: a random string of alphanumeric characters that gives you access to the API

  2. endpoint: the URI listed in the API reference section below

  3. method: one of GET, POST, PUT, or DELETE

  4. arguments: JSON-encoded values sent to the method (these are not always required)

More often than not, you will be sending either GET or POST requests to api.quant-aq.com. All API endpoints begin with the same URL which, for the QuantAQ Cloud, is api.quant-aq.com/. The full URL will be of the form:

https://api.quant-aq.com/{version}/{endpoint}

The version of the API may change (this will be documented) which signals changes in the underlying structure of the API. For now, there is only one version available: v1. Throughout these docs, we will just assume the version is v1.

A good first API call would be to get your account information. As mentioned above, we will be using httpie for examples. To get your account information, the API call would look like:

$ http -a <your-api-key-here>: GET \
        https://api.quant-aq.com/v1/account

You should see a response that looks something like the following:

{
    "confirmed": true,
    "email": "users_email@quant-aq.com",
    "first_name": "First Name",
    "id": 1,
    "is_administrator": false,
    "last_name": "Last Name",
    "last_seen": "2020-09-28T13:12:33.745041",
    "member_since": "2020-06-05T22:05:24.612347",
    "role": 5,
    "username": "username"
}

Understanding API calls and responses

Any tool that is fluent in HTTP requests and supports HTTP basic authentication protocols can be used to communicate with the QuantAQ Cloud API. Requests must be made using HTTPS. The interface response depends on the action required.

HTTP statuses and errors

Each request that is made to the API will have an attached status code that tells you whether the request was successful or not. If there is an issue with the request, an error will be returned as indicated both by the HTTP status code and the response body. In general, if the status code is in the 200's, the request was successful. If the status code is in the 400's, there was an error with the request; this could range from improper authentication to an illegal operation (e.g., you were trying to request data for which you do not have the necessary permissions). If a 500 error is returned, there was a server-side error which means we were unable to process the request for some reason.

An example error response:

HTTP/1.1 403 Forbidden
{
    "id": "forbidden",
    "message": "You do not have permissions for this action."
}

API Reference

Account

This is an object representing your account information. You can retrieve it to see basic information about your account, as summarized in the attributes section below.

Get your account information

GET /v1/account

Retrieves the current account information for the user who is making the request.

Path Parameters

None.

Query Parameters

None.

Response

Body

Name
Type
Description

username

string

The accounts username

confirmed

boolean

True if the account user has confirmed their email address

email

string

The email address of record for the user

first_name

string

The first name of the account user

last_name

string

The last name of the account user

id

int

The unique identifier for the account user

last_seen

datetime

The last time the account user was seen

member_since

datetime

The timestamp corresponding to when the user joined the site

{
    "confirmed": true,
    "email": "your-email@email.com",
    "first_name": "First Name",
    "id": 1,
    "last_name": "Last Name",
    "last_seen": "2020-09-28T13:12:33.745041",
    "member_since": "2020-06-05T22:05:24.612347",
    "role": 5,
    "username": "username"
}

Devices

This is an object representing a QuantAQ device. You can retrieve device information, either on an individual sensor basis or as a list to see basic information about the device(s), as summarized in the attributes section below. You can also update the information for a single device or delete a device.

Get a single Device

GET /v1/devices/{serial_number}

Retrieves the information for a single device by its serial number.

Path Parameters

Name
Type
Description

serial_number

string

The serial number of the device

Query Parameters

None.

Response

Body

Name
Type
Description

city

string

The city in which the device is installed

country

string

2-digit ISO country code corresponding to the country where the device is installed

created

datetime

The timestamp corresponding to when the device was brought online

description

string

The user-defined device description

geo.lat

float

The latitude corresponding to the geolocation of the device

geo.lon

float

The longitude corresponding to the geolocation of the device

id

int

The unique identifier for the device

model

string

The device model: one of [ modulair, modulair_pm, arisense_v200 ]

last_seen

datetime

The last time the device was seen

n_datapoints

int

The total number of data points the device has collected over its lifetime

*no longer valid

owner_id

int

The id of the device owner

private

boolean

True if the device is marked as private by the device owner

sn

string

The serial number of the device

status

string

The current operation status of the device. One of: [ CALIBRATION, ACTIVE, RETIRED, PRE_REGISTERED ]

timezone

string

The timezone corresponding to the location where the device is installed

url

string

The url corresponding to the device

{
  "city": "Boston",
  "country": null,
  "created": "2019-12-08T23:23:28.107099",
  "description": null,
  "geo": {
      "lat": null,
      "lon": null
  },
  "id": 6,
  "last_seen": "2019-12-08T23:23:28.107106",
  "model": "arisense_v200",
  "n_datapoints": 0,
  "outdoors": true,
  "owner_id": 1,
  "private": true,
  "sn": "a123456",
  "status": "INACTIVE",
  "timezone": null,
  "url": "https://api.quant-aq.com/device-api/v1/devices/a123456"
}

Get a list of Devices

GET /v1/devices

Retrieves a paginated list of devices including all devices the user has access to across Organizations and Networks. If no Devices are available, an empty list will be returned.

Path Parameters

None.

Query Parameters

Name
Type
Description

org_id

int, optional

The ID of the Organization to subquery

network_id

int, optional

The ID of the Network to subquery

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the table in the previous section for detailed body information.

Meta

{
  "data": [
      {
          "city": "New City",
          "country": "US",
          "created": "2019-03-03T17:50:16.829776",
          "description": "",
          "geo": {
              "lat": 42.5,
              "lon": -71.1
          },
          "id": 1,
          "last_seen": "2019-12-06T22:57:05.917175",
          "model": "arisense_v200",
          "n_datapoints": 4048,
          "outdoors": true,
          "owner_id": 1,
          "private": true,
          "sn": "SN000-001",
          "status": "CALIBRATION",
          "timezone": "US/Eastern",
          "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001"
      },
      ...
  ],
  "meta": {
      "first_url": "https://api.quant-aq.com/device-api/v1/devices/?page=1&per_page=50",
      "last_url": "https://api.quant-aq.com/device-api/v1/devices/?page=1&per_page=50",
      "next_url": null,
      "page": 1,
      "pages": 1,
      "per_page": 50,
      "prev_url": null,
      "total": 3
	}
}

Update a Device

PUT /v1/devices/{serial_number}

Retrieves the information for a single device by its serial number.

Path Parameters

Name
Type
Description

serial_number

string

The serial number of the device

Query Parameters

Name
Type
Description

city

string

The city in which the device is installed

country

string

2-digit ISO country code corresponding to the country where the device is installed

description

string

The user-defined device description

lat

float

The latitude corresponding to the geolocation of the device

lon

float

The longitude corresponding to the geolocation of the device

is_private

boolean

True if the device is marked as private by the device owner

device_state

string

The current operation status of the device. One of: [ CALIBRATION, ACTIVE, RETIRED, PRE_REGISTERED ]

timezone

string

The timezone corresponding to the location where the device is installed

Response

Body

Please see the table in the previous section for detailed body information.

{
  "city": "Boston",
  "country": null,
  "created": "2019-12-08T23:23:28.107099",
  "description": null,
  "geo": {
      "lat": null,
      "lon": null
  },
  "id": 6,
  "last_seen": "2019-12-08T23:23:28.107106",
  "model": "arisense_v200",
  "n_datapoints": 0,
  "outdoors": true,
  "owner_id": 1,
  "private": true,
  "sn": "a123456",
  "status": "INACTIVE",
  "timezone": null,
  "url": "https://api.quant-aq.com/device-api/v1/devices/a123456"
}

Organizations

This is an object representing an Organization. You can retrieve it to see basic information about a given Organization including the members and devices, as summarized in the attributes section below.

Get a single Organization

GET /v1/orgs/{org_id}

Retrieve the information for a single Organization by its Organization ID. The user must be a confirmed member of the Organization, or the endpoint will return a 403.

Path Parameters

Name
Type
Description

org_id

int

The ID of the Organization

Query Parameters

None.

Response

Body

Name
Type
Description

name

string

The name of the Organization

id

string

The unique identifier for the Organization

description

string

A short description of the Organization

created_on

datetime

An ISO-formatted timestamp representing the creation date of the Organization

sandbox

boolean

true if a Sandbox Organization, otherwise false

members

list

A list containing the confirmed members of the Organization that are visible to the requesting user. Organization administrators can see all Organization members. Each entry is a sub-object representing an Organization user including their role and username.

devices

list

A list containing the serial number of all Devices associated with the Organization that are visible to the requesting user. An administrator can see all Organization-managed devices, while a non-administrator can see the Devices for the Networks they are a member of.

networks

list

A list containing the IDs of all Networks associated with the Organization that are visible to the requesting user.

{
  "name": "Org 1"
  "id": 1,
    "description": "Where Org 1 things live.",
    "created_on": "2023-11-07T00:00:00.000000+00:00",
    "sandbox": false,
  "members": [
      {
	"role": "admin",
	"user": "user-1"
      },
      {
         "role": "member",
  	 "user": "user-2"
      }
  ],
    "devices": [],
    "networks": []
}

Get a list of all Organizations

GET /v1/orgs/

Retrieves a list of all organizations the user account has access to. This endpoint returns a paginated list of Organization objects. The call will return an empty list if no Organizations met the provided parameters, or if the requester is not a confirmed member of any Organizations (though they should be the member of their own sandbox).

Path Parameters

None.

Query Parameters

Name
Type
Description

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the single Organization section above for details on the response body.

Meta

{
  "data": [
      {
	"name": "Org 1"
	"id": 1,
	"description": "Where Org 1 things live.",
	"created_on": "2023-11-07T00:00:00.000000+00:00",
	"sandbox": false,
	"members": [
		{
		  "role": "admin",
		  "user": "user-1"
		},
		{
		  "role": "member",
		  "user": "user-2"
		}
	],
	"devices": [],
	"networks": []
	}
  ],
  "meta": {
      "first_url": "https://api.quant-aq.com/device-api/v1/orgs/?page=1&per_page=50",
      "last_url": "https://api.quant-aq.com/device-api/v1/orgs/?page=1&per_page=50",
      "next_url": null,
      "page": 1,
      "pages": 1,
      "per_page": 50,
      "prev_url": null,
      "total": 1
  }
}

Networks

This is an object representing a Network. You can retrieve it to see basic information about a given Network including the members and Devices.

Get a Network

GET /v1/orgs/{org_id}/{network_id}

Retrieve the information for a single Network by its Organization ID and Network ID. The user must be a confirmed member of the Network, or the endpoint will return a 403.

Path Parameters

Name
Type
Description

org_id

int

The ID of the Organization

network_id

int

The ID of the Network

Query Parameters

None.

Response

Body

Name
Type
Description

name

string

The name of the Network

id

string

The unique identifier for the Network

description

string

A short description of the Network

created_on

datetime

An ISO-formatted timestamp representing the creation date of the Network

members

list

A list containing the confirmed members of the Network that are visible to the requesting user.

devices

list

A list containing the serial number of all Devices associated with the Network.

{
    "name": "Network 1",
		"id": 1,
		"description": "Where Network 1 things live.",
    "organization": 1,
		"created_on": "2023-11-07T00:00:00.000000+00:00",
		"members": [
        {
          "role": "Operator",
          "user": "user1"
        },
				{
          "role": "Researcher",
          "user": "user2"
        },
    ],
		"devices": []
}

Get a list of Networks

GET /v1/orgs/{org_id}/networks/

Retrieves a list of all visible Networks belonging to a given Organization. This endpoint is scoped behind the Organization endpoint, so you must provide an Organization ID. An Organization’s Network is visible to a user if they are an Organization administrator or a member of the Network. The Organization must be visible to the requester, or the endpoint will return a 403.

Path Parameters

Name
Type
Description

org_id

int

The ID of the Organization

Query Parameters

Name
Type
Description

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the single Network section above for details on the response body.

Meta

{
  "data": [
      {
			    "name": "Network 1",
					"id": 1,
					"description": "Where Network 1 things live.",
			    "organization": 1,
					"created_on": "2023-11-07T00:00:00.000000+00:00",
					"members": [
			        {
			          "role": "Operator",
			          "user": "user1"
			        },
							{
			          "role": "Researcher",
			          "user": "user2"
			        },
			    ],
					"devices": []
			}
  ],
  "meta": {
      "first_url": "https://api.quant-aq.com/device-api/v1/orgs/1/networks/?page=1&per_page=50",
      "last_url": "https://api.quant-aq.com/device-api/v1/orgs/1/networks/?page=1&per_page=50",
      "next_url": null,
      "page": 1,
      "pages": 1,
      "per_page": 50,
      "prev_url": null,
      "total": 1
  }
}

Data

This is an object representing your data for a given Device. You can retrieve it as a list for either raw or final data

Get final data

GET /v1/devices/{serial_number}/data/

Retrieves a paginated list of data for a specific device using its serial number.

Path Parameters

Name
Type
Description

serial_number

string

The serial number of the device you would like to query

Query Parameters

Name
Type
Description

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the product manual for the type of Device you are querying for details on the response body. These are located in the "Hardware" section of these docs.

Meta

{
    "data": [
						{
	            "co": 51.106268512085,
	            "co2": 421.793483200912,
	            "geo": {
	                "lat": 40.9844188816344,
	                "lon": 105.561207967016
	            },
	            "no": 10.2810514330163,
	            "no2": 56.8233499407749,
	            "noise": 6.29058420281369,
	            "o3": 37.946070157595,
	            "pm1": 8.91967278706223,
	            "pm10": 14.2017895600789,
	            "pm25": 9.07509558015509,
	            "pressure": 101454.562990336,
	            "rh_manifold": 73.2982119788483,
	            "sn": "SN000-001",
	            "solar": 8.49282458496783,
	            "temp_box": 35.226457866451,
	            "temp_manifold": 7.28921112549997,
	            "timestamp": "2020-06-08T15:31:16.895459",
	            "timestamp_local": "2020-06-08T09:31:16.895459",
	            "tvoc": null,
	            "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/19",
	            "wind_dir": 323.38596795112,
	            "wind_speed": 99.8816892936835
	        }
    ],
    "meta": {
        "first_url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/?page=1&per_page=50&limit=100",
        "last_url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/?page=2&per_page=50&limit=100",
        "next_url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/?page=2&per_page=50&limit=100",
        "page": 1,
        "pages": 2,
        "per_page": 50,
        "prev_url": null,
        "total": 100
    }
}

Get raw data

GET /v1/devices/{serial_number}/data/raw/

Retrieves a paginated list of raw data for a specific device using its serial number.

Path Parameters

Name
Type
Description

serial_number

string

The serial number of the device you would like to query

Query Parameters

Name
Type
Description

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the product manual for the type of Device you are querying for details on the response body. These are located in the "Hardware" section of these docs.

Meta

{
  "data": [
			{
          "bin0": 286.647741870419,
          "bin1": 551.701930611041,
          "bin10": 46.7706898657725,
          "bin11": 29.584787450594,
          "bin12": 50.7844931631582,
          "bin13": 21.5517228689086,
          "bin14": 44.4108140986913,
          "bin2": 221.637921828236,
          "bin3": 275.16465539171,
          "bin4": 312.552750081673,
          "bin5": 224.606340244391,
          "bin6": 230.723866268078,
          "bin7": 40.6604798027605,
          "bin8": 86.764139275662,
          "bin9": 76.3482566483437,
          "co2_raw": 959.118224004688,
          "co_ae": 911.5526546364,
          "co_diff": null,
          "co_we": 467.476827385698,
          "dew_point": 2.1147447373898,
          "flag": 64,
          "geo": {
              "lat": 40.9844188816344,
              "lon": 105.561207967016
          },
          "no2_ae": 579.782539043588,
          "no2_diff": null,
          "no2_we": 614.951076396963,
          "no_ae": 789.090772676965,
          "no_diff": null,
          "no_we": 439.438007376347,
          "noise": 6.29058420281369,
          "o3_ae": 455.557344482557,
          "o3_diff": null,
          "o3_we": 669.05302084695,
          "opc_flow": 0.569001807871506,
          "opc_sample_time": null,
          "pressure": 101454.562990336,
          "rh_manifold": 73.2982119788483,
          "sn": "SN000-001",
          "solar": 8.49282458496783,
          "temp_box": 35.226457866451,
          "temp_manifold": 7.28921112549997,
          "timestamp": "2020-06-08T15:31:16.895459",
          "timestamp_local": "2020-06-08T09:31:16.895459",
          "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/raw/19",
          "voc_raw": 139.457791015991,
          "wind_dir": 323.38596795112,
          "wind_speed": 99.8816892936835
      }
  ],
  "meta": {
      "first_url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/raw/?page=1&per_page=50&limit=100",
      "last_url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/raw/?page=2&per_page=50&limit=100",
      "next_url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/raw/?page=2&per_page=50&limit=100",
      "page": 1,
      "pages": 2,
      "per_page": 50,
      "prev_url": null,
      "total": 100
  }
}

Data by Date

This section and the endpoint were added on March 31st, 2022.

This is an object representing your data for a given Device, as queried by date. You can retrieve it as a list for either raw or final data.

Get final data by date

GET /v1/devices/{serial_number}/data-by-date/{date}/

Retrieves a paginated list of final data for a specific device using its serial number for a specific date.

Path Parameters

Name
Type
Description

serial_number

string

The serial number of the device you would like to query

date

string

The date for which you would like to return data. The format must be YYYY-MM-DD and all dates are in GMT. Thus, if you request data for 2022-01-01, it will return all data for the device on Jan. 1st GMT.

Query Parameters

Name
Type
Description

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the product manual for the type of Device you are querying for details on the response body. These are located in the "Hardware" section of these docs.

Meta

{
    "data": [
						{
	            "co": 51.1,
	            "co2": 421.7,
	            "geo": {
	                "lat": 40.984,
	                "lon": 105.561
	            },
	            "no": 10.2810514330163,
	            "no2": 56.8233499407749,
	            "o3": 37.946070157595,
	            "pm1": 8.91967278706223,
	            "pm10": 14.2017895600789,
	            "pm25": 9.07509558015509,
	            "rh_manifold": 73.2982119788483,
	            "sn": "SN000-001",
	            "temp_box": 35.226457866451,
	            "temp_manifold": 7.28921112549997,
	            "timestamp": "2020-06-08T15:31:16.895459",
	            "timestamp_local": "2020-06-08T09:31:16.895459",
	            "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/19",
	            "wind_dir": 323.38596795112,
	            "wind_speed": 99.8816892936835
	        }
    ],
    "meta": {
        "date": "2022-01-01", 
        "total": 100
    }
}

Get raw data by date

GET /v1/devices/{serial_number}/data-by-date/raw/{date}/

Retrieves a paginated list of raw data for a specific device using its serial number for a specific date.

Path Parameters

Name
Type
Description

serial_number

string

The serial number of the device you would like to query

date

string

The date for which you would like to return data. The format must be YYYY-MM-DD and all dates are in GMT. Thus, if you request data for 2022-01-01, it will return all data for the device on Jan. 1st GMT.

Query Parameters

Name
Type
Description

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the product manual for the type of Device you are querying for details on the response body. These are located in the "Hardware" section of these docs.

Meta

{
  "data": [
			{
          "bin0": 286.647741870419,
          "bin1": 551.701930611041,
          "bin10": 46.7706898657725,
          "bin11": 29.584787450594,
          "bin12": 50.7844931631582,
          "bin13": 21.5517228689086,
          "bin14": 44.4108140986913,
          "bin2": 221.637921828236,
          "bin3": 275.16465539171,
          "bin4": 312.552750081673,
          "bin5": 224.606340244391,
          "bin6": 230.723866268078,
          "bin7": 40.6604798027605,
          "bin8": 86.764139275662,
          "bin9": 76.3482566483437,
          "co2_raw": 959.118224004688,
          "co_ae": 911.5526546364,
          "co_diff": null,
          "co_we": 467.476827385698,
          "dew_point": 2.1147447373898,
          "flag": 64,
          "geo": {
              "lat": 40.9844188816344,
              "lon": 105.561207967016
          },
          "no2_ae": 579.782539043588,
          "no2_diff": null,
          "no2_we": 614.951076396963,
          "no_ae": 789.090772676965,
          "no_diff": null,
          "no_we": 439.438007376347,
          "noise": 6.29058420281369,
          "o3_ae": 455.557344482557,
          "o3_diff": null,
          "o3_we": 669.05302084695,
          "opc_flow": 0.569001807871506,
          "opc_sample_time": null,
          "pressure": 101454.562990336,
          "rh_manifold": 73.2982119788483,
          "sn": "SN000-001",
          "solar": 8.49282458496783,
          "temp_box": 35.226457866451,
          "temp_manifold": 7.28921112549997,
          "timestamp": "2020-06-08T15:31:16.895459",
          "timestamp_local": "2020-06-08T09:31:16.895459",
          "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/raw/19",
          "voc_raw": 139.457791015991,
          "wind_dir": 323.38596795112,
          "wind_speed": 99.8816892936835
      }
  ],
  "meta": {
      "date": "2022-01-01",
      "total": 100
  }
}

Most Recent Data

Retrieve the most recent data record for either a single Device (by serial number), a Network (id), or an Organization (id). A list will be returned for any of them.

Get the most recent data

GET /v1/data/most-recent/

Retrieves the data for a specific Device using its serial number or a list of Devices using an Organization ID or Network ID. If multiple parameters are used, the devices from which data is fetched must meet all conditions.

Path Parameters

None.

Query Parameters

At least one of sn, org_id, or network_id must be provided otherwise a 400 error will be returned.

Name
Type
Description

sn

string

The serial number of the device in question.

org_id

int

The ID of the Organization.

network_id

int

The ID of the Network.

per_page

int

The number of items to return per page (default=50)

page

int

The page number to return (default=1)

sort

string, optional

Please see the advanced queries section at the bottom of this page for more information

filter

string, optional

Please see the advanced queries section at the bottom of this page for more information

limit

int, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the product manual for the type of Device you are querying for details on the response body. These are located in the "Hardware" section of these docs.

Meta

{
    "data": [
						{
	            "co": 51.106268512085,
	            "co2": 421.793483200912,
	            "geo": {
	                "lat": 40.9844188816344,
	                "lon": 105.561207967016
	            },
	            "no": 10.2810514330163,
	            "no2": 56.8233499407749,
	            "noise": 6.29058420281369,
	            "o3": 37.946070157595,
	            "pm1": 8.91967278706223,
	            "pm10": 14.2017895600789,
	            "pm25": 9.07509558015509,
	            "pressure": 101454.562990336,
	            "rh_manifold": 73.2982119788483,
	            "sn": "SN000-001",
	            "solar": 8.49282458496783,
	            "temp_box": 35.226457866451,
	            "temp_manifold": 7.28921112549997,
	            "timestamp": "2020-06-08T15:31:16.895459",
	            "timestamp_local": "2020-06-08T09:31:16.895459",
	            "tvoc": null,
	            "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/19",
	            "wind_dir": 323.38596795112,
	            "wind_speed": 99.8816892936835
	        },
					...
    ]
}

Resampled Data

As of September 24th, 2024, the resampled data downloads only provide data for completed resampling periods. Future periods and the current in-progress period will be omitted. For more information about how QuantAQ resamples data, see this article.

The attributes for the resampled data object depend on the model of the Device and will always return the final data. Generally, a list is returned containing all available data for that Device, per period.

The data returned from this endpoint differs from others in several ways. Some further remarks on the structure and contents:

  • Data entries may be null, if there are no measurements for that period, or if the number of measurements does not meet the completeness criterion. For more information refer to this help article.

  • Periods are included even if no measurements meet the completeness criterion.

  • The number of data records (of any sort) is provided in n_datapoints. Note that this does not indicate that every data record has a valid measurement for every listed pollutant, since components may operate independently of each other.

  • Periods are computed using the device’s local timezone. Across Daylight Savings Time borders, there may be more or less time represented by a given period. Further discussion here.

  • Times are provided in both local and UTC time, with offsets included.

  • Averaging is done naively across all data within the period and is not intended to match the National Ambient Air Quality Standard (NAAQS) or other specific averaging logic and is provided for convenience only

Get resampled data

This endpoint will be deprecated in January 2025 and replaced by a new resampled data endpoint.

Retrieves the data for a specific device using its serial number.

GET /v1/data/resampled/

Path Parameters

None.

Query Parameters

sn, start_date, and end_date must be provided otherwise a 400 error will be returned.

Name
Type
Description

sn

string, required

The serial number of the device in question.

start_date

string, required

The ID of the Organization.

end_date

string, required

The ID of the Network.

period

string, optional

Please see the advanced queries section at the bottom of this page for more information

Response

Body

Please see the product manual for the type of Device you are querying for details on the response body. These are located in the "Hardware" section of these docs.

[FIX META RESPONSE BLOCK]

{
    "data": [
						{
	            "co": 51.106268512085,
	            "co2": 421.793483200912,
	            "geo": {
	                "lat": 40.9844188816344,
	                "lon": 105.561207967016
	            },
	            "no": 10.2810514330163,
	            "no2": 56.8233499407749,
	            "noise": 6.29058420281369,
	            "o3": 37.946070157595,
	            "pm1": 8.91967278706223,
	            "pm10": 14.2017895600789,
	            "pm25": 9.07509558015509,
	            "pressure": 101454.562990336,
	            "rh_manifold": 73.2982119788483,
	            "sn": "SN000-001",
	            "solar": 8.49282458496783,
	            "temp_box": 35.226457866451,
	            "temp_manifold": 7.28921112549997,
	            "timestamp": "2020-06-08T15:31:16.895459",
	            "timestamp_local": "2020-06-08T09:31:16.895459",
	            "tvoc": null,
	            "url": "https://api.quant-aq.com/device-api/v1/devices/SN000-001/data/19",
	            "wind_dir": 323.38596795112,
	            "wind_speed": 99.8816892936835
	        },
					...
    ]
}

Meta Data

Logs

Advanced Queries

Most QuantAQ Cloud API endpoints support advanced queries that allow you to filter, limit, and sort your results. All endpoints that return paginated data - such as retrieving data points - support these requests.

Filtering requests

To filter a query, use the filter keyword argument with the format filter=<parameter>,<filter spec>,<value>. Multiple filters can be combined using a ; to build complex queries. For example, if we want to return the data points where PM2.5 is between 25 and 50 µg/m3, we would write filter=pm25,ge,25;pm25,le,50;.

A full request might then look like:

$ http -a <your-api-key-here>: GET \
        "https://api.quant-aq.com/device-api/v1/devices/<sn>/data/?filter=pm25,ge,25;pm25,le,50;"

The following filter specs are supported and available to use:

  • eq: = (equals)

  • ne: ≠ (not equals)

  • lt: < (less than)

  • gt: > (greater than)

  • ge: ≥ (greater than or equal to)

  • le: ≤ (less than or equal to)

  • in: in

  • like: like

Limiting requests

To limit the number of data points returned for any given request, use the limit keyword argument with the number of data you would like returned. For example, to return just the first 5 items, use limit=5. If you are calling an endpoint that returns paginated data and would like to return a specific number of data per page, you can alternatively (or additionally) use the per_page keyword argument.

Sorting requests

To return data in a specific order, you can use the sort keyword argument with format sort=<parameter>,<order> where order is one of asc or desc. For example, if you want to return the data descended by timestamp:

$ http -a <api-key>: GET \
    https://api.quant-aq.com/device-api/v1/devices/<serial number>/data/?sort=timestamp,desc

Other Resources

SDKs

py-quantaq

py-quantaq is the official python API wrapper for the QuantAQ Cloud API and is maintained and supported by QuantAQ. Full documentation can be found here. For questions specfiic to py-quantaq, please use the GitHub repository issues page.

r-quantaq

r-quantaq is the official R API wrapper for the QuantAQ Cloud API and is maintained and supported by QuantAQ. Full documentation can be found here. For questions specfiic to R-quantaq, please use the GitHub repository issues page.

Changelog

Date
Release Notes

September 24th, 2024

  • The Resampled Data endpoint now omits future periods on the current day instead of including them as null.

February 27th, 2024

  • A Resampled Data endpoint was added (/v1/data/resampled/)

December 28th, 2023

  • All teams-related endpoints and parameters were removed, following deprecation in Summer 2023

  • After significant user feedback, “Public” devices are no longer accessible via the API to unauthorized users without Org or Network access. (Public devices remain visible through the QuantAQ Cloud web app)

November 7th, 2023

  • Several new endpoints were added, to accommodate organization and network requests:

    • /v1/orgs/

    • /v1/orgs/<org_id>/

    • /v1/orgs/<org_id>/networks/

    • /v1/orgs/<org_id>/networks/<network_id>

  • Two endpoints were changed to permit filtering by organization and network:

    • /v1/data/most-recent/ now accepts optional org_id and network_id filtering parameters

    • /v1/data/devices/ now accepts optional org_id and network_id filtering parameters

March 31st, 2022

  • Two new endpoints were added (/devices/<sn>/data-by-date/<date>/, /devices/<sn>/data-by-date/raw/<date>/) to allow users to more efficiently query large amounts of data

January 26th, 2022

  • A new endpoint was added (/data/most-recent/) to allow users to query the most recent data for a single device or team of devices.

January 11th, 2021

  • the devices/ endpoint was updated to allow for a new parameter (team) which permits users to query available devices by team name. Simply add ?team=team-1 and you will only be returned the available devices for the requested team. If the team name does not exist or have any devices, an empty list will be returned. If you would like to return all available devices across all of your teams, simply omit the team parameter as before.

PreviousSmart Solar Power SystemNextCommand Line Interface

Last updated