Nebo.Live API

Table of Contents

Authentication

Back to top ^

Base url is https://nebo.live/api. You can either use the default version /api/cities or explicitly specify the desired version /api/v2/cities. You can optionally specify the locale /api/en/cities or /api/v2/en/cities.

Each application is given a pair of keys by the system administrator: token and code. Authorization credentials can be read-only or read-write. Write permissions are given separately for each individual sensor (Sensor) of the system.

Basic Request

Back to top ^

Example of request with token = 4eSSZMm53qWWBdG6oidg4CZV, code = C2SXU6xu9TV7pWA1CFJjrvnA and time = 1642338547 (13:09:07 GMT 01/16/2022, Jan 16th 2022). Full SHA-1 digest of concat(time, code) is 1adcf12f957980bf86d479d7babd92a2b6b7204f, hash = 12f957980bf

curl --header "X-Auth-Nebo: 4eSSZMm53qWWBdG6oidg4CZV" https://nebo.live/api/v2/en/cities?time=1642338547&hash=12f957980bf

Responses

Back to top ^

Requests

Back to top ^

All responses from the server are in JSON format, unless otherwise specified.

GET /api/v2/cities

Back to top ^

List of all registered cities

[
  {
    "id": "d330b106-3919-4797-b109-a782b40c9303",
    "name": "Beautiful",
    "country": "Narnia",
    "url": "narnia",
    "lat": 10.123456 # Double?
    "lng": 10.123456 # Double?
  },
  ...
]

GET /api/v2/cities/slug

Back to top ^

List of all sensors from city with slug. Slug is an url from cities-request

[
{
  "id": "a6cd67a8-9b00-4be7-adb3-1173212da047",
  "name": "Kopylova",
  "source": "Nebo",
  "source_description": "Source description",
  "source_link": "http://mega-link.local", # String?
  "source_logo": "aofuasofu.svg", # String?
  "lat": 0, # Double?
  "lng": 0, # Double?
  "instant": {
      "pm25": 4, # Integer?
      "pm10": null, # Integer?
      "pm01": null, # Integer?
      "aqi": 17, # Integer
      "pm25_aqi": 17, # Integer?
      "pm10_aqi": 0, # Integer?
      "pm01_aqi": null, # Integer?
      "co_aqi": null, # Integer?
      "so2_aqi": 0, # Integer?
      "so2": null, # Double?
      "created_at": "2020-03-13T10:51:06.812Z",
      "ts": 1584096666, # Integer
      "humidity": 49, # Double?
      "temperature": 8, # Double?
      "co": 451 # Double?
  }
},
{
    "id": "45ed1430-acef-43c5-a305-49b80b2b0bdc",
    "name": "Ady Lebedevoy",
    "source": "Nebo",
    "source_description": "Source description",
    "source_link": "http://mega-link.local", # String?
    "source_logo": "aofuasofu.svg", # String?
    "lat": 56.015892, # Double?
    "lng": 92.871704, # Double?
    "instant": {
        "pm25": 4, # Integer?
        "pm10": null, # Integer?
        "pm01": null, # Integer?
        "aqi": 17, # Integer
        "pm25_aqi": 17, # Integer?
        "pm10_aqi": 0, # Integer?
        "pm01_aqi": null, # Integer?
        "co_aqi": null, # Integer?
        "so2_aqi": 0, # Integer?
        "so2": null, # Double?
        "created_at": "2020-03-13T10:51:06.812Z",
        "ts": 1584096666, # Integer
        "humidity": 49, # Double?
        "temperature": 8, # Double?
        "co": 451 # Double?
    }
}
]

GET /api/v2/cities/slug/weather

Back to top ^

Weather data for city with slug. Slug is an url from cities-request

{
    "pressure": 1018, # Integer
    "visibility": 10000, # Integer
    "wind_speed": 8, # Integer
    "wind_direction": 260, # Integer
    "clouds": 0, # Integer
    "icon": "01d" # String?
}

GET /api/v2/sensors/slug

Back to top ^

Current data for sensor slug. Slug is an id for element from list of sensors.

