# 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](https://httpie.org/) - 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 `username`and `password.` When using **httpie**, you can use the `-a`flag 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: ```sh 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: ```sh $ http -a : GET \ https://api.quant-aq.com/v1/account ``` You should see a response that looks something like the following: ```json { "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 by both 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: ```sh HTTP/1.1 403 Forbidden { "id": "forbidden", "message": "You do not have permissions for this action." } ``` #### Rate Limiting Rate limiting is set for the API at 150 requests/minute for all data endpoints. If you have exceeded this limit, you will receive a 429 status code and will need to wait until the next minute to make more requests. *** ## 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*
NameTypeDescription
usernamestringThe accounts username
confirmedbooleanTrue if the account user has confirmed their email address
emailstringThe email address of record for the user
first_namestringThe first name of the account user
last_namestringThe last name of the account user
idintThe unique identifier for the account user
last_seendatetimeThe last time the account user was seen
member_sincedatetimeThe timestamp corresponding to when the user joined the site
{% tabs %} {% tab title="200" %} ```json { "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" } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} *** ### 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**
NameTypeDescription
serial_numberstringThe serial number of the device
**Query Parameters** None. **Response** *Body*
NameTypeDescription
citystringThe city in which the device is installed
countrystring2-digit ISO country code corresponding to the country where the device is installed
createddatetimeThe timestamp corresponding to when the device was brought online
descriptionstringThe user-defined device description
geo.latfloatThe latitude corresponding to the geolocation of the device
geo.lonfloatThe longitude corresponding to the geolocation of the device
idintThe unique identifier for the device
modelstringThe device model: one of [ modulair, modulair_pm, arisense_v200 ]
last_seendatetimeThe last time the device was seen
n_datapointsint

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

*no longer valid

owner_idintThe id of the device owner
privatebooleanTrue if the device is marked as private by the device owner
snstringThe serial number of the device
statusstringThe current operation status of the device. One of: [ CALIBRATION, ACTIVE, RETIRED, PRE_REGISTERED ]
timezonestringThe timezone corresponding to the location where the device is installed
urlstringThe url corresponding to the device
{% tabs %} {% tab title="200" %} ```json { "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" } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} #### 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**
NameTypeDescription
org_idint, optionalThe ID of the Organization to subquery
network_idint, optionalThe ID of the Network to subquery
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease see the advanced queries section at the bottom of this page for more information
**Response** *Body* Please see the table in the [previous section](#get-a-single-device) for detailed body information. *Meta*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} #### Update a Device `PUT` `/v1/devices/{serial_number}` Retrieves the information for a single device by its serial number. **Path Parameters**
NameTypeDescription
serial_numberstringThe serial number of the device
**Query Parameters**
NameTypeDescription
citystringThe city in which the device is installed
countrystring2-digit ISO country code corresponding to the country where the device is installed
descriptionstringThe user-defined device description
latfloatThe latitude corresponding to the geolocation of the device
lonfloatThe longitude corresponding to the geolocation of the device
is_privatebooleanTrue if the device is marked as private by the device owner
device_statestringThe current operation status of the device. One of: [ CALIBRATION, ACTIVE, RETIRED, PRE_REGISTERED ]
timezonestringThe timezone corresponding to the location where the device is installed
**Response** *Body* Please see the table in the [previous section](#get-a-single-device) for detailed body information. {% tabs %} {% tab title="200" %} ```json { "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" } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} *** ### 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**
NameTypeDescription
org_idintThe ID of the Organization
**Query Parameters** None. **Response** *Body*
NameTypeDescription
namestringThe name of the Organization
idstringThe unique identifier for the Organization
descriptionstringA short description of the Organization
created_ondatetimeAn ISO-formatted timestamp representing the creation date of the Organization
sandboxbooleantrue if a Sandbox Organization, otherwise false
memberslistA 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.
deviceslistA 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.
networkslistA list containing the IDs of all Networks associated with the Organization that are visible to the requesting user.
{% tabs %} {% tab title="200" %} ```json { "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": [] } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} #### 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**
NameTypeDescription
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease see the advanced queries section at the bottom of this page for more information
**Response** *Body* Please see the [single Organization](#get-a-single-organization) section above for details on the response body. *Meta*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} ### 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**
NameTypeDescription
org_idintThe ID of the Organization
network_idintThe ID of the Network
**Query Parameters** None. **Response** *Body*
NameTypeDescription
namestringThe name of the Network
idstringThe unique identifier for the Network
descriptionstringA short description of the Network
created_ondatetimeAn ISO-formatted timestamp representing the creation date of the Network
memberslistA list containing the confirmed members of the Network that are visible to the requesting user.
deviceslistA list containing the serial number of all Devices associated with the Network.
{% tabs %} {% tab title="200" %} ```json { "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": [] } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} #### 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**
NameTypeDescription
org_idintThe ID of the Organization
**Query Parameters**
NameTypeDescription
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease see the advanced queries section at the bottom of this page for more information
**Response** *Body* Please see the [single Network](#get-a-network) section above for details on the response body. *Meta*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} ### 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**
NameTypeDescription
serial_numberstringThe serial number of the device you would like to query
**Query Parameters**
NameTypeDescription
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease 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*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} #### 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**
NameTypeDescription
serial_numberstringThe serial number of the device you would like to query
**Query Parameters**
NameTypeDescription
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease 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*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} ### Data by Date {% hint style="info" %} This section and the endpoint were added on March 31st, 2022. {% endhint %} 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**
NameTypeDescription
serial_numberstringThe serial number of the device you would like to query
datestringThe 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**
NameTypeDescription
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease 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*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} #### 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**
NameTypeDescription
serial_numberstringThe serial number of the device you would like to query
datestringThe 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**
NameTypeDescription
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease 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*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 } } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} ### 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** {% hint style="warning" %} At least one of `sn`, `org_id`, or `network_id` must be provided otherwise a 400 error will be returned. {% endhint %}
NameTypeDescription
snstringThe serial number of the device in question.
org_idintThe ID of the Organization.
network_idintThe ID of the Network.
per_pageintThe number of items to return per page (default=50)
pageintThe page number to return (default=1)
sortstring, optionalPlease see the advanced queries section at the bottom of this page for more information
filterstring, optionalPlease see the advanced queries section at the bottom of this page for more information
limitint, optionalPlease 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*
NameTypeDescription
first_urlstringThe url of the first page in the collection
last_urlstringThe url of the last page in the collection
next_urlstringThe url of the next page in the collection
prev_urlstringThe url of the previous url in the collection
pageintThe current page number
pagesintThe total number of pages available
per_pageintThe number of records returned per page
totalintThe total number of records available in the query
{% tabs %} {% tab title="200" %} ```json { "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 }, ... ] } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} ### Resampled Data {% hint style="info" %} 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](https://support.quant-aq.com/en/articles/8838723-how-to-download-resampled-data). {% endhint %} 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](https://support.quant-aq.com/en/articles/8838723-how-to-download-resampled-data). * 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](https://support.quant-aq.com/en/articles/8838723-how-to-download-resampled-data). * 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 Retrieves the data for a specific device using its serial number. `GET` `/v1/data/resampled/` **Path Parameters** None. **Query Parameters** {% hint style="warning" %} `sn`, `start_date`, `end_date`, and `period` must be provided otherwise a 400 error will be returned. {% endhint %}
NameTypeDescription
snstring, requiredThe serial number of the device in question.
start_datestring, requiredThe ID of the Organization.
end_datestring, requiredThe ID of the Network.
periodstring, requiredThe length of period at which the data should be resampled. Options: 15m (15 minutes), 1h (1 hour), 8h (8 hours), 1d (1 day)
**Response** *Body* The data available will depend on the device in question, but will be shaped roughly like the following, with one object per time period. Consult the Hardware section of the documentation for a sense of what columns your device supports. {% tabs %} {% tab title="200" %} ```json { "data": [ { "co": 139.156, "n_datapoints": 60, "no": 3.705, "no2": 2.367, "o3": 42.106, "period_end": "2025-05-27T01:00:00-07:00", "period_end_utc": "2025-05-27T08:00:00+00:00", "period_start": "2025-05-27T00:00:00-07:00", "period_start_utc": "2025-05-27T07:00:00+00:00", "pm1": 1.514, "pm10": 14.993, "pm25": 2.962, "sample_rh": 62.408, "sample_temp": 13.57, "sn": "MOD-X-00001", "wd": 62.148, "ws": 0.896, "ws_scalar": 1.006, "wx_dew_point": 6.696, "wx_pressure": 1019.945, "wx_rh": 65.304, "wx_temp": 12.985 },, ... } ``` {% endtab %} {% tab title="400" %} ```json { "error": "bad request", "message": "period parameter should be one of 1h|15m|8h|1d" } ``` {% endtab %} {% endtabs %} ### 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=,,`. 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: ```sh $ http -a : GET \ "https://api.quant-aq.com/device-api/v1/devices//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=,` where `order` is one of `asc` or `desc`. For example, if you want to return the data descended by timestamp: ```sh $ http -a : GET \ https://api.quant-aq.com/device-api/v1/devices//data/?sort=timestamp,desc ``` ## Other Resources ### SDKs #### py-quantaq [`py-quantaq`](https://github.com/quant-aq/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](https://quant-aq.github.io/py-quantaq/). For questions specfiic to `py-quantaq`, please use the [GitHub repository issues page](https://github.com/quant-aq/py-quantaq/issues). #### r-quantaq [`r-quantaq`](https://github.com/quant-aq/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](https://github.com/quant-aq/r-quantaq). For questions specfiic to `R-quantaq`, please use the [GitHub repository issues page](https://github.com/quant-aq/r-quantaq/issues). ## Changelog
DateRelease 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.