Back to top

Kaiterra API

Version: 2019-2-12

Overview

The Kaiterra API allows your programs to access the air quality data reported by your Laser Egg, Laser Egg 2/2+, or Sensedge.

We follow standard HTTP/REST API conventions, so retrieving data looks like this:

$ export KAITERRA_APIV1_URL_KEY=0123456789abcdef-YOUR-API-KEY
$ curl -v "https://api.origins-china.cn/v1/lasereggs/00000000-0001-0001-0000-00007e57c0de?key=$KAITERRA_APIV1_URL_KEY"
 ... snip some rows ...
> GET /v1/lasereggs/00000000-0001-0001-0000-00007e57c0de?key=kOpAgVMnz2zM5l6XKQwv4JmUEvopnmUewFKXQ0Wvf9Su72a9 HTTP/1.1
> Host: api.origins-china.cn
> User-Agent: curl/7.50.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Date: Mon, 15 May 2017 08:21:08 GMT
< Content-Length: 232
< Vary: Origin
<
{"id":"00000000-0001-0001-0000-00007e57c0de","info.aqi":{"ts":"2018-03-26T08:53:20Z","data":{"pm10":120,"pm25":214}}}
* Connection #0 to host api.origins-china.cn left intact

Get your API key by signing up at dashboard.kaiterra.cn.

Note: this document was formatted with API Blueprint.

Common Concepts

Auth

Anonymous requests to the API are disallowed. Get your API key by signing up at dashboard.kaiterra.cn.

We support the following kinds of authentication:

  • URL-based key: When issuing an HTTP request, the client includes the key in a URL parameter called key (this is how e.g. Google Maps works). All requests must use HTTPS, so the key is safe from eavesdropping. This method is simple, but it’s only suitable for clients that are running on trusted devices, such as a server you control, or a researcher’s workstation. These keys must NOT be embedded directly into web pages, or iOS or Android apps.

To demonstrate how to call the API, we’ve published some Python examples on GitHub.

If authentication information is required but not present, or if it is not accepted, HTTP 401 is returned (401 is called “Unauthorized”, but it should really be called “Unauthenticated”).

Query String Conventions

  • Unique Device IDs (UDIDs) for Laser Eggs and other devices are 128-bit UUIDs. They’re case-insensitive and may be submitted with or without intermediate dashes (3d6d04a2-ba9f-11e6-9598-0800200c9a66 and c9f7cf2f98064884aa860315e85951f6 are both OK).

    • Note: there are no permissions on Laser Eggs, so anyone with access to the API can request data for any Laser Egg for which they know the ID. However, Laser Egg IDs are 128 bits long, so they have far more entropy than any password that a user account may have, which makes them much harder to guess.
  • All dates/times follow RFC3339 (a refinement of ISO8601), which looks like 2016-12-07T05:32:16Z. Milliseconds are accepted but are ignored (truncated). All times must be in UTC; any that aren’t will be rejected with 400 bad request.

Request Headers

The following headers are technically optional but are a good idea:

  • Accept-Encoding: gzip is supported; clients are encouraged to use it.

  • Content-Encoding: if there is a request body, this header denotes its encoding. Always use UTF-8.

Pollutant Data

Data on various pollutants or other metrics (like temperature and humidity) are returned in JSON dictionaries.

All pollutant measurements have default units of micrograms per cubic meter (µg/m³). If the units are otherwise, they are called out below, or specified in parentheses after the pollutant name, like co (mg/m3) or nox (ppb).

Property names are:

Laser Egg, Laser Egg 2/2+

  • pm25: PM2.5 (µg/m³), post-calibration

  • pm10: PM10 (µg/m³), post-calibration

  • humidity: relative humidity in % (0-100)

  • temp: temperature in Celsius

  • rtvoc: (Laser Egg 2+) TVOC measurement, in parts per billion (ppb)

Sensedge

Available Sensedge measurement properties depend on which modules are inserted. Properties are prefixed with the model number of the module.

  • km100.rpm25c: PM2.5 (µg/m³), post-calibration

  • km100.rpm10c: PM10 (µg/m³), post-calibration

  • km102.rhumid: relative humidity in % (0-100)

  • km102.rtemp: temperature in Celsius

  • km102.rtvoc (ppb): TVOC measurement, in parts per billion (ppb)

  • rco2 (ppm): CO2 measurement from the unit’s built-in sensor, in parts per million (ppm)

Kaiterra Devices

Laser Eggs

Laser Egg Info
GET/lasereggs/{id}

