Welcome × Home Update Profile Reset Password Terms & Conditions Request an API Key Leave the Platform

CityVerver Developer Portal

The API

Despite housing a wide variety of data, the CityVerve API is itself structurally very simple and easy to use. In this section, we will explain the API in detail and show you how you could use create apps that use CityVerve data. In addition to this formal API document, you can also read:

  • Our Getting Started guide, with step-by-step instructions on how to get up and running with the API.
  • Our API Showcase where you will find a bunch of samples, examples and tutorials. All designed to take the pain out of getting your first app up and running.

This API documentation is currently work in progress and BETA quality only.

Background and Design

In order to make it as easy as possible to use, we've designed the CityVerve API to have a very light and simple format. In practical terms, that means that you will only need to write one set of code to be able to address all the variety of data that is available on the platform. So, for example, once you've written some code to work with traffic-signals, that code will also work with air-quality sensors. If you reading a time series from a noise-meter, it's the same mechanism for reading the time series of buses leaving a bus-stop.

A design goal of the API design was that new data should not need new structure, as this in turn would lead to a burden of new code. Also, we really want users to mash-up data from lots of different areas in order to find useful overlaps. So hence another key design goal was to keep a consistent structure across all our different datasets.

We have constructed the API around industry recognised standards and practises for things like access control, resource definition, URL parameters, data exchange formats, data types, etc. The API is a middle-of-the-road RESTful design that will be instantly recognisable to people who are already familiar with using Web APIs. Expect no surprises, specialities or quirks here!

Finally, we love to share and hence you will find lots of working sample code in our GitHub repos. You can use these samples to kick-start your application and, best of all, its all free to use with an open license.

Within this document, you will find several notes inserts in different colours. These colours each have a specific meaning as defined below:

Notes which outline some details about how the API is described within this document.

Important general or foundational points about the API.

Work-to-do or work-in-progress portions of this document.

Protocol

All access to the API (and this Developer Portal) is via HTTPS protocol only.

Versioning

You should note that the current version of the API is marked as 'v1'.

https://api.cityverve.org.uk/v1

Across the API, the version is included directly into the leading edge of the URL. This is inline with industry practices.

Legalities

Each type of data that you access via the API may come with specific legal characteristics which you should respect. This is in addition to the Terms and Conditions which you will need to accept before being given a key to access the API. These legal characteristics consists of categories such as these:

  • license - The legal context in which the data is allowed to be accessed, used and/or shared.
  • terms - Specific terms of use which users of the data are expected to respect.
  • contact - The contact point for all legal questions and clarifications.
  • attribution - The legal owner of the data.

Other legal categories may emerge over time.

You should expect to see zero, one or many of each of these categories present for every entity within the API. Here is an example of the legal structure in the format in which it will be present in returned documents:

{ other-data: "goes-here", legal: [ { type: "license", name: "Open Licence EU", link: "https://foo.com/abc" }, { type: "license", name: "Restrictive Use 12", link: "https://foo.com/cde" }, { type: "terms", name: "Terms and Conditions", link: "https://foo.com/fgh" }, { type: "terms", name: "Fair Use", link: "https://foo.com/hij" }, { type: "contact", name: "Miss Admin Person", link: "https://foo.com/klm" }, { type: "attribution", name: "Big Company Inc", link: "https://foo.com/nop" } ] }

There will always be a license property for entities returned by the API, but where there is no declarations to be made, it will be empty array:

{ other-data: "goes-here", legal: [ ] }

For clarity, the "legal" property will not be shown on the examples within this document.

Elements of the API

There are three separate and distinct elements to the CityVerve API. Each element is designed to answer a specific class of question. The three structural elements operate the same for all the different types of data that they range over. So, for example, they operate the same for air-quality as they do for bus-stops. The three elements are as follows:

  • The Catalogue - finding things

    • What is this street light I am standing next to?
    • Which buses go down this road?
    • Find me sensors that can measure humidity within this bounding box
  • Entities - properties of things

    • Does this bus stop have a shelter?
    • How many free spaces are there in this car park?
    • Who manufactured this air quality sensor?
  • Time (Space) Series - data from things

    • Give me the latest air quality reading
    • Show me all todays values over 30°C
    • Return last month's values between 70db and 90db

