Skip to content

Latest commit

 

History

History
317 lines (213 loc) · 34.1 KB

apiary.md

File metadata and controls

317 lines (213 loc) · 34.1 KB
Raw

FORMAT: 1A HOST: https://api.arrayofthings.org/api

Array of Things HTTP API

Welcome the Array of Things HTTP API!

The Array of Things (AoT) is an experimental environmental sensing project. More information about the project can be found at https://arrayofthings.org/.

Data, Entities and Relationships

Data, in the sense of sensor measurements and node metrics, are maintained in the API for one week. After a week, the data is expunged from the database. If you need data that is older than seven days, we recommend you use the AoT File Browser to access the full data sets.

Results from the API are returned as pages of data, and can be sized and iterated against using the order, page and size query parameters.

The size parameter controls the number of results returned in the page. It must be an integer between 1 and 5000. The default value is 200.

The page parameter controls which page of data is being returned. It must be an integer of at least 1 with no enforced maximum -- values that exceed the number of records available for a given entity will return an empty page. The default value is 1.

The order parameter controls the ordering of the results in the page. It is a string, and it must follow the format {direction}:{field} where direction is one of asc for ascending order or desc for descending order, and field is the field name of the entity to order on. Each entity has its own default ordering:

  • projects are arranged by slug in ascending order
  • nodes are arranged by vsn in ascending order
  • sensors are arranged by path in ascending order
  • observations and metrics are arranged by timestamp in descending order

The following listings describe the entities made available via the API.

Projects

The Array of Things is geographically distributed globally. Nodes within the system are arranged by projects. Most commonly these projects are named for major urban centers or universities that administer the nodes. For example, our largest deployment of nodes is in the city of Chicago so we have a project named chicago to track those nodes; just as we have a set of nodes administered by Vanderbilt University and project named vanderbilt.

Field Type Description
name string The full name of the project
slug string The slugged name used to build references
hull geojson object The convex hull of the nodes that are part of the project
archive_url string The link to the full CSV archive of the project's data

Nodes

Nodes are the physical devices that are deployed to record measurements. They are typically comprised of several sensors that record multiple observation types.

Field Type Description
vsn string The unique identifier of the node -- its name
location geojson object The coordinates of the node
address string The human readable location of the node
description string Additional information about the node

Sensors

Sensors are the (usually, although not always) physical devices onboard the nodes that record measurements. In some instances, sensors are purely software based and rely on one or more other physical devices for input to record their observations -- for example the image detection sensors use a single camera input to determine car and pedestrian counts at intersections.

Field Type Description
path string The unique identifier of the sensor -- its name
uom string The unit of measurement the sensor records its observations in
min float The typical minimum value of the observation values recorded
max float The typical maximum value of the observation values recorded
data_sheet string A link to the sensor's data sheet

Observations and Metrics

Sensors record their measurements, and those are collected as one of two different types: observations are the environmental measurements that are recorded (e.g. temperature), and metrics are the system measurements collected for monitoring and error reporting (e.g. CPU load). They both have the same table structure and are separated only because they are interesting to different groups of users -- someone designing a map of urban heat islands probably doesn't care much about the humidity inside of the node, just as I (an AoT admin) want to be able to create applications to monitor node state and send alerts when things go sideways.

Field Type Description
node_van string The reference to the node from which the measurement was recorded
sensor_path string The reference to the sensor that recorded the measurement
location geojson object The coordinates of the node when the measurement was recorded
timestamp UTC date time string The date and time (in UTC) that the measurement was recorded
value float The value of the recorded measurement
uom string The unit of measurement of the recorded measurement

The API Endpoints

Each entity type has its own endpoint in the API.

NOTE: The API has a rate limit of 1,000 requests per minute per IP address.

Project [/projects/{slug}]

Get a single project.

  • Parameters
    • slug (string) - The slug value of the project you want detailed information from.

Project Details [GET]

Projects [/projects{?order,size,page,format}]

