Urban Observatory API: Urban Sciences Building API Reference
The Urban Observatory represents the largest open platform of urban sensing data in the United Kingdom. The updated API is currently in operation for the Urban Sciences Building and some of the newer data sources across the city. It is anticipated that this schema, once complete, will replace the existing API.
For more information...
You can also download this specification in OpenAPI format.
API Endpoint
https://api.usb.urbanobservatory.ac.uk/api/v2.0a
Contact: luke.smith@ncl.ac.uk
Request Content-Types: application/json
Response Content-Types: application/json, text/csv
Schemes: https
Version: 2.0a
Entity
An entity ordinarily describes a spatial location, such as a room in a building, or a pole in the street. In some circumstances, an entity may be a mobile piece of equipment, such as those used for validation, in which case the location will be provided as a timeseries.
List all entities (paginated)
Paginated list of all entities, including their associated feeds and timeseries.
Page number to return results from, will default to 1
if omitted.
Request a number of items per page, however the API may constrain the range.
Filter based on metadata, e.g. meta:roomNumber=2.048
Filter based on the ID at the source controller or broker, such as the BACNET ID within a building. This is usually useful if you have some prior knowledge of the systems, or are using the data in combination with related data sources. Note that source IDs are not required to confirm to any standard, other than the controller ID and source ID combined must be a unique pair.
Filter to only include entities with, and feeds therein, matching at least one of the metrics specified. Partial matches on metrics are included, and each word is considered to be additive and case insensitive, so phrases must be surrounded by double quotes. For example, to return the occupancy and room temperature, but exclude flow temperatures, use metric=occupied+"room temperature"
.
Successful request
Response Example (200 OK)
{
"pagination": {
"pageNumber": 1,
"pageSize": 10,
"pageCount": 1,
"total": 1
},
"items": [
{
"entityId": "e33f9ed0-cb60-4326-8ea6-4f166dd0c767",
"name": "Urban Sciences Building: Floor 2: Room 2.048 Zone 1",
"meta": {
"building": "Urban Sciences Building",
"roomZone": "1",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"position": [],
"feed": [
{
"feedId": "eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"metric": "Room temperature",
"meta": {
"building": "Urban Sciences Building",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"provider": {
"providerId": "986cd257-b50d-4fe8-8439-dc2a69271172",
"organisation": {
"organisationId": "2567c616-43f3-4b6b-930b-126ba9ad51c8",
"name": "Urban Observatory",
"url": "http://www.urbanobservatory.ac.uk/",
"privateSector": false
},
"contact": {
"contactId": "19c2aabb-33d0-47f1-a4f5-3fbfe3c7bcf0",
"name": "Urban Observatory",
"email": "urbanobservatory@ncl.ac.uk",
"phone": "0191 208 8599"
},
"licence": {
"licenceId": "1629fceb-799b-4840-8f5b-8b8612b374c9",
"name": "Urban Observatory: Ethical approval required",
"url": "http://www.urbanobservatory.ac.uk/",
"description": {
"open": false
}
}
},
"technology": null,
"hardware": null,
"service": [],
"timeseries": [
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
],
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/feed/eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"rel": "self"
}
]
}
]
}
]
}
Request a single entity by its unique ID
A single entity and its associated feeds will be returned, if a valid ID is supplied and permissions permit.
(no description)
Successful request
Bad request
Response Example (200 OK)
{
"entityId": "e33f9ed0-cb60-4326-8ea6-4f166dd0c767",
"name": "Urban Sciences Building: Floor 2: Room 2.048 Zone 1",
"meta": {
"building": "Urban Sciences Building",
"roomZone": "1",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"position": [],
"feed": [
{
"feedId": "eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"metric": "Room temperature",
"meta": {
"building": "Urban Sciences Building",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"provider": {
"providerId": "986cd257-b50d-4fe8-8439-dc2a69271172",
"organisation": {
"organisationId": "2567c616-43f3-4b6b-930b-126ba9ad51c8",
"name": "Urban Observatory",
"url": "http://www.urbanobservatory.ac.uk/",
"privateSector": false
},
"contact": {
"contactId": "19c2aabb-33d0-47f1-a4f5-3fbfe3c7bcf0",
"name": "Urban Observatory",
"email": "urbanobservatory@ncl.ac.uk",
"phone": "0191 208 8599"
},
"licence": {
"licenceId": "1629fceb-799b-4840-8f5b-8b8612b374c9",
"name": "Urban Observatory: Ethical approval required",
"url": "http://www.urbanobservatory.ac.uk/",
"description": {
"open": false
}
}
},
"technology": null,
"hardware": null,
"service": [],
"timeseries": [
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
],
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/feed/eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"rel": "self"
}
]
}
]
}
Response Example (400 Bad Request)
{
"error": true,
"message": "Malformed UUID cannot be used.",
"code": "MalformedUUID"
}
Feed
A feed is a representation of a measurement or parametrisation, usually a metric, for example the observed temperature.
Request a single feed by its unique ID
A single feed and its descendant timeseries will be returned.
Feed ID to retrieve description and associated set of timeseries for.
Successful request
Bad request
Response Example (200 OK)
{
"feedId": "eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"metric": "Room temperature",
"meta": {
"building": "Urban Sciences Building",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"provider": {
"providerId": "986cd257-b50d-4fe8-8439-dc2a69271172",
"organisation": {
"organisationId": "2567c616-43f3-4b6b-930b-126ba9ad51c8",
"name": "Urban Observatory",
"url": "http://www.urbanobservatory.ac.uk/",
"privateSector": false
},
"contact": {
"contactId": "19c2aabb-33d0-47f1-a4f5-3fbfe3c7bcf0",
"name": "Urban Observatory",
"email": "urbanobservatory@ncl.ac.uk",
"phone": "0191 208 8599"
},
"licence": {
"licenceId": "1629fceb-799b-4840-8f5b-8b8612b374c9",
"name": "Urban Observatory: Ethical approval required",
"url": "http://www.urbanobservatory.ac.uk/",
"description": {
"open": false
}
}
},
"technology": null,
"hardware": null,
"service": [],
"timeseries": [
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
],
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/feed/eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"rel": "self"
}
]
}
Response Example (400 Bad Request)
{
"error": true,
"message": "Malformed UUID cannot be used.",
"code": "MalformedUUID"
}
Timeseries
There may be more than one timeseries associated with a feed, provided for convenience. Ordinarily there will be a plain timeseries, representing raw data from the device. In some cases, there may then be additional timeseries representing converted values (e.g. scaled), corrected, or aggregated temporally.
Request a single timeseries by its unique ID
A single timeseries and its current value will be returned, if recent, provided a valid ID is supplied and permissions permit.
Timeseries ID to retrieve description and latest observed value for.
Successful request
Bad request
Response Example (200 OK)
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
Response Example (400 Bad Request)
{
"error": true,
"message": "Malformed UUID cannot be used.",
"code": "MalformedUUID"
}
Request historic data from a timeseries by its unique ID and a date range
A date range may be specified to obtain historic readings from a timeseries, or the last 24 hours will be provided by default.
Timeseries ID to retrieve historic data for.
Start period for the historic data to be retrieved, inclusive.
End period for the historic data to be retrieved, inclusive.
Output format for the data, although JSON is always recommended and CSV outputs are computed from JSON.
Successful request
Bad request
Forbidden
Response Example (200 OK)
{
"timeseries": {
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
},
"historic": {
"startTime": "2018-02-11T10:31:04.065Z",
"endTime": "2018-02-13T10:31:04.065Z",
"limited": false,
"values": [
{
"time": "2018-02-12T10:30:40.125Z",
"duration": -4.284,
"value": 3.23809
},
{
"time": "2018-02-12T10:30:08.269Z",
"duration": -4.386,
"value": 3.31608
}
]
}
}
Response Example (400 Bad Request)
{
"error": true,
"message": "Malformed UUID cannot be used.",
"code": "MalformedUUID"
}
Response Example (403 Forbidden)
{
"error": true,
"message": "No access to this timeseries.",
"code": "ForbiddenError"
}
Summary
List all entities in summary form
Non-paginated list of all entities, with only basic information provided.
Successful request
Response Example (200 OK)
{
"entityId": "970d26c6-37c3-49e4-b2f8-00db042ac3eb",
"name": "Urban Sciences Building: Floor 2: Room 2.048 Zone 1",
"feed": {
"87b2d34e-b96e-44c1-ae69-374f4bac02cd": "Room Temperature"
}
}
Schema Definitions
Pagination: object
The pagination associated with the response, and data concerning the total number of items and pages.
- pageNumber: number
-
Index of the page returned by the request.
- pageSize: number
-
Number of items per page to be returned.
- pageCount: number
-
Total number of pages available.
- total: number
-
Total number of items available, after any filtering has been applied.
Example
{
"pageNumber": 1,
"pageSize": 10,
"pageCount": 1,
"total": 1
}
BadRequest: object
An invalid ID or query parameter was used to request information, such as an ID not in the UUID syntax.
- error: boolean
-
Indicator that an error was returned.
- message: string
-
Description of the error which occurred in friendly terms.
- code: string MalformedUUID, BadRequestError
-
A short description of the error, for use in code.
Example
{
"error": true,
"message": "Malformed UUID cannot be used.",
"code": "MalformedUUID"
}
Forbidden: object
The requested data could not be returned, because permissions do not permit.
- error: boolean
-
Indicator that an error was returned.
- message: string
-
Description of the error which occurred in friendly terms.
- code: string ForbiddenError
-
A short description of the error, for use in code.
Example
{
"error": true,
"message": "No access to this timeseries.",
"code": "ForbiddenError"
}
Link: object
A link provided for HATEOAS purposes, to the item itself or an associated API method.
- rel: string
-
The relation of the URL to the entity in the API, which will be taken from this list where possible, but non-standard relations are permitted.
- href: string
-
An absolute URL for the resource.
- method: string GET, POST, PATCH, PUT, DELETE GET
-
The HTTP protocol method to be used, or
GET
if not specified.
Example
{
"rel": "self",
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2/historic"
}
Organisation: object
An organisation which is providing the data to the Urban Observatory, or responsible for some element.
- organisationId: string (uuid)
-
A unique identifier associated with the organisation.
- name: string
-
The name of the organisation, which may be a subsidiary of the legal entity, e.g. Urban Observatory.
- url: string
-
A URL for the organisation's web page.
- privateSector: boolean
-
Indication of whether the organisation is public or private sector.
Example
{
"organisationId": "2567c616-43f3-4b6b-930b-126ba9ad51c8",
"name": "Urban Observatory",
"url": "http://www.urbanobservatory.ac.uk/",
"privateSector": false
}
Contact: object
The contact for more information, or technical issues relating to the sensing. This may not always be available.
- contactId: string (uuid)
-
A unique identifier associated with the contact.
- name: string
-
An individual's name, or an indication of shared contact details
- email: string
-
An email address to contact.
- phone: string
-
A telephone number to use, which may not always be available.
Example
{
"contactId": "19c2aabb-33d0-47f1-a4f5-3fbfe3c7bcf0",
"name": "Urban Observatory",
"email": "urbanobservatory@ncl.ac.uk",
"phone": "0191 208 8599"
}
Licence: object
- licenceId: string (uuid)
-
A unique identifier associated with the licence.
- name: string
-
The name for the licence, e.g. Open Government Licence v3.
- url: string
-
A URL for the licence, or where more information can be obtained, such as the procedure for approval to use the data.
- description: object
-
A data-based description of the licence, such as the constraints which may be in place, e.g.
open: false
.
Example
{
"licenceId": "1629fceb-799b-4840-8f5b-8b8612b374c9",
"name": "Urban Observatory: Ethical approval required",
"url": "http://www.urbanobservatory.ac.uk/",
"description": {
"open": false
}
}
Storage: object
The storage mechanism used to hold the data internally.
- unitId: string (uuid)
-
A unique identifier for the storage used for this data within the internal systems.
- name: string
-
A name for the storage, usually those used in programming (e.g. real, integer)
- suffix: string
-
The suffix used for data storage in the internal systems.
Example
{
"storageId": 3,
"name": "Real",
"suffix": "real"
}
Unit: object
The units associated with the values held in the timeseries.
- unitId: string (uuid)
-
A unique identifier for the units associated with timeseries.
- name: string
-
A friendly description for the units used.
Example
{
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
}
Entity: object
- entityId: string
-
A unique identifier associated with this entity.
- name: string
-
Friendly name associated with the entity, not used internally.
- meta: object
-
Metadata associated with the entity, such as room numbers or building name.
- position: array
- feed: Feed
Example
{
"entityId": "e33f9ed0-cb60-4326-8ea6-4f166dd0c767",
"name": "Urban Sciences Building: Floor 2: Room 2.048 Zone 1",
"meta": {
"building": "Urban Sciences Building",
"roomZone": "1",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"position": [],
"feed": [
{
"feedId": "eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"metric": "Room temperature",
"meta": {
"building": "Urban Sciences Building",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"provider": {
"providerId": "986cd257-b50d-4fe8-8439-dc2a69271172",
"organisation": {
"organisationId": "2567c616-43f3-4b6b-930b-126ba9ad51c8",
"name": "Urban Observatory",
"url": "http://www.urbanobservatory.ac.uk/",
"privateSector": false
},
"contact": {
"contactId": "19c2aabb-33d0-47f1-a4f5-3fbfe3c7bcf0",
"name": "Urban Observatory",
"email": "urbanobservatory@ncl.ac.uk",
"phone": "0191 208 8599"
},
"licence": {
"licenceId": "1629fceb-799b-4840-8f5b-8b8612b374c9",
"name": "Urban Observatory: Ethical approval required",
"url": "http://www.urbanobservatory.ac.uk/",
"description": {
"open": false
}
}
},
"technology": null,
"hardware": null,
"service": [],
"timeseries": [
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
],
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/feed/eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"rel": "self"
}
]
}
]
}
Feed: object
- feedId: string (uuid)
-
A unique identifier associated with this feed.
- metric: string
-
A short description for the metric represented, e.g. Room temperature.
- meta: object
-
Metadata associated with the feed, such as the room number or floor.
- provider: object
-
A description of the organisation or person providing the data, and the licence under which it is provided.
- technology: object
-
Placeholder for future information.
- hardware: object
-
Placeholder for future information.
- service: array
-
Placeholder for future information.
- timeseries: Timeseries
Example
{
"feedId": "eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"metric": "Room temperature",
"meta": {
"building": "Urban Sciences Building",
"roomNumber": "2.048",
"buildingFloor": "2"
},
"provider": {
"providerId": "986cd257-b50d-4fe8-8439-dc2a69271172",
"organisation": {
"organisationId": "2567c616-43f3-4b6b-930b-126ba9ad51c8",
"name": "Urban Observatory",
"url": "http://www.urbanobservatory.ac.uk/",
"privateSector": false
},
"contact": {
"contactId": "19c2aabb-33d0-47f1-a4f5-3fbfe3c7bcf0",
"name": "Urban Observatory",
"email": "urbanobservatory@ncl.ac.uk",
"phone": "0191 208 8599"
},
"licence": {
"licenceId": "1629fceb-799b-4840-8f5b-8b8612b374c9",
"name": "Urban Observatory: Ethical approval required",
"url": "http://www.urbanobservatory.ac.uk/",
"description": {
"open": false
}
}
},
"technology": null,
"hardware": null,
"service": [],
"timeseries": [
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
],
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/feed/eeaa50bb-fb5f-47be-a6ab-eb4c67debecb",
"rel": "self"
}
]
}
Timeseries: object
- timeseriesId: string (uuid)
-
A unique identifier associated with this timeseries.
- unit: Unit
- storage: Storage
- derivatives: array
-
Placeholder for future use.
- aggregation: array
-
Placeholder for future use.
- assessments: array
-
Placeholder for future use.
- latest: TimeseriesEntry
-
The most recent timeseries entry, only shown if within the last week, and a historic range has not been requested. Code must be resilient if
latest
is omitted from a timeseries. - links: Link
Example
{
"timeseriesId": "371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"unit": {
"unitId": "19bc95ba-83f2-4dcd-b49e-5e5415c75771",
"name": "amperes"
},
"storage": {
"storageId": 3,
"name": "Real",
"suffix": "real"
},
"derivatives": [],
"aggregation": [],
"assessments": [],
"latest": {
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
},
"links": [
{
"href": "https://api.usb.urbanobservatory.ac.uk/api/v2.0a/sensors/timeseries/371fbff8-f61d-4f66-99be-7d9de8ad51f2",
"rel": "self"
}
]
}
TimeseriesEntry: object
A historic entry associated with a timeseries and a time.
- time: string (date-time)
-
Date and time associated with the historic value
- duration: number
-
The duration this value applies to, or if negative, the window of error in which the value change could have occurred.
- value: any
-
The value associated with the time in the timeseries, unless the timeseries does not contain values (i.e. event only).
- error: boolean
-
Indication that an error occurred, and data could not be supplied.
- message: string
-
Short description of why data could not be supplied.
- description: string
-
Verbose description of why an error occurred and data could not be supplied.
Example
{
"time": "2018-02-12T10:30:40.125Z",
"duration": -2.1,
"value": 3.5
}
EntitySummary: object
- entityId: string
-
A unique identifier associated with this entity.
- name: string
-
Friendly name associated with the entity, not used internally.
- feed: object
-
A direct mapping of feed IDs to their respective metrics, with all other data omitted.
Example
{
"entityId": "970d26c6-37c3-49e4-b2f8-00db042ac3eb",
"name": "Urban Sciences Building: Floor 2: Room 2.048 Zone 1",
"feed": {
"87b2d34e-b96e-44c1-ae69-374f4bac02cd": "Room Temperature"
}
}