AirMQ GraphQL API Documentation

This documentation contains description of all API queries, responses and respective data types.

All requests to the API are POST.

Please expect upcoming blog post with API usage examples and best practices.

AirMQ Telegram channel is a good place to ask questions and get answers.

Contact

AirMQ Team
info@airmq.by

License

Apache 2.0
https://www.apache.org/licenses/LICENSE-2.0.html

API Endpoints

Public API:
https://api.airmq.cc
GraphQL Playground interface:
https://api.airmq.cc/playground

Playground

For testing purposes, API data can be accessed interactively with web-based GraphQL Playground IDE using following URL: https://api.airmq.cc/playground

Authorization

This API uses token-based authorization. All requests must supply an HTTP Authorization header with provided token as payload. To request a token, please register at user panel or apply to our Telegram channel.

Queries

`cityAverage`

Query for current weighted values per city or id list

Returns a SensorData

Name	Description
`filter` - `LastFilter`

Example

Query

query cityAverage($filter: LastFilter) {
  cityAverage(filter: $filter) {
    time
    Temp
    Hum
    Press
    PMS1
    PMS25
    PMS10
    Count
  }
}

Variables

{"filter": {"city": 'Homiel', "interval_m": 30}}

Response

{
  "data": {
    "cityAverage": {
      "time": "2021-11-21T16:34:27.191Z",
      "Temp": "-10.05",
      "Hum": "36.31",
      "Press": "985.99",
      "PMS1": "3.49",
      "PMS25": "4.17",
      "PMS10": "6.22",
      "Count": "0.112"
    }
  }
}

`cityAverages`

Time series of average values per city or id list

Returns [SensorData]

Name	Description
`filter` - `MeanFilter`

Example

Query

query cityAverages($filter: MeanFilter) {
  cityAverages(filter: $filter) {
    time
    Temp
    Hum
    Press
    PMS1
    PMS25
    PMS10
    Count
  }
}

Variables

{
  "filter": {
    "city": 'Вiцебск',
    "t_from": '2021-09-07T01:08:03.420Z',
    "t_to": '2021-10-08T01:08:03.420Z',
    "interval_m": 30
  }
}

Response

{
  "data": {
    "cityAverages": [
      {
        "time": "2021-11-21T16:34:27.191Z",
        "Temp": "-10.05",
        "Hum": "36.31",
        "Press": "985.99",
        "PMS1": "3.49",
        "PMS25": "4.17",
        "PMS10": "6.22",
        "Count": "0.112"
      }
    ]
  }
}

`cityList`

List of all cities in the country with AirMQ sensors installed

Returns [City]

Name	Description
`countryCode` - `String`

Example

Query

query cityList($countryCode: String) {
  cityList(countryCode: $countryCode) {
    _id
    countryCode
    cityName {
      ...CityNameFragment
    }
    locationCount
  }
}

Variables

{"countryCode": "BY"}

Response

{
  "data": {
    "cityList": [
      {
        "_id": "BY06001",
        "countryCode": "BY",
        "cityName": CityName,
        "locationCount": 15
      }
    ]
  }
}

`location`

Query for single sensor location. Returns location info and sensor data.

Returns a Location

Name	Description
`filter` - `LocationFilter`

Example

Query

query location($filter: LocationFilter) {
  location(filter: $filter) {
    _id
    city
    name
    isOnline
    latitude
    longitude
    status {
      ...StatusFragment
    }
    currentValue {
      ...SensorDataFragment
    }
    timeSeries {
      ...SensorDataFragment
    }
  }
}

Variables

{"filter": {"_id": 'BY01001060'}}

Response

{
  "data": {
    "location": {
      "_id": "BY01001060",
      "city": "Brest",
      "name": "Тэхнапарк",
      "isOnline": true,
      "latitude": 53.88022411496701,
      "longitude": 29.86211252212241,
      "status": Status,
      "currentValue": SensorData,
      "timeSeries": [SensorData]
    }
  }
}

`locations`

Query for multiple sensor locations. Returns array of location info and sensor data

Returns [Location]

Name	Description
`filter` - `LocationsFilter`

Example

Query

query locations($filter: LocationsFilter) {
  locations(filter: $filter) {
    _id
    city
    name
    isOnline
    latitude
    longitude
    status {
      ...StatusFragment
    }
    currentValue {
      ...SensorDataFragment
    }
    timeSeries {
      ...SensorDataFragment
    }
  }
}

Variables

{"filter": {"city": 'Брэст', "isOnline": true}}

Response

{
  "data": {
    "locations": [
      {
        "_id": "BY01001060",
        "city": "Brest",
        "name": "Тэхнапарк",
        "isOnline": true,
        "latitude": 53.88022411496701,
        "longitude": 29.86211252212241,
        "status": Status,
        "currentValue": SensorData,
        "timeSeries": [SensorData]
      }
    ]
  }
}

`myLocations`

Query for user's own locations. Returns array of location info and sensor data

Returns [Location]

Example

Query

query myLocations {
  myLocations {
    _id
    city
    name
    isOnline
    latitude
    longitude
    status {
      ...StatusFragment
    }
    currentValue {
      ...SensorDataFragment
    }
    timeSeries {
      ...SensorDataFragment
    }
  }
}

Response

{
  "data": {
    "myLocations": [
      {
        "_id": "BY01001060",
        "city": "Brest",
        "name": "Тэхнапарк",
        "isOnline": false,
        "latitude": 53.88022411496701,
        "longitude": 29.86211252212241,
        "status": Status,
        "currentValue": SensorData,
        "timeSeries": [SensorData]
      }
    ]
  }
}