Page through projects.

  • Parameters
    • order (string, optional) - Controls the ordering of the results in the page. It must follow the format {direction}:{field} where direction is one of asc for ascending order or desc for descending order, and field is the field name of the entity to order on. The default is asc:name.
    • size (number, optional) - Controls the number of results returned in the page. It must be an integer between 1 and 5000. The default value is 200.
    • page (number, optional) - Controls which page of data is being returned. It must be an integer of at least 1 with no enforced maximum -- values that exceed the number of records available for a given entity will return an empty page. The default value is 1.
    • format (string, optional) - Controls the type of the data returned. It must be one of json or geojson. The default value is json.

List Projects [GET]

List Projects in a 2 Sized Page, Second Page [GET]

Node [/nodes/{vsn}]

Get a single node.

  • Parameters
    • vsn (string) - The vsn value of the node you want detailed information from.

Node Details [GET]

  • Parameters

    • vsn (string) - The vsn value of the node you want detailed information from.
      • Default: 004

  • Response 200 (application/json)

    {"data":{"vsn":"004","location":{"type":"Feature","geometry":{"type":"Point","crs":{"type":"name","properties":{"name":"EPSG:4326"}},"coordinates":[-87.627678,41.878377]}},"description":"AoT Chicago (S) [C]","address":"State St & Jackson Blvd Chicago IL"}}

Nodes [/nodes{?order,size,page,format,location,project}]

Page through nodes.

There is a special parameter for this endpoint: location. The parameter takes a special format to filter results.

?location=within:{GeoJSON object} filters results to those whose location value is within the given GeoJSON object. This is to say that a node resides within a given bounding box.

?location=diwithin:{distance in meters}:{GeoJSON object} filters results to those whose location is within the given distance from the given GeoJSON object. This is to say that a node is location within X meters from a given point.

The format of the GeoJSON object is a fully URL encoded object. In its full format (without encoding), you would specify values such as:

?location=within:{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [1, 1],
      [1, 2],
      [2, 2],
      [2, 1],
      [1, 1]
    ]],
    "crs": {
      "type": "name",
      "properties": {
        "name": "EPSG:4326"
      }
    }
  }
}

or

?location=dwithin:2000:{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [1,2],
    "crs": {
      "type": "name",
      "properties": {
        "name": "EPSG:4326"
      }
    }
  }
}
  • Parameters
    • order (string, optional) - Controls the ordering of the results in the page. It must follow the format {direction}:{field} where direction is one of asc for ascending order or desc for descending order, and field is the field name of the entity to order on. The default is asc:vsn.
    • size (number, optional) - Controls the number of results returned in the page. It must be an integer between 1 and 5000. The default value is 200.
    • page (number, optional) - Controls which page of data is being returned. It must be an integer of at least 1 with no enforced maximum -- values that exceed the number of records available for a given entity will return an empty page. The default value is 1.
    • format (string, optional) - Controls the type of the data returned. It must be one of json or geojson. The default value is json.
    • location (object,optional) - See notes above. The default is null.
    • project (string, optional) - Filters the results to those who are related to the project slug. Default is null.

List Nodes [GET]

List Nodes, Limit to Chicago, Return GeoJSON [GET]

  • Parameters

    • size (number, optional) - Controls the number of results returned in the page. It must be an integer between 1 and 5000. The default value is 200.
      • Default: 5
    • format (string, optional) - Controls the type of the data returned. It must be one of json or geojson. The default value is json.
      • Default: geojson
    • project (string, optional) - Filters the results to those who are related to the project slug. Default is null.
      • Default: chicago

  • Response 200 (application/json)

    {"meta":{"links":{"previous":null,"next":"https://api-of-things.plenar.io/api/nodes?format=geojson&order=asc%3Avsn&page=2&project=chicago&size=5","current":"https://api-of-things.plenar.io/api/nodes?format=geojson&order=asc%3Avsn&page=1&project=chicago&size=5"}},"data":[{"type":"Feature","properties":{"vsn":"004","description":"AoT Chicago (S) [C]","address":"State St & Jackson Blvd Chicago IL"},"geometry":{"type":"Point","crs":{"type":"name","properties":{"name":"EPSG:4326"}},"coordinates":[-87.627678,41.878377]}},{"type":"Feature","properties":{"vsn":"006","description":"AoT Chicago (S)","address":"18th St & Lake Shore Dr Chicago IL"},"geometry":{"type":"Point","crs":{"type":"name","properties":{"name":"EPSG:4326"}},"coordinates":[-87.616055,41.858136]}},{"type":"Feature","properties":{"vsn":"00A","description":"AoT Chicago (S) [CA]","address":"Lake Shore Drive & Fullerton Ave Chicago IL"},"geometry":{"type":"Point","crs":{"type":"name","properties":{"name":"EPSG:4326"}},"coordinates":[-87.6307578,41.9262614]}},{"type":"Feature","properties":{"vsn":"00D","description":"AoT Chicago (S)","address":"Cornell & 47th St Chicago IL"},"geometry":{"type":"Point","crs":{"type":"name","properties":{"name":"EPSG:4326"}},"coordinates":[-87.590228,41.810342]}},{"type":"Feature","properties":{"vsn":"010","description":"AoT Chicago (S) [C]","address":"Homan Ave & Roosevelt Rd Chicago IL"},"geometry":{"type":"Point","crs":{"type":"name","properties":{"name":"EPSG:4326"}},"coordinates":[-87.710543,41.866349]}}]}

