Air-Quality-Web/docs/05-API-Docs.md

# API
The server-side API is accessed through `api.php`, and supports a number of GET parameters. On the main production instance, this can be found [here](https://sensors.connectedhumber.org/api.php).

The most important of these is the `action` parameter, Which determines what the API will do. The following values are supported:

Action									| Meaning
----------------------------------------|----------------------------
[`version`](#version)					| Gets the version of _Air Quality Web_ that's currently running.
[`fetch-data`](#fetch-data)				| Fetches air quality data from the system for a specific data type at a specific date and time.
[`list-devices`](#list-devices)			| Fetches a list of devices currently in the system.
[`list-devices-near`](#list-devices-near)   | Lists the devices close to a given location (new since v0.11!)
[`device-info`](#device-info)			| Gets (lots of) information about a single device.
[`list-reading-types`](#list-reading-types)	| Lists the different types of readings that can be specified.
[`device-data-bounds`](#device-data-bounds)	| Gets the start and end DateTime bounds for the data recorded for a specific device.
[`device-data`](#device-data)			| Gets data by device given a start and end time.
[`changelog`](#changelog)				| Gets the changelog as a fragment of HTML.

These are explained in detail below. First though, a few notes:

 - All dates are in UTC.
 - All datetime-type fields support the keyword `now`.
 - Additional object properties MAY be returned by the API at a later date. Clients MUST ignore additional unknown properties they do not understand.
 - Clients SHOULD respect the `cache-control` headers returned by the API.


## version
> Returns the version of the application.

_No parameters are currently supported by this action._

Examples:


```
https://example.com/path/to/api.php?action=version
```


## fetch-data
> Fetches air quality data from the system for a specific data type at a specific date and time.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`datetime`			| date/time	| Required. Specifies the date and time for which readings are desired. For current data use the special keyword `now`.
`reading_type`		| string	| Required. Specifies the type of reading desired.
`format`            | string    | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

Examples:

```
https://example.com/path/to/api.php?action=fetch-data&datetime=2019-01-03%2007:52:10&reading_type=PM10
https://example.com/path/to/api.php?action=fetch-data&datetime=now&reading_type=PM10
```

## list-devices
> Fetches a list of devices currently in the system.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`only-with-location`| bool		| Optional. If present only devices with a defined location will be returned. Useful for getting a list of devices to place on a map.
`format`            | string    | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

Examples:

```
https://example.com/path/to/api.php?action=list-devices
https://example.com/path/to/api.php?action=list-devices&only-with-location=yes
```

## list-devices-near
> Lists devices close to a given location.


**Remember:** Don't forget that unlike most other API actions, this requires a `POST` request and not a `GET`! This is to preserve privacy, as the web server stores GET parameters along with request urls in the server logs.

### GET Parameters

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`count` 			| int		| Required. Specifies the number of devices to return.

### POST Parameters
POST parameters should be specified as part of the request body. The request should have a `content-type` of `application/x-www-form-urlencoded`.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`latitude`			| float		| Required. The latitude of the location to search for nearby devices.
`longitude`			| float		| Required. The longitude of the location to search for nearby devices.

### Example HTTP Request

```
POST /api.php?action=list-devices-near&count=5 HTTP/1.1
host: airquality.example.com
content-length: 38
content-type: application/x-www-form-urlencoded

latitude=12.345678&longitude=98.765432
```

### Response Object Properties
Since it may not be obvious, the properties returned in a response object are detailed below:

Property			| Meaning
--------------------|----------------------------------
`id`				| The device's unique id.
`name`				| The device's name. Should be unique, but don't count on it.
`latitude`			| The latitude of the device in question.
`longitude`			| The longitude of the aforementioned device.
`distance_calc`		| The distance between the specified point and the device, represented as the length of a relative (lat, long) vector between the 2. _Should_ be accurate enough to get the devices in the right order with respect to the actual distance, but if not please [open an issue](https://github.com/ConnectedHumber/Air-Quality-Web/issues/new)
`distance_actual`	| The actual distance between the specified point and the device, in metres.

## device-info
> Gets (lots of) information about a single device.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`device-id`         | int		| Required. The id of the device to get extended information for. See the `list-device` action for how to get a hold of one.

Examples:

## list-reading-types
> Lists the different types of readings that can be specified.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`device-id`         | int		| Optional. If specified, this filters the list of measurement types to list only those reported by the device with the specified id.
`format`            | string    | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

```
https://example.com/path/to/api.php?action=list-reading-types
https://example.com/path/to/api.php?action=list-reading-types&device-id=22
https://example.com/path/to/api.php?action=list-reading-types&device-id=54
```


## device-data-bounds
> Gets the start and end DateTime bounds for the data recorded for a specific device.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`device-id`         | int		| Required. The id of the device to get the data DateTime bounds for.

```
https://example.com/path/to/api.php?action=device-data-bounds&device-id=18
https://example.com/path/to/api.php?action=device-data-bounds&device-id=11
```

## device-data
> Gets data by device given a start and end time.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`device-id`			| int		| The id of the device to get data for.
`reading-type`		| string	| The type of reading to obtain data for.
`start`				| datetime  | The starting datetime, or the special keyword "now".
`end`				| datetime  | The ending datetime, or the special keyword "now".
`average-seconds`	| int		| Optional. If specified, readings will be grouped into lumps of this many seconds and averaged. For example a value of 3600 (1 hour) will return 1 data point per hour, with the value of each point an average of all the readings for that hour.
`format`            | string    | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

```
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z&average-seconds=3600
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=now&average-seconds=3600&format=csv
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-06-13T00:00:00&end=now&format=csv
```

## device-data-recent
> Gets a given number of the most recent readings for a specific device.

Parameter			| Type		| Meaning
--------------------|-----------|---------------------
`device-id`			| int		| The id of the device to get data for.
`reading-type`		| string	| The type of reading to obtain data for.
`count`				| int		| The number of recent readings to return.
`format`            | string    | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

```
https://example.com/path/to/api.php?action=device-data-recent&device-id=21&reading-type=PM25&count=5
https://example.com/path/to/api.php?action=device-data-recent&device-id=36&reading-type=humidity&count=30
```

## changelog
> Gets the changelog as a fragment of HTML.

_No parameters are currently supported by this action._

```
https://example.com/path/to/api.php?action=changelog
```
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00			`# API`
HTTP API docs: fix link at the top of the page 2021-09-03 20:49:50 +00:00			The server-side API is accessed through `api.php`, and supports a number of GET parameters. On the main production instance, this can be found [here](https://sensors.connectedhumber.org/api.php).
Add link to production api.php in API docs, and change default action to a helpful message Also bump version 2019-05-16 16:31:35 +00:00
			The most important of these is the `action` parameter, Which determines what the API will do. The following values are supported:
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00
Add links to sections in API docs 2019-06-13 19:57:49 +00:00			`Action \| Meaning`
			`----------------------------------------\|----------------------------`
			[`version`](#version) \| Gets the version of _Air Quality Web_ that's currently running.
			[`fetch-data`](#fetch-data) \| Fetches air quality data from the system for a specific data type at a specific date and time.
			[`list-devices`](#list-devices) \| Fetches a list of devices currently in the system.
Add list-devices-near action with appropriate API documentation 2019-06-21 21:05:13 +00:00			[`list-devices-near`](#list-devices-near) \| Lists the devices close to a given location (new since v0.11!)
Add links to sections in API docs 2019-06-13 19:57:49 +00:00			[`device-info`](#device-info) \| Gets (lots of) information about a single device.
			[`list-reading-types`](#list-reading-types) \| Lists the different types of readings that can be specified.
			[`device-data-bounds`](#device-data-bounds) \| Gets the start and end DateTime bounds for the data recorded for a specific device.
			[`device-data`](#device-data) \| Gets data by device given a start and end time.
			[`changelog`](#changelog) \| Gets the changelog as a fragment of HTML.
HTTP API: Add quick reference for actions to the top 2019-06-03 22:25:24 +00:00
Bugfix new device-recent-data action 2019-06-13 21:10:14 +00:00			`These are explained in detail below. First though, a few notes:`

			`- All dates are in UTC.`
			- All datetime-type fields support the keyword `now`.
Add list-devices-near action with appropriate API documentation 2019-06-21 21:05:13 +00:00			`- Additional object properties MAY be returned by the API at a later date. Clients MUST ignore additional unknown properties they do not understand.`
			- Clients SHOULD respect the `cache-control` headers returned by the API.
Bugfix new device-recent-data action 2019-06-13 21:10:14 +00:00
HTTP API: Add quick reference for actions to the top 2019-06-03 22:25:24 +00:00
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00			`## version`
			`> Returns the version of the application.`

			`_No parameters are currently supported by this action._`

			`Examples:`


			```
			`https://example.com/path/to/api.php?action=version`
			```


			`## fetch-data`
			`> Fetches air quality data from the system for a specific data type at a specific date and time.`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`datetime` \| date/time \| Required. Specifies the date and time for which readings are desired. For current data use the special keyword `now`.
			`reading_type` \| string \| Required. Specifies the type of reading desired.
			`format` \| string \| Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

			`Examples:`

			```
			`https://example.com/path/to/api.php?action=fetch-data&datetime=2019-01-03%2007:52:10&reading_type=PM10`
			`https://example.com/path/to/api.php?action=fetch-data&datetime=now&reading_type=PM10`
			```

			`## list-devices`
			`> Fetches a list of devices currently in the system.`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`only-with-location`\| bool \| Optional. If present only devices with a defined location will be returned. Useful for getting a list of devices to place on a map.
			`format` \| string \| Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

			`Examples:`

			```
			`https://example.com/path/to/api.php?action=list-devices`
			`https://example.com/path/to/api.php?action=list-devices&only-with-location=yes`
			```

Add list-devices-near action with appropriate API documentation 2019-06-21 21:05:13 +00:00			`## list-devices-near`
			`> Lists devices close to a given location.`


			Remember: Don't forget that unlike most other API actions, this requires a `POST` request and not a `GET`! This is to preserve privacy, as the web server stores GET parameters along with request urls in the server logs.

			`### GET Parameters`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`count` \| int \| Required. Specifies the number of devices to return.

			`### POST Parameters`
			POST parameters should be specified as part of the request body. The request should have a `content-type` of `application/x-www-form-urlencoded`.

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`latitude` \| float \| Required. The latitude of the location to search for nearby devices.
			`longitude` \| float \| Required. The longitude of the location to search for nearby devices.

			`### Example HTTP Request`

			```
			`POST /api.php?action=list-devices-near&count=5 HTTP/1.1`
			`host: airquality.example.com`
			`content-length: 38`
			`content-type: application/x-www-form-urlencoded`

			`latitude=12.345678&longitude=98.765432`
			```

			`### Response Object Properties`
			`Since it may not be obvious, the properties returned in a response object are detailed below:`

			`Property \| Meaning`
			`--------------------\|----------------------------------`
			`id` \| The device's unique id.
			`name` \| The device's name. Should be unique, but don't count on it.
			`latitude` \| The latitude of the device in question.
			`longitude` \| The longitude of the aforementioned device.
typo in link 2019-06-22 14:52:24 +00:00			`distance_calc` \| The distance between the specified point and the device, represented as the length of a relative (lat, long) vector between the 2. _Should_ be accurate enough to get the devices in the right order with respect to the actual distance, but if not please [open an issue](https://github.com/ConnectedHumber/Air-Quality-Web/issues/new)
Add list-devices-near action with appropriate API documentation 2019-06-21 21:05:13 +00:00			`distance_actual` \| The actual distance between the specified point and the device, in metres.

Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00			`## device-info`
			`> Gets (lots of) information about a single device.`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`device-id` \| int \| Required. The id of the device to get extended information for. See the `list-device` action for how to get a hold of one.

			`Examples:`

			`## list-reading-types`
			`> Lists the different types of readings that can be specified.`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`device-id` \| int \| Optional. If specified, this filters the list of measurement types to list only those reported by the device with the specified id.
			`format` \| string \| Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

			```
			`https://example.com/path/to/api.php?action=list-reading-types`
			`https://example.com/path/to/api.php?action=list-reading-types&device-id=22`
			`https://example.com/path/to/api.php?action=list-reading-types&device-id=54`
			```


			`## device-data-bounds`
			`> Gets the start and end DateTime bounds for the data recorded for a specific device.`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`device-id` \| int \| Required. The id of the device to get the data DateTime bounds for.

			```
			`https://example.com/path/to/api.php?action=device-data-bounds&device-id=18`
			`https://example.com/path/to/api.php?action=device-data-bounds&device-id=11`
			```

			`## device-data`
			`> Gets data by device given a start and end time.`

			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`device-id` \| int \| The id of the device to get data for.
			`reading-type` \| string \| The type of reading to obtain data for.
API Docs: Clarify that "now" as a special keyword is allowed 2019-06-13 20:06:30 +00:00			`start` \| datetime \| The starting datetime, or the special keyword "now".
			`end` \| datetime \| The ending datetime, or the special keyword "now".
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00			`average-seconds` \| int \| Optional. If specified, readings will be grouped into lumps of this many seconds and averaged. For example a value of 3600 (1 hour) will return 1 data point per hour, with the value of each point an average of all the readings for that hour.
			`format` \| string \| Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.

			```
			`https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z`
			`https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z&average-seconds=3600`
			`https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=now&average-seconds=3600&format=csv`
API Docs: Clarify that "now" as a special keyword is allowed 2019-06-13 20:06:30 +00:00			`https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-06-13T00:00:00&end=now&format=csv`
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00			```

Implement new device-data-recent, but it's not working right. 2019-06-13 21:02:04 +00:00			`## device-data-recent`
			`> Gets a given number of the most recent readings for a specific device.`
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00
Implement new device-data-recent, but it's not working right. 2019-06-13 21:02:04 +00:00			`Parameter \| Type \| Meaning`
			`--------------------\|-----------\|---------------------`
			`device-id` \| int \| The id of the device to get data for.
			`reading-type` \| string \| The type of reading to obtain data for.
			`count` \| int \| The number of recent readings to return.
			`format` \| string \| Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`.
API Docs: Clarify that "now" as a special keyword is allowed 2019-06-13 20:06:30 +00:00
Implement new device-data-recent, but it's not working right. 2019-06-13 21:02:04 +00:00			```
			`https://example.com/path/to/api.php?action=device-data-recent&device-id=21&reading-type=PM25&count=5`
			`https://example.com/path/to/api.php?action=device-data-recent&device-id=36&reading-type=humidity&count=30`
			```
API Docs: Clarify that "now" as a special keyword is allowed 2019-06-13 20:06:30 +00:00
Try to setup docpress, but it doesn't appear to work. 2019-03-12 13:24:11 +00:00			`## changelog`
			`> Gets the changelog as a fragment of HTML.`

			`_No parameters are currently supported by this action._`

			```
			`https://example.com/path/to/api.php?action=changelog`
			```