Example URI

GET <https://api.origins-china.cn/v1>/lasereggs/00000000-0001-0001-0000-00007e57c0de
URI Parameters
HideShow
id
string (required) Example: 00000000-0001-0001-0000-00007e57c0de

Unique ID of the laser egg whose details are being requested.

Response  200
HideShow

The egg’s most recent sensor reading is returned. If the egg has been registered but has never reported any data, then the data element is omitted from the response.

Body
{
  "id": "00000000-0001-0001-0000-00007e57c0de",
  "info.aqi": {
    "ts": "2016-10-27T10:01:42Z",
    "data": {
      "pm25": 34.5,
      "pm10": 12.1
    }
  }
}
Response  404
HideShow

Indicates that a Laser Egg with the given UDID has not yet been registered.

Sensedges

Sensedge info
GET/sensedges/{id}

Example URI

GET <https://api.origins-china.cn/v1>/sensedges/00000000-0031-0001-0000-00007e57c0de
URI Parameters
HideShow
id
string (required) Example: 00000000-0031-0001-0000-00007e57c0de

Unique ID of the device whose details are being requested.

Response  200
HideShow

Only the most recent data from the Sensedge’s sensors is returned. If the device exists but has never reported any data, then the latest element is omitted from the response.

Body
{
        "id": "00000000-0031-0001-0000-00007e57c0de",
        "latest": {
            "ts": "2018-07-24T02:39:18Z",
            "km100.rpm25c": 278,
            "km100.rpm10c": 125,
            "km102.rhumid": 56.36,
            "km102.rtemp": 10.76,
            "km102.rtvoc (ppb)": 402.1,
            "rco2 (ppm)": 1673,
        }
    }
Response  404
HideShow

Indicates that a Sensedge with the given UDID has not yet been registered.

Other

Batch Requests

Submit a Batch Request
POST/batch{?include_headers}

Instead of making multiple HTTP requests, clients can issue one batch request with a special JSON formatted body. The format is nearly identical to Facebook’s batch request API, except that there is no support for dependent requests and other advanced features.

Authentication parameters, such as the key URL parameter, must be included in URL or headers of the POST batch request. Any auth parameters on the sub-requests will be ignored. Each sub-request inherits the authentication and authorization context of the POST batch request. Therefore, it’s possible that some sub-requests will succeed, and others will fail with 403 Forbidden.

While the JSON objects in the batch response will be in the same order as the objects in the batch request, the relative order in which the server fulfills each request is undefined. For example, in a batch request that contains a PATCH and a GET request on the same resource, the result of the GET request may or may not reflect the changes made by the PATCH request.

Example URI

POST <https://api.origins-china.cn/v1>/batch?include_headers=false
URI Parameters
HideShow
include_headers
boolean (required) Example: false

Default: false. Whether to include the response headers for individual responses.

Request
HideShow

The batch request body is a JSON array of request objects. Each object must have a method and relative_url property; other properties are optional.

  • method (string) - The HTTP method to use.

  • relative_url (string) - The URL to request, relative to the Kaiterra API’s base URL.

  • headers (json, optional) - A JSON array of header description objects, each of which has a name and value object.

  • body (string, optional) - The request body for this request. JSON objects must be JSON-encoded before being placed in this string.

Headers
Content-Type: application/json
Body
[
  {
    "method": "GET",
    "relative_url": "lasereggs/00000000-0001-0001-0000-00007e57c0de"
  },
  {
    "method": "GET",
    "relative_url": "sensedges/00000000-0031-0001-0000-00007e57c0de"
  }
]
Response  200
HideShow

Returns the result of each of the requested operations. Note that HTTP 200 will be returned as long as the batch request body could be processed, even if none of the operations succeeded. The example response below has been shortened to keep it brief.

Body
[
  {
    "code": 200,
    "body": "{\"id\":\"00000000-0001-0001-0000-00007e57c0de\",\"info.aqi\":{\"ts\":\"2019-02-12T05:53:48Z\",\"data\":{\"pm10\":120,\"pm25\":170}}}"
  },
  {
    "code": 200,
    "body": "{\"id\":\"00000000-0031-0001-0000-00007e57c0de\",\"latest\":{\"km100.rpm10c\":125,\"km100.rpm25c\":200,\"km102.rhumid\":43.63,\"km102.rtemp\":1.133,\"km102.rtvoc (ppb)\":359.3,\"ts\":\"2019-02-12T05:53:48Z\"}}"
  }
]

Generated by aglio on 12 Feb 2019