The examples above are written in English languages sentences, but in the actual API these are expressed via calls over a RESTful interface.

The reason "space" is present in "Time (Space) Series" is to account for the fact that some time series delivering sensors may be not fixed in space (i.e. they may be mounted on top of a moving vehicle, such as a tram). In a strict sense, the Time Series API always returns [space-time, value] pairs but in the majority of cases the space portion is a fixed, non-moving point.

All three elements of the CityVerve API work together and reference each other. Typically, you would use the catalogue to find an entity which has the profile you are looking for. That will hand you off to an entity that will have domain specific properties which you can inspect. Finally, some entities will have time series from which you extract time-value pair data points.

So, for example, you can use the Catalogue API to find an air-quality sensor. Then inspect it properties, such as its manufacturer, using the Entity API. Then read its data points via the Time Series API.

The Catalogue API

As outlined earlier, the catalogue portion of the API is used to locate "things". The catalogue fulfils the same role as an old style telephone directory. Given you are trying to find something with certain capabilities or properties (including often it's location), the catalogue will help locate the entities that fulfil your criteria and provide you with a contact point to allow you to "talk" to them.

Here are some examples of the types of questions you can ask of the catalogue.

  • Find all schools
  • Find all high schools
  • Find all high schools that have an Outstanding rating
  • Find something that can measure noise
  • Find something that can measure noise within this bounding box
  • Find something that can measure noise within this bounding box from a given manufacturer
  • Find bus stops that are on this road
  • What is this bus stop I am standing next to
  • Find buses that pass through this bus stop

The examples above are written in English languages sentences, but in the actual API these are expressed via calls over a RESTful interface.

Hypercat

Within the CityVerve API, the cataloguing technology that we use is called HyperCat. HyperCat is an existing specification which is designed to provide automatic resource discovery for the Internet of Things. The key design goal of HyperCat is to "provide interoperability over entities and/or services for discoverability". Hence it is very aligned to the goals of our API.

The version of HyperCat which we use is formally defined as BSI PAS 212:2016.

It is certain beyond the scope of this document to formally (re)document all the features of HyperCat. We strongly encourage you to read the specification and use that to understand HyperCat and its capabilities in more detail. However, for completeness we have documented the main elements of the catalogue API here.

If you want to get practical hands on experience of HyperCat, try our HyperCat client demo app in the Showcase section of this site.

The master catalogue is accessible from the cat endpoint. When called in this way, without any further parameters, it always returns the full catalogue of all the entities it knows:

GEThttps://api.cityverve.org.uk/v1/cat

{ catalogue-metadata: [ { rel: "urn:X-hypercat:rels:isContentType", val: "application/vnd.hypercat.catalogue+json" }, { rel: "urn:X-hypercat:rels:hasDescription:en", val: "CityVerve Public API - blue-plaque catalogue" }, { rel: "urn:X-hypercat:rels:hasHomepage", val: "https://developer.cityverve.org.uk" }, { rel: "urn:X-hypercat:rels:supportsSearch", val: "urn:X-hypercat:search:simple" } ], items: [ { href: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-1", item-metadata: [ { rel: "urn:X-cityverve:rels:entity.recipient", val: "Dame Isobel Baillie (1895 - 1983)" }, { rel: "urn:X-hypercat:rels:id", val: "bp-1" }, { rel: "http://www.w3.org/2003/01/geo/wgs84_pos#lat", val: -2.266539 }, { rel: "http://www.w3.org/2003/01/geo/wgs84_pos#long", val: 53.464045 }, { rel: "urn:X-cityverve:rels:name", val: "Dame Isobel Baillie" }, { rel: "urn:X-cityverve:rels:type", val: "blue-plaque" } ] }, { href: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-2", item-metadata: [ { rel: "urn:X-cityverve:rels:entity.recipient", val: "Superintendent James Bent" }, { rel: "urn:X-hypercat:rels:id", val: "bp-2" }, { rel: "http://www.w3.org/2003/01/geo/wgs84_pos#lat", val: -2.266864 }, { rel: "http://www.w3.org/2003/01/geo/wgs84_pos#long", val: 53.4641 }, { rel: "urn:X-cityverve:rels:name", val: "Superintendent James Bent" }, { rel: "urn:X-cityverve:rels:type", val: "blue-plaque" } ] } ] }

This JSON document consists of the following main sections:

Section Description
catalogue-metadata High level information about the catalogue entries
items An array of the actual specific catalogue entries

Within the items section, each entry consists of:

Section Description
href A fully qualified URL to the entity in question
item-metadata An array of key/value pairs describing key properties of the entity

Within each item-metadata entry, the parts consists of:

Section Description
rel The key part of the key/value pair
val The val part of the key/value pair

The example above, shows a simple catalogue consisting of two blue-plaques along with their corresponding key/value metadata items.

In the United Kingdom, a blue plaque is a permanent sign installed in a public place to commemorate a link between that location and a famous person or event, serving as a historical marker.

HyperCat allows for the concept of hierarchical catalogues, that is catalogues that contain other catalogues.

Within CityVerve each entity type presents a separate and distinct catalogue. The master CityVerve catalogue is a catalogue of these lower entity catalogues.

A full catalogue is comprehensive, but not too helpful in its own right. A more useful feature is to search a catalogue to look for entities that match some specific criteria. This is easily achieved within HyperCat through a series of standardised URL parameters. Different HyperCat catalogues support different type of metadata searches. The exact list of search capabilities is listed in the catalogue-metadata section of the catalogue. The full range of searches that may be supported are:

Search Type Description
Simple A full string search on rel or val
Prefix A string search on the leading part of rel or val
LexRange A range search on rel or val that have a logical order
GeoBound A geographical search on entries that have a long and lat
Multi A technique for combining the above searches into expressions with Boolean operators

Different entity catalogues will support different search semantics. You will need to examine the catalogue-metadata section to see which search types are supported.

Hypercat Search Examples

Here are some examples of HyperCat searches in action:

Searching a catalogue for entities

https://api.cityverve.org.uk/v1/cat/polling-station?rel=entity.ward&val=Irwell%20Riverside

polling-stations in the ward 'Irwell Riverside'

Searching a catalogue for entities via a prefix

https://api.cityverve.org.uk/v1/cat/polling-station?prefix-rel=entity.ward&prefix-val=Swinton

polling-stations where the ward starts with 'Swinton'

Searching a catalogue for a entities via a lexical range match

https://api.cityverve.org.uk/v1/cat/cycle-hub?rel=entity.capacity&val=39

cycle-hubs with a capacity of exactly 39

https://api.cityverve.org.uk/v1/cat/cycle-hub?lexrange-rel=entity.capacity&lexrange-min=99

cycle-hubs with a capacity of at least 100

Searching a catalogue entities via a geographical bounding box

https://api.cityverve.org.uk/v1/cat/history?geobound-minlong=-2.35&geobound-minlat=53.36&geobound-maxlong=-2.67&geobound-maxlat=54.38

history events that took place in the geo box

The Entity API

The entity API provides data about "things" within the domain being modelled. As a rule-of-thumb, anything which is a noun within the domain space is probably an entity within the system. Examples of entities within CityVerve are car-parks, tram, schools, traffic-lights, air-quality-sensorss, etc.

There are several ways to find an entity (or type of entity) that you are interested in. For example, lets imagine that you are looking for information about car-parks in a given area. You can, of course, query the catalogue and ask it to locate car-parks of a given class within a given geographical bound. Alternatively, you can ask the entity API to list out all car-parks that are known along with their name and location. Finally, if you know the car-park ID, you can go directly to the document that describes the properties of that specific car-park.

Obtaining a List of All Known Entity Types

There is a simple way to get the list of all entity types that the CityVerve API currently services. The endpoint below will return a JSON list of all such entity types.

GEThttps://api.cityverve.org.uk/v1/entity

The entity types presented in this documents are not necessarily those which are available through the live public API. Indeed a much richer set is available from the live service. Please issue a GET on the end-point described above to get the definitive list of live entity types.

Entity types are always in a single flat list that contains not explicit hierarchy.

This endpoint returns a list of entity types expressed as both ids and as fully qualified URIs.

All IDs in the API throughout the API are always also expressed as fully qualified URIs which can be "cashed in" directly as RESTful endpoints to obtain their corresponding datasets.

Constants, keys and enumerations within the API are always expressed in lower case, using dashes-for-spaces and in the singular context.

Obtaining a List of All Known Instances of a Given Entity Type

Once you know the entity type that you are interested in, you can then go on to obtain a list of all known instances of that entity type within the system.

GEThttps://api.cityverve.org.uk/v1/entity/blue-plaque

[ { id: "bp-1", uri: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-1", name: "Dame Isobel Baillie (1895 - 1983)", loc: { type: "Point", coordinates: [ -2.266539, 53.464045 ] } }, { id: "bp-6", uri: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-6", name: "Duncan Edwards (1936 - 1958)", type: "blue-plaque", loc: { type: "Point", coordinates: [ -2.290923, 53.454151 ] } }, { id: "bp-3", uri: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-3", name: "James Gibson (1877 - 1951)", loc: { type: "Point", coordinates: [ -2.283981, 53.4649 ] } }, { id: "bp-3", uri: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-3", name: "L S Lowry (1887 - 1976)", loc: { type: "Point", coordinates: [ -2.26344, 53.461617 ] } } ]

In this example, we have asked for a list of all instances of the entity type blue-plaque.

In the United Kingdom, a blue plaque is a permanent sign installed in a public place to commemorate a link between that location and a famous person or event, serving as a historical marker.)

The data returned by this request contains the IDs of all instances of the given type, along with other key information that will be of use to the caller. The data that is guaranteed to be returned for all instances and in all entity documents is called the The Global Guarantee which is documented later in this section. This subset of data is designed to be sufficient to allow the instances to be placed into a selectable list or overlaid as pins onto a map.

Do make sure to read the note below on handling long lists of entities, otherwise you might miss some entities in your code.

In order to limit the amount of code that needs to be written to handle the diversity of data sets within the platform, the structure of the returned document shown in this example is guaranteed to be the same for all requests irrespective of the entity type. For example, the request below is for a different entity type (history), but you will observe that the data structure returned is consistent with the first example.

GEThttps://api.cityverve.org.uk/v1/entity/history

[ { id: "history-453", uri: "https://api.cityverve.org.uk/v1/entity/history/history-453", name: "The rebel army of Charles Edward Stuart enters Manchester", loc: { type: "Point", coordinates: [ -2.2311, 53.4166 ] } }, { id: "history-675", uri: "https://api.cityverve.org.uk/v1/entity/history/history-675", name: "First match played at the City of Manchester Stadium", loc: { type: "Point", coordinates: [ -2.235278, 53.451111 ] } }, { id: "history-768", uri: "https://api.cityverve.org.uk/v1/entity/history/history-768", name: "BBC Radio Manchester opens as a local station)", loc: { type: "Point", coordinates: [ -2.289, 53.479 ] } } ]

The geographical location returned in this document is a standards compliant GeoJSON structure. Within the CityVerve API we can guarantee that ALL geographical locations will be GeoJSON complaint. This is part of a wider set of guarantees that the system offers to users in order to limit the amount of code that they need to implement. For more information you can see the Data Type Guarantee section of this document.

Handling Long Lists of Entity Instances

When you ask for a list of instances of an entity type, the API may return you paged results. This is because, for some entity types, the complete list could be huge and result in massive documents, delayed downloads and (possibly) time-outs.

The current paging point for entity lists (and time series data points) is 250 items. This is the maximum you will see in a single document. For more items, you will need to use the paging URL parameters below.

When paged results are returned, you will need to make more than one call to get the full list (perhaps you really want to do a search using The Catalogue API). In order to obtain more items, you can use two optional URL parameters which divide the list into small sets:

Param Description
limit the maximum count of the instances you want returned
offset the index of the first instance that you want returned

These parameters can be used on their own or in concert. Here are some examples uses of these URL parameters:

GEThttps://api.cityverve.org.uk/v1/entity/blue-plaque

The list of all instances of blue-plaques

GEThttps://api.cityverve.org.uk/v1/entity/blue-plaque?limit=10

The list of the first 10 instances of blue-plaques

GEThttps://api.cityverve.org.uk/v1/entity/blue-plaque?offset=12

The list of all instances of blue-plaques but not including the first 12

GEThttps://api.cityverve.org.uk/v1/entity/blue-plaque?offset=12&limit=10

The list of the instances 12 through to 22 of blue-plaques

Error Scenarios

The entity types known to the system is a fixed list that does not change too often. Changes (mostly additions) will be well signalled to the developer community via the developer portal. Hence, asking for data for an entity type that the system does not recognise, is classed as a bad request rather than missing data.

GEThttps://api.cityverve.org.uk/v1/entity/foo-bar

HTTP/400 - Bad Request
Obtaining Information About a Specific Entity

Once you know the specific entity instance that you are interested in, you can then go on to obtain all the data that the system knows about that entity instance.

GEThttps://api.cityverve.org.uk/v1/entity/blue-plaque/bp-4

[ { id: "bp-4", uri: "https://api.cityverve.org.uk/v1/entity/blue-plaque/bp-4", name: "L S Lowry (1887 - 1976)", type: "blue-plaque", loc: { type: "Point", coordinates: [ -2.26344, 53.461617 ] }, entity: { recipient: "L S Lowry (1887 - 1976)", location: "Old Trafford Community Centre", date-erected: "2001", reference: "http://en.wikipedia.org/wiki/L._S._Lowry", text: "Lowry was an internationally acclaimed artist. He was born at 8 Barrett Street in Stretford on the 1st November 1887. Barrett Street ran north westwards from Cross Street to Hullard Street." }, instance: { maintenance: "Cleaned Nov 17th" } } ]

Let’s take a moment to go through this data document in detail. As we have said earlier, the structural elements of the CityVerve API are deliberately limited, so understanding the structure of this one data document will help with all entity documents delivered by the system.

Entities are always returned within an array BUT in the vast majority of cases, this will have only have one item in it. In some rare cases, there could be more than one item. This only happens when there is a data conflict in the back-end systems that supply the source data. You are free to ignore this rare occurrence and, instead, always address the first item of the returned array.

The API Guarantees

In order to maximise certainty and interoperability to developers, the API offers a series of guarantees to its callers. These are in three critical areas.

The Data Type Guarantee

Across the CityVerve API, the JSON keys have been carefully chosen such that users can have firm expectations of the type and availability of the corresponding data values.

Key Description Value
id The globally unique ID for an entity instance A non-empty string
uri The full API endpoint for this entity instance A non-empty fully qualified URI as a string
name A human readable name for an entity instance A non-empty string
type The type of an entity instance The enumeration returned by the /entity endpoint
location The geographical location of an entity instance A GeoJSON structure. If no location is relevant in the context of an entity, you may see here a GeoJSON structure of type POINT but with an empty array of points.
date and/or time Temporal values such as dates, times or dates with times An ISO 8601 compliant time date and/or time
duration Temporal duration such as minutes, days, weeks, etc An ISO 8601 compliant duration

Generally, data returned from the API will always be offered in its most computable form. If you come across data that you think could be presented in a better form (or data that does not match our guarantees) then do get in touch to let us know.

The Global Guarantee

At the top of this document you will find a set of data, some of which was also present in the entity instance list described earlier. Specifically, the ID, name and geographical location. In addition to this, we see here added some legal information such as licenses and attribution. Together this part of the document forms what we call The Global Guarantee.

Key Description Key Present Value
id The globally unique ID for the entity instance always A non empty string
uri The full API endpoint for this entity instance always A non empty fully qualified URI as a string
name A human readable name for the entity instance always A non-empty string
type sdfsd always
loc location always GeoJSON

The Global Guarantee is a set of data which is guaranteed to be present for ALL entities within the system. If forms the fundamental set of data which users can expect to be globally present.

[ { id: "<a non-empty, entity unique id>", uri: "<a non-empty, entity uri to te api endpoint>", name: "<a non-empty, human readable name>", type: "<the corresponding entity type>", loc: { type: "Point", coordinates: [ "<the latititude if relevant, else empty>", "<the longititude if relevant, else empty>" ] }, entity: { }, instance: { } } ]

A more detailed breakdown of The Global Guarantee can be found over on The Data pages.

The Entity Guarantee

Within the returned document you will see a section with the key "entity", which is where all the entity specific information resides. It is likely that he user made their request in order to specifically extract information from the entity section. Every entity document returned by the API will have an entity section but different entity types will return different values in this section.

An important point is that the API provides guarantees about the data that you will find within the entity section for a given entity type. This is what we call The Entity Guarantee. For example, in the blue-plaques document above we see that the following data is present in the entity section: recipient, location, date-erected, reference and text. These form the entity guarantee for blue-plaques. Users can expect that this data will be present for ALL blue plaques in the system; even if the data is sourced from multiple, different systems. This guarantee means that one implementation for a given entity type will be sufficient for all instances of that type.

You can find The Entity Guarantee for blue-plaques formally documented here.

Entity Guarantees are only WITHIN a given entity type. Hence, different entity types have different guarantees. For example, the entity section for "history" entities is different from that of "blue-plaques".

[ { id: "history-456", uri: "https://api.cityverve.org.uk/v1/entity/history/history-456", name: "The Portico Library opens as a businessmen's subscription library and newsroom", type: "history", loc: { type: "Point", coordinates: [ -2.240278, 53.479721 ] }, entity: { index: -5175360000, date: "3rd December 1806", year: 1806, image: "https://upload.wikimedia.org/wikipedia/commons/a/a8/Portico_Library%2C_Manchester.jpg", description: "The Portico Library, The Portico or Portico Library and Gallery on Mosley Street, Manchester, is an independent subscription library designed in the Greek Revival style by Thomas Harrison of Chester and built between 1802 and 1806. It has been described as 'the most refined little building in Manchester'. The library was established as a result of a meeting of Manchester businessmen in 1802 which resolved to found an 'institute uniting the advantages of a newsroom and a library'." } } ]

In this document you will see there is complete consistency in the structure of the data present within the scope of The Global Guarantee (although the data values themselves are instance specific). However the entity section of the document is different from blue-plaques and is specific to the history entity type.

You can find a full list of Entity Guarantees here.

Instance Specific Data

Sometimes, although not always, you will find some entity data contained with the instance section of the document. This is for data which is attributable to the entity, but which does not form part of the entity guarantee. Typically, this means the data is more ad hoc and only occasionally present. It may also mean that multiple backend systems are providing the source data and only a subset of those has this extra data.

Taking the same entity example as shown above, here is the same data with some instance specific information also present.

[ { id: "history-456", uri: "https://api.cityverve.org.uk/v1/entity/history/history-456", name: "The Portico Library opens as a businessmen's subscription library and newsroom", type: "history", loc: { type: "Point", coordinates: [ -2.240278, 53.479721 ] }, entity: { index: -5175360000, date: "3rd December 1806", year: 1806, image: "https://upload.wikimedia.org/wikipedia/commons/a/a8/Portico_Library%2C_Manchester.jpg", description: "The Portico Library, The Portico or Portico Library and Gallery on Mosley Street, Manchester, is an independent subscription library designed in the Greek Revival style by Thomas Harrison of Chester and built between 1802 and 1806. It has been described as 'the most refined little building in Manchester'. The library was established as a result of a meeting of Manchester businessmen in 1802 which resolved to found an 'institute uniting the advantages of a newsroom and a library'." }, instance: { maintenance: "Cleaned Nov 17th" } } ]

An "instance" property will always be present for entities, but will be empty in most instances.

Instance specific data is only documented in an informal, ad hoc way. It can be discovered mostly via experimentation. Since it is not always present, users who want to use it must create applications that are tolerant of it not always being present. They must also create code that tests for its existence before addressing it.

Instance specific data is clearly not desirable, but is an inevitable consequence of a heterogeneous and diverse system. The API team will endeavour to keep it to a minimum in favour of maintaining a richer entity guarantee. However, where ad hoc data is available, we feel it is better to return it to the user rather than suppress it.

Error Scenarios

There are a number of scenarios which can results in responses from the API which are not a HTTP OK (response code HTTP/200). For example, you might ask for an entity with an ID that is not recognised by the system. In this case, you will get a response code to indicate that the entity is not found. Similarly, other response codes may be returned in reaction to requests that contain issues with the entity ID.

If you ask for an entity with an ID that is not known to the system, the response will be as follows:

HTTP/404 - Not Found

If you ask for an entity with an ID that has changed and is no longer preferred by the system, the response will be as follows:

HTTP/301 - Moved Permanently

If you ask for an entity with an ID that has been removed from the system, the response will be as follows:

HTTP/410 - Gone

Time (Space) Series

The time (space) series API gives access to data that has a temporal dimension. Typically it is data that is a time and value pair. There are two type of time series data represented within the system:

  • Feeds are time series that occur on a regular cadence (for example data from an air quality sensor)
  • Events are time series that occur on a non-regular, erratic or ad hoc basis (for example departure of buses from a bus Stop)

Both types of time series have exactly the same access mechanism. In general the model being presented is as follows:

  • An entity may have zero, one or more time (space) series
  • A time (space) series may have zero, one or more data points
  • A data point is a start time reference, an optional end time reference, an optional space reference and a data value

The reason "space" is inserted in "Time (Space) Series" is to account for the fact that some time series delivering sensors are not fixed in space (i.e. they may be mounted on top of a moving vehicle such as a tram). In a strict sense, the Time Series API always returns [space-time, value] but in most cases the space portion is a fixed, non-moving point. There won't be cases of a single time series have spatial data on some points and not on others; it's either always there or always not there, for a given time series.

Entities with Time Series Data

All time series data is returned the context of an owning entity within the Entity API. Some entities will have time series data, but not all. It depends on the domain context of their corresponding entity type. For example, a bus-stop might have a time series of all the buses which left it. However a park-bench might not have any time series associated with it.

If present, time series will be presented peer-level to the entity node in the returned document:

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W

{ id: "6472W", uri: "https://api.cityverve.org.uk/v1/entity/noise-meter/6472W", type: "noise-meter", name: "6472W", loc: { type: "Point", coordinates: [ -2.2874, 53.3853 ] }, entity: { manufacturer: "Noise Sense", date-installed: "2016-12-13T15:00:00Z", power-type: "solar-cell-a-12" }, timeseries: [ { id: "dose", uri: "https://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/dose", loc: { type: "Point", coordinates: [ -2.2734, 53.4753 ] }, periodicity: "PT15M", mobility: "fixed", latest: { from: "2017-11-28T23:14:28.221Z", to: "2017-11-28T23:29:28.221Z", value: "72.9" }, value: { type: "decibel", unit: "db" } }, { id: "peak", uri: "https://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/peak", loc: { type: "Point", coordinates: [ -2.2734, 53.4753 ] }, periodicity: "PT15M", mobility: "fixed", latest: { from: "2017-11-21T22:14:28.221Z", to: "2017-11-218T22:29:28.221Z", value: "93.0" }, value: { type: "decibel", unit: "db" } } ] }

This noise meter presents two time series (which may be logical constructs sourced from the same singular physical hardware). The top-level time series data consists of:

  • id - An instance unique id for this time series.
  • loc - (optional) The location of the sensor generating the time series data (see below).
  • periodicity - (optional) The cadence in which new data can be expected.
  • mobility - (optional) Whether the sensor is fixed in space or is mounted on a moving housing.
  • latest - The last data point for this time series (see below).
  • value - Information about the type and unit that this time series is measuring
The Geographical Location of Time Series Data

The exact Geographical point from which the time series data points originate can be specified in up to three levels of detail:

  • Entity Level - This is specified as the 'loc' property in the Global Guarantee section.
  • Sensor Level - When present in a 'time series' property, this is a more specific location for data points than its parent entities' location.
  • Data Point Level - When present in a 'data point' property (see below), this is a more specific location for single data point than either its parent sensor or entities' location.

For example a ozone-meter may simply present a location at the topmost global level. Whereas a weather-station may consist of several time series, each with a specific location that is more specific than that of the overall station. Finally, a noise-meter maybe mounted on to a bus and hence give a location for every sampled data point.

Where locations are specified at a data point level, they will be present for all data points in that time series. Which means that location will be present for either zero or all data points for a given time series.

Access Only the Time Series For an Entity

If you request the details of a specific entity but with the trailing timeseries URL resource, the API will return only the time series portion of the entity document.

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries

[ { id: "dose", uri: "https://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/dose", loc: { type: "Point", coordinates: [ -2.2734, 53.4753 ] }, periodicity: "PT15M", mobility: "fixed", latest: { from: "2017-11-28T23:14:28.221Z", to: "2017-11-28T23:29:28.221Z", value: "72.9" }, value: { type: "decibel", unit: "db" } }, { id: "peak", uri: "https://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/peak", loc: { type: "Point", coordinates: [ -2.2734, 53.4753 ] }, periodicity: "PT15M", mobility: "fixed", latest: { from: "2017-11-21T22:14:28.221Z", to: "2017-11-218T22:29:28.221Z", value: "93.0" }, value: { type: "decibel", unit: "db" } } ]
Access a Specific Time Series For an Entity

To get information about a specific time series you need to address it directly using its ID in relation to it owning entity.

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/dose

{ id: "dose", uri: "https://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/dose", loc: { type: "Point", coordinates: [ -2.2734, 53.4753 ] }, periodicity: "PT15M", mobility: "fixed", latest: { from: "2017-11-28T23:14:28.221Z", to: "2017-11-28T23:29:28.221Z", value: "72.9" }, value: { type: "noise", unit: "decibel" } }
Obtaining Data Points from a Time Series

To get the actual data points from the given time series you need to address it directly using its ID in relation to it owning entity and then ask for the datapoints as a trailing URL resource.

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/dose/datapoints

[ { from: "2017-11-22T12:51:38.952Z", to: "2017-11-22T13:06:38.952Z", value: "78.18" }, { from: "2017-11-22T13:10:07.245Z", to: "2017-11-22T13:25:07.245Z", value: "72.32" }, { from: "2017-11-22T13:28:20.028Z", to: "2017-11-22T13:43:20.028Z", value: "70.31" }, { from: "2017-11-22T13:46:48.605Z", to: "2017-11-22T14:01:48.605Z", value: "78.83" }, { from: "2017-11-22T14:04:52.430Z", to: "2017-11-22T14:19:52.430Z", value: "80.03" } ]

There may be cases where the from and to values are the same, or where the to value is missing altogether. This is for point samples rather than for period based samples.

As stated above, there may be cases where a location (loc) property is also present for a each data point.

The current paging point for time series data points is 250 items. This is the maximum you will see in a single document. For more items, you will need to use the filtering URL parameters below.

Filtering Data Points from a Time Series

There are several way to filter the time series data points based upon a series of URL parameters.

Time Filtering
Param Description Notes
start The earliest time value as an ISO 8601 date Can be used on it's own
end The latest time value as an ISO 8601 date You must also specify a start parameter. Can't be used with duration
duration The time interval for values as number of seconds You must also specify a start parameter. Can't be used with end

Please be aware of the following validation rules:

  • A non ISO 8601 start will be ignored
  • A non ISO 8601 end will be ignored
  • A non integer duration will be ignored
  • An end without a start will be ignored
  • A duration without a start will be ignored
  • Where both an end and duration are supplied, the duration will be ignored
Value Filtering
Param Description Notes
gt Greater than Can't be used with gte
gte Greater than or equal to Can't be used with gt
lt Less than Can't be used with lte
lte Less than or equal to Can't be used with lt
eq Equal to Can't be used with gt, gte, lt or lte,

Please be aware of the following validation rules:

  • Where both a gte and gt are supplied, the gt will be ignored
  • Where both a lte and lt are supplied, the lt will be ignored
  • Where an eq is supplied, all other value filters will will be ignored
Count Filtering
Param Description Notes
limit The maximum count of values (defaults to the current maximum of 250) Takes precendance over all other filters

Please be aware of the following validation rules:

  • A non numeric limit will be ignored
  • A zero or negative limit will be ignored
  • A limit over the maximum will be ignored

The Time, Value and Count filters can be combined into the same single request

Examples

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?start=2017-01-23T01%3A15%3A00Z

Values from a start time

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?end=2017-01-23T01%3A20%3A00Z

Values between a start and end time

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?start=2017-01-23T01%3A15%3A00Z&duration=3600

Values from a start time for an iterval

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?limit=120

The last 120 values

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?start=2017-01-23T01%3A15%3A00Z&end=2017-01-23T01%3A20%3A00Z&limit=120

Up to a maximum number of 120 values between a start and end time

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?start=2017-01-23T01%3A15%3A00Z&duration=3600&limit=120

Up to a maximum number of 120 values from a start time

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?gt=90

Where the data exceed 90

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?lte=45

Where the data is less than or equal to 45

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?lte=45&gt=90

Where the data is between 45 and 90

GEThttps://api.cityverve.org.uk/v1/entity/noise-meter/6472W/timeseries/impulse/datapoints?start=2017-01-23T01%3A15%3A00Z&end=2017-01-23T01%3A20%3A00Z&gt=90

Values between a start and end time where the data is greater than 90

Subscribe to CityCast - the smart cities podcast from CityVerve