Introduction
KNOC API expects an API token to be included with every request in Authorization header like this:
Authorization: Bearer api.example-token
Data API
Get Server Information
This endpoint returns server configuration information that is considered to be useful for data clients.
curl "http://example.com/api/data/v1/info" \
-H "Authorization: Bearer api.example-token"
The above command returns JSON structured like this:
{
"timezone": "Europe/Tallinn"
}
HTTP Request
GET http://example.com/api/data/v1/info
Response structure
| Property | Description |
|---|---|
| timezone | Server timezone as understood by the tz database. This timezone should be used for displaying data to user. |
Get All Areas
curl "http://example.com/api/data/v1/areas" \
-H "Authorization: Bearer api.example-token"
The above command returns JSON structured like this:
[
{
"id": 1,
"name": "Area 1",
"mapArea": null,
"mapPolygon": null
},
{
"id": 2,
"name": "Area 2",
"mapArea": null,
"mapPolygon": null
},
{
"id": 3,
"name": "Area 3",
"mapArea": null,
"mapPolygon": null
}
]
This endpoint returns all areas.
HTTP Request
GET http://example.com/api/data/v1/areas
Response structure
This endpoint returns an array of Area objects with the following structure:
| Property | Description |
|---|---|
| id | Area ID |
| name | Area name |
| mapArea | Currently null, but might be populated in future updates. |
| mapPolygon | Currently null, but might be populated in future updates. |
Get All Groups
curl "http://example.com/api/data/v1/groups" \
-H "Authorization: Bearer api.example-token"
The above command returns JSON structured like this:
[
{
"id": 1,
"name": "Test group",
"areas": [1, 2, 3],
"areasV2": [
{
"id": 1,
"reversed": false
},
{
"id": 2,
"reversed": true
},
{
"id": 3,
"reversed": false
}
]
}
]
This endpoint returns all groups.
HTTP Request
GET http://example.com/api/data/v1/groups
Response structure
This endpoint returns an array of Group objects with the following structure:
| Property | Description |
|---|---|
| id | Group ID |
| name | Group name |
| areas | Array of area IDs that belong in the group. DEPRECATED: this property might be removed in future. Avoid using it in new applications. |
| areasV2 | Array of GroupArea objects (see below) |
GroupArea structure:
| Property | Description |
|---|---|
| id | Area ID |
| reversed | Whether the In and Out columns of the area data are reversed in the group. |
Query Area Data
curl "http://example.com/api/data/v1/data?areas=1&since=2021-12-22T00:00&until=2021-12-22T23:59&precision=hour" \
-H "Authorization: Bearer api.example-token"
The above command returns JSON structured like this:
{
"timestamp": [
"2021-12-22T00:00:00+02:00",
"2021-12-22T01:00:00+02:00",
"2021-12-22T04:00:00+02:00",
"2021-12-22T05:00:00+02:00",
"2021-12-22T06:00:00+02:00",
"2021-12-22T07:00:00+02:00",
"2021-12-22T08:00:00+02:00",
"2021-12-22T09:00:00+02:00",
"2021-12-22T10:00:00+02:00",
"2021-12-22T11:00:00+02:00",
"2021-12-22T12:00:00+02:00",
"2021-12-22T13:00:00+02:00",
"2021-12-22T14:00:00+02:00",
"2021-12-22T15:00:00+02:00",
"2021-12-22T16:00:00+02:00",
"2021-12-22T17:00:00+02:00",
"2021-12-22T18:00:00+02:00",
"2021-12-22T19:00:00+02:00",
"2021-12-22T20:00:00+02:00",
"2021-12-22T21:00:00+02:00",
"2021-12-22T22:00:00+02:00",
"2021-12-22T23:00:00+02:00"
],
"areas": [
{
"id": 1,
"hasPassBy": true,
"rows": [
{
"in": 91,
"out": 27,
"passBy": 28.173374
},
{
"in": 92,
"out": 34,
"passBy": 27.299702
},
{
"in": 93,
"out": 25,
"passBy": 31
},
{
"in": 91,
"out": 22,
"passBy": 25.852272
},
{
"in": 89,
"out": 40,
"passBy": 28.525642
},
{
"in": 92,
"out": 26,
"passBy": 27.218935
},
{
"in": 86,
"out": 27,
"passBy": 26.38037
},
{
"in": 83,
"out": 23,
"passBy": 25
},
{
"in": 83,
"out": 24,
"passBy": 25.776398
},
{
"in": 97,
"out": 26,
"passBy": 27.714285
},
{
"in": 84,
"out": 34,
"passBy": 26.415094
},
{
"in": 91,
"out": 25,
"passBy": 28.08642
},
{
"in": 91,
"out": 31,
"passBy": 25.633802
},
{
"in": 100,
"out": 29,
"passBy": 33.0033
},
{
"in": 101,
"out": 26,
"passBy": 29.881657
},
{
"in": 94,
"out": 33,
"passBy": 26.404493
},
{
"in": 93,
"out": 27,
"passBy": 27.844313
},
{
"in": 101,
"out": 32,
"passBy": 29.970327
},
{
"in": 82,
"out": 38,
"passBy": 24.698795
},
{
"in": 95,
"out": 33,
"passBy": 28.443113
},
{
"in": 86,
"out": 28,
"passBy": 27.831715
},
{
"in": 98,
"out": 24,
"passBy": 29.25373
}
]
}
],
"sums": {
"in": 2013,
"out": 634,
"passBy": 27.700563
}
}
This endpoint returns data for specified areas.
HTTP Request
GET http://example.com/api/data/v1/data
Required Query Parameters
| Parameter | Example | Description |
|---|---|---|
| areas | 1,2,3 | Comma-separated list of area IDs |
| since | 2020-01-01T00:00 | Timestamp in YYYY-MM-DD'T'HH:MM format since which data should be returned. In server timezone (see Get Server Information). |
| until | 2020-01-31T23:59 | Timestamp in YYYY-MM-DD'T'HH:MM format until which data should be returned. In server timezone (see Get Server Information). |
| precision | day | Data precision. Allowed values: minute, hour, day. |
Response structure
| Property | Description |
|---|---|
| timestamp | Array of RFC 3339 timestamps for each row of data. |
| areas | Array of AreaData (see below) objects for each area included in the query. |
| sums | Object with data sums |
AreaData structure:
| Property | Description |
|---|---|
| id | Area ID |
| hasPassBy | Whether the area has a pass-by counter assigned |
| rows | Data rows |
Query Group Data
curl "http://example.com/api/data/v1/data?group=1&since=2021-12-22T00:00&until=2021-12-22T23:59&precision=hour" \
-H "Authorization: Bearer api.example-token"
The above command returns JSON structured like this:
{
"timestamp": [
"2021-12-22T00:00:00+02:00",
"2021-12-22T01:00:00+02:00",
"2021-12-22T04:00:00+02:00",
"2021-12-22T05:00:00+02:00",
"2021-12-22T06:00:00+02:00",
"2021-12-22T07:00:00+02:00",
"2021-12-22T08:00:00+02:00",
"2021-12-22T09:00:00+02:00",
"2021-12-22T10:00:00+02:00",
"2021-12-22T11:00:00+02:00",
"2021-12-22T12:00:00+02:00",
"2021-12-22T13:00:00+02:00",
"2021-12-22T14:00:00+02:00",
"2021-12-22T15:00:00+02:00",
"2021-12-22T16:00:00+02:00",
"2021-12-22T17:00:00+02:00",
"2021-12-22T18:00:00+02:00",
"2021-12-22T19:00:00+02:00",
"2021-12-22T20:00:00+02:00",
"2021-12-22T21:00:00+02:00",
"2021-12-22T22:00:00+02:00",
"2021-12-22T23:00:00+02:00"
],
"groups": [
{
"id": 1,
"hasPassBy": true,
"rows": [
{
"in": 91,
"out": 27,
"passBy": 28.173374
},
{
"in": 92,
"out": 34,
"passBy": 27.299702
},
{
"in": 93,
"out": 25,
"passBy": 31
},
{
"in": 91,
"out": 22,
"passBy": 25.852272
},
{
"in": 89,
"out": 40,
"passBy": 28.525642
},
{
"in": 92,
"out": 26,
"passBy": 27.218935
},
{
"in": 86,
"out": 27,
"passBy": 26.38037
},
{
"in": 83,
"out": 23,
"passBy": 25
},
{
"in": 83,
"out": 24,
"passBy": 25.776398
},
{
"in": 97,
"out": 26,
"passBy": 27.714285
},
{
"in": 84,
"out": 34,
"passBy": 26.415094
},
{
"in": 91,
"out": 25,
"passBy": 28.08642
},
{
"in": 91,
"out": 31,
"passBy": 25.633802
},
{
"in": 100,
"out": 29,
"passBy": 33.0033
},
{
"in": 101,
"out": 26,
"passBy": 29.881657
},
{
"in": 94,
"out": 33,
"passBy": 26.404493
},
{
"in": 93,
"out": 27,
"passBy": 27.844313
},
{
"in": 101,
"out": 32,
"passBy": 29.970327
},
{
"in": 82,
"out": 38,
"passBy": 24.698795
},
{
"in": 95,
"out": 33,
"passBy": 28.443113
},
{
"in": 86,
"out": 28,
"passBy": 27.831715
},
{
"in": 98,
"out": 24,
"passBy": 29.25373
}
]
}
],
"sums": {
"in": 2013,
"out": 634,
"passBy": 27.700563
}
}
This endpoint returns data for a group.
HTTP Request
GET http://example.com/api/data/v1/data
Required Query Parameters
| Parameter | Example | Description |
|---|---|---|
| group | 1 | Group ID |
| since | 2020-01-01T00:00 | Timestamp in YYYY-MM-DD'T'HH:MM format since which data should be returned. In server timezone (see Get Server Information). |
| until | 2020-01-31T23:59 | Timestamp in YYYY-MM-DD'T'HH:MM format until which data should be returned. In server timezone (see Get Server Information). |
| precision | day | Data precision. Allowed values: minute, hour, day. |
Response structure
| Property | Description |
|---|---|
| timestamp | Array of RFC 3339 timestamps for each row of data. |
| groups | Array of one GroupData (see below) object. |
| sums | Object with data sums |
GroupData structure:
| Property | Description |
|---|---|
| id | Group ID |
| hasPassBy | Whether the group has an area with a pass-by counter assigned |
| rows | Data rows |