{
    "id": "45ed1430-acef-43c5-a305-49b80b2b0bdc",
    "name": "Ady Lebedevoy",
    "source": "Nebo",
    "source_description": "Source description",
    "source_link": "http://mega-link.local", # String?
    "source_logo": "aofuasofu.svg", # String?
    "lat": 56.015892, # Double?
    "lng": 92.871704, # Double?
    "instant": {
        "pm25": 4, # Integer?
        "pm10": null, # Integer?
        "pm01": null, # Integer?
        "aqi": 17, # Integer
        "pm25_aqi": 17, # Integer?
        "pm10_aqi": 0, # Integer?
        "pm01_aqi": null, # Integer?
        "co_aqi": null, # Integer?
        "so2_aqi": 0, # Integer?
        "so2": null, # Double?
        "created_at": "2020-03-13T10:51:06.812Z",
        "ts": 1584096666, # Integer
        "humidity": 49, # Double?
        "temperature": 8, # Double?
        "co": 451 # Double?
    }
}

PUT /api/v2/sensors/slug

Back to top ^

Add new single data measurement for sensor slug. Slug is an id for element from list of sensors.

Input data is

{
  "value": {
    "pm25":151,
    ... # Additional measurements
    "created_at": "2018-01-04T14:49:17.470Z"
  }
}

On success returns saved value

{
  "id": "42fd9caf-7349-4563-b9e2-47635e667bf6",
  "pm25": 151,
  "created_at": "2018-01-04T14:49:17.470Z"
}

On failure returns status code 400 with blank response body.

GET /api/v2/sensors/slug/minute

Back to top ^

Raw measured data from sensor slug for the last 60 minutes. Slug is an id for element from list of sensors.

[
  {
    "pm25": 4, # Integer?
    "pm10": null, # Integer?
    "pm01": null, # Integer?
    "aqi": 17, # Integer
    "pm25_aqi": 17, # Integer?
    "pm10_aqi": 0, # Integer?
    "pm01_aqi": null, # Integer?
    "co_aqi": null, # Integer?
    "so2_aqi": 0, # Integer?
    "so2": null, # Double?
    "created_at": "2020-03-13T10:51:07.812Z",
    "ts": 1584096667, # Integer
    "humidity": 49, # Double?
    "temperature": 8, # Double?
    "co": 451 # Double?
  },
  {
    "pm25": 4, # Integer?
    "pm10": null, # Integer?
    "pm01": null, # Integer?
    "aqi": 17, # Integer
    "pm25_aqi": 17, # Integer?
    "pm10_aqi": 0, # Integer?
    "pm01_aqi": null, # Integer?
    "co_aqi": null, # Integer?
    "so2_aqi": 0, # Integer?
    "so2": null, # Double?
    "created_at": "2020-03-13T10:54:07.812Z",
    "ts": 1584099667, # Integer
    "humidity": 49, # Double?
    "temperature": 8, # Double?
    "co": 451 # Double?
  }
]

GET /api/v2/sensors/slug/daily

Back to top ^

Measured data from sensor slug for the last 365 days, averaged by day. Slug is an id for element from list of sensors.

[
  {
    "pm25": 4, # Integer?
    "pm10": null, # Integer?
    "pm01": null, # Integer?
    "aqi": 17, # Integer
    "pm25_aqi": 17, # Integer?
    "pm10_aqi": 0, # Integer?
    "pm01_aqi": null, # Integer?
    "co_aqi": null, # Integer?
    "so2_aqi": 0, # Integer?
    "so2": null, # Double?
    "created_at": "2020-03-13T10:51:06.812Z",
    "ts": 1584096666, # Integer
    "humidity": 49, # Double?
    "temperature": 8, # Double?
    "co": 451 # Double?
  },
  {
    "pm25": 4, # Integer?
    "pm10": null, # Integer?
    "pm01": null, # Integer?
    "aqi": 17, # Integer
    "pm25_aqi": 17, # Integer?
    "pm10_aqi": 0, # Integer?
    "pm01_aqi": null, # Integer?
    "co_aqi": null, # Integer?
    "so2_aqi": 0, # Integer?
    "so2": null, # Double?
    "created_at": "2020-03-13T10:51:06.812Z",
    "ts": 1584096666, # Integer
    "humidity": 49, # Double?
    "temperature": 8, # Double?
    "co": 451 # Double?
  },
  {
    "pm25": 4, # Integer?
    "pm10": null, # Integer?
    "pm01": null, # Integer?
    "aqi": 17, # Integer
    "pm25_aqi": 17, # Integer?
    "pm10_aqi": 0, # Integer?
    "pm01_aqi": null, # Integer?
    "co_aqi": null, # Integer?
    "so2_aqi": 0, # Integer?
    "so2": null, # Double?
    "created_at": "2020-03-13T10:51:06.812Z",
    "ts": 1584096666, # Integer
    "humidity": 49, # Double?
    "temperature": 8, # Double?
    "co": 451 # Double?
  },
  .......
]