Sensor [/sensors/{path}]

Get a single sensor.

  • Parameters
    • path (string) - The path value of the sensor you want detailed information from.

Sensor Details [GET]

Sensors [/sensors{?order,size,page}]

Page through sensors.

  • Parameters
    • order (string, optional) - Controls the ordering of the results in the page. It must follow the format {direction}:{field} where direction is one of asc for ascending order or desc for descending order, and field is the field name of the entity to order on. The default is asc:path.
    • size (number, optional) - Controls the number of results returned in the page. It must be an integer between 1 and 5000. The default value is 200.
    • page (number, optional) - Controls which page of data is being returned. It must be an integer of at least 1 with no enforced maximum -- values that exceed the number of records available for a given entity will return an empty page. The default value is 1.

List Sensors [GET]

Observations [/observations{?order,size,page,format,location,project,node,sensor,timestamp,value,histogram,time_bucket}]

Page through observations.

  • Parameters
    • order (string, optional) - Controls the ordering of the results in the page. It must follow the format {direction}:{field} where direction is one of asc for ascending order or desc for descending order, and field is the field name of the entity to order on. The default is asc:vsn.
    • size (number, optional) - Controls the number of results returned in the page. It must be an integer between 1 and 5000. The default value is 200.
    • page (number, optional) - Controls which page of data is being returned. It must be an integer of at least 1 with no enforced maximum -- values that exceed the number of records available for a given entity will return an empty page. The default value is 1.
    • format (string, optional) - Controls the type of the data returned. It must be one of json or geojson. The default value is json.
    • location (object,optional) - See notes about the use of location in the nodes section above. The default is null.
    • project (string, optional) - Filters the results to those who are related to the project slug. Default is null.
    • node (string, optional) - Filters the results to those who are related to the node vsn. This can be an array value to limit to multiple nodes using the format node[]=004&node[]=005. Default is null.
    • sensor (string, optional) - Filters the results to those who are related to the sensor path. This can be an array value to limit to multiple sensors using the format sensor[]=foo&sensor[]=bar. Default is null.
    • timestamp (string, optional) - Filters the results to those whose values satisfy the given query. The format of the value must be {function}:{comparator} where function is one of eq, lt, le, gt or ge and the comparator is the value you are comparing against. Default is null.
    • value (string, optional) - Filters the results to those whose values satisfy the given query. The format of the value must be {function}:{comparator} where function is one of eq, lt, le, gt or ge and the comparator is the value you are comparing against. Default is null.
    • histogram (string, optional) - Returns a histogram of values. The format of the value must be {min}::{max}::{number of buckets}. This should be used in conjunction with at least a sensor param and usually in combination with project. Default is null.
    • time_bucket (string, optional) - Returns a histogram of values. The format of the value must be {function}:{interval} where function is one of min, max, avg or median and interval is PostgreSQL interval value (e.g. 6 hours). This should be used in conjunction with at least a sensor param and usually in combination with node or project. Default is null.

List Observations [GET]

List Observations as a Histogram [GET]

List Observations as Time Buckets [GET]