Types

`City`

City details

Field Name	Description
`_id` - `String`	City id
`countryCode` - `String`	2-symbol country code
`cityName` - `CityName`	CityName object
`locationCount` - `Int`	Number of sensor locations within city boundaries

Example

{
  "_id": "BY06001",
  "countryCode": "BY",
  "cityName": CityName,
  "locationCount": 15
}

Types

`CityName`

City Names

Field Name	Description
`be` - `String`	City name in belarusian
`ru` - `String`	City name in russian
`en` - `String`	City name in english

Example

{
  "be": "Вiцебск",
  "ru": "Витебск",
  "en": "Viciebsk"
}

Types

`ISODate`

A custom scalar that returns date and time in ISO 8601 format

Example

"2020-10-07T01:08:03.420Z"

Types

`LastFilter`

Input values to filter the query

Input Field	Description
`city` - `String`	City name in any (be, ru, en) language
`interval_d` - `Int` default = `0`	Averaging interval, days
`interval_h` - `Int` default = `0`	Averaging interval, hours
`interval_m` - `Int` default = `15`	Averaging interval, minutes, default = 15

Example

{
  "city": "Брэст",
  "interval_d": 0,
  "interval_h": 0,
  "interval_m": 15
}

Types

`Location`

Object containing sensor location info and sensor data

Field Name	Description
`_id` - `String`	Location ID
`city` - `String`	City name in English
`name` - `String`	Location name
`isOnline` - `Boolean`	Location online state
`latitude` - `Float`	Location latitude
`longitude` - `Float`	Location longitude
`status` - `Status`	Location telemetry info
`currentValue` - `SensorData`	Returns current measurements. Should be supplied with interval argument from `TimeSpan` input filter
Arguments `input` - `TimeSpan`
`timeSeries` - `[SensorData]`	Returns series of measurements. Should be supplied with `TimeSpan` input filter
Arguments `input` - `TimeSpan`

Example

{
  "_id": "BY01001060",
  "city": "Brest",
  "name": "Тэхнапарк",
  "isOnline": true,
  "latitude": 53.88022411496701,
  "longitude": 29.86211252212241,
  "status": Status,
  "currentValue": SensorData,
  "timeSeries": [SensorData]
}

Types

`LocationFilter`

Single location filter

Input Field	Description
`_id` - `String`	Location id
`name` - `String`	Location name

Example

{
  "_id": "BY05001023",
  "name": "Serabranka"
}

Types

`LocationsFilter`

Multiple locations filter

Input Field	Description
`_id` - `String`	Location id
`city` - `String`	City name in any language
`countryCode` - `String`	2-symbol country code
`isOnline` - `Boolean`	Show only online or offline locations

Example

{
  "_id": "BY01001045",
  "city": "Брэст",
  "countryCode": "BY",
  "isOnline": true
}

Types

`MeanFilter`

Input values to filter the query. Mandatory fields are marked with !

Input Field	Description
`city` - `String`	City name in any (be, ru, en) language
`t_from` - `ISODate!`	Start time in ISO 8601 format. Mandatory
`t_to` - `ISODate!`	End time in ISO 8601 format. Mandatory
`interval_d` - `Int` default = `0`	Averaging interval, days
`interval_h` - `Int` default = `0`	Averaging interval, hours
`interval_m` - `Int` default = `15`	Averaging interval, minutes, default = 15

Example

{
  "city": "Brest",
  "t_from": "2021-09-07T01:08:03.420Z",
  "t_to": "2021-10-08T01:08:03.420Z",
  "interval_d": 0,
  "interval_h": 0,
  "interval_m": 30
}

Types

`SensorData`

Sensor values

Field Name	Description
`time` - `ISODate`	Time in ISO 8601 format, UTC time
`Temp` - `Float`	Temperature, °C
`Hum` - `Float`	Relative humidity, %
`Press` - `Float`	Air pressure, hPa
`PMS1` - `Float`	PM1 particulate matter, μg/m³
`PMS25` - `Float`	PM2.5 particulate matter, μg/m³
`PMS10` - `Float`	PM10 particulate matter, μg/m³
`Count` - `Float`	Ambient radioactivity, μSv/h

Example

{
  "time": "2021-11-21T16:34:27.191Z",
  "Temp": "-10.05",
  "Hum": "36.31",
  "Press": "985.99",
  "PMS1": "3.49",
  "PMS25": "4.17",
  "PMS10": "6.22",
  "Count": "0.112"
}

Types

`Status`

Sensor telemetry

Field Name	Description
`RSSI` - `Int`	WiFi signal strength, dB
`build` - `String`	Sensor firmware version
`uptime` - `Int`	Location uptime, minutes

Example

{
  "RSSI": "-75",
  "build": "20210819TZV-noDebug",
  "uptime": "360"
}

Types

`TimeSpan`

Time span and interval

Input Field	Description
`t_from` - `ISODate`	Start time in ISO 8601 format
`t_to` - `ISODate`	End time in ISO 8601 format
`interval_d` - `Int` default = `0`	Averaging interval, days
`interval_h` - `Int` default = `0`	Averaging interval, hours
`interval_m` - `Int` default = `15`	Averaging interval, minutes, default = 15

Example

{
  "t_from": "2021-09-07T01:08:03.420Z",
  "t_to": "2021-10-07T01:08:03.420Z",
  "interval_d": 0,
  "interval_h": 0,
  "interval_m": 15
}

Documentation by Anvil SpectaQL