GET /api/v2/sensors/slug/weather

Back to top ^

Weather data for sensor slug. Slug is an id for element from list of sensors.

{
    "pressure": 1018, # Integer
    "visibility": 10000, # Integer
    "wind_speed": 8, # Integer
    "wind_direction": 260, # Integer
    "clouds": 0, # Integer
    "icon": "01d" # String?
}

POST /api/v2/sensors/activate

Back to top ^

Activate new sensor. Serial should be registered by administration before activation.

Input data:

{
  "serial": "dfsdfsdfwerwercsef120",
  "lat": 59.0012,
  "lon": 82.1289182,
  "pressure": 950, # hPa
  "temperature": -15 # Celcius
}

If the activation was successful, it will return the credentials for write-access to sensor. Reactivation (obtaining data for authentication) is not possible, only through communication with the administration.

{
  "id": "42fd9caf-7349-4563-b9e2-47635e667bf6",
  "token": "aAaAaAaAaAaA100500",
  "code":  "BbBbBbBbBbBbBbBbBbB"
}

On failure returns status code 400 with blank response body.

Manage clients and notifications

Back to top ^

All of following methods (managing users and alert settings) do not require mandatory request authorization with header and time, hash.

POST /api/v2/clients

Back to top ^

Create new client for notification system

Input data

{
  "client": {
    "telegram": 0, # must be one of this
    "firebase": 0  # must be one of this
  }
}

Returns

{
  "id": "a6cd67a8-9b00-4be7-adb3-1173212da047",
  "telegram": 0,
  "firebase": 0,
  "created_at": "2018-01-04T08:21:00.000Z"
}

DELETE /api/v2/clients/slug

Back to top ^

Delete client of notification system with all nested notifications settings. Slug is an identity number from Firebase or Telegram.

Returns blank response with code 200 or 404.

GET /api/v2/clients/slug/noifications

Back to top ^

List of notification settings for client with slug. Slug - is an identity number from Firebase or Telegram.

[
  {
    "id":"793d2b39-f912-4c8b-809e-093579f91c60",
    "notable_id":"17ebc296-4f44-421e-b80b-c1aade566483",
    "notable_type":"City",
    "limit":100, # Integer
    "created_at":"2018-04-10T10:34:00.365Z",
    "notable_name":"London"
  },
  {
    "id":"69eb6430-0ad1-4855-8967-9c525f516031",
    "notable_id":"77c1e0fb-a047-46e2-9490-004a11fad69c",
    "notable_type":"City",
    "limit":150, # Integer
    "created_at":"2018-04-10T10:52:30.346Z",
    "notable_name":"Krasnoyarsk"
  }
]

POST /api/v2/clients/slug/notifications

Back to top ^

Create new subscription for notification for client with slug. Slug - is an identity number from Firebase or Telegram.

{
  "notification": {
    "notable_id":"77c1e0fb-a047-46e2-9490-004a11fad69c",
    "notable_type":"Sensor", # or "notable_type":"City",
    "limit":150, # Integer
  }
}

Output

{
  "id": "a6cd67a8-9b00-4be7-adb3-1173212da047",
  "notable_id":"77c1e0fb-a047-46e2-9490-004a11fad69c",
  "notable_type":"Sensor", # or "notable_type":"City",
  "limit":150, # Integer
  "created_at": "2018-01-04T08:21:00.000Z"
}

DELETE /api/v2/clients/*client_slug*/notifications/*notification_slug*

Back to top ^

Create new subscription for notification for client with slug. Client_slug - is an identity number from Firebase or Telegram. Notification_slug - is an id from create-request

Returns blank response with code 200 or 404.

Users data

Back to top ^

OAuth is used for this section. You should add header Authorization with value Bearer: token to all requests. All needed data you can find through .well-known url.

GET|POST /api/v2/favorites

Back to top ^

List of favorite sensors for current user. User fetched from bearer token.

{
  "data": [

    {
      "sensor_id":"783d2b39-f912-4c8b-809e-093579f91c60",
      "name":"Title of sensor by user",
      "description":"Name of sensor from system",
      "position": 0, # will be sorted by it
      "image_index": 15 # 1-18
    },
    {
      "sensor_id":"69eb6430-0ad1-4855-8967-9c515f516031",
      "name":"Another title",
      "description":"Name of sensor from system",
      "position": 1,
      "image_index": 15
    }

    ....

  ]
}