Assets Discovery Service

Version: 0.1

This API aims to create the foundations for a novel urban data observatory in the form of a service that allow various stakeholders (data scientists, city decision makers, organisations and citizens) to explore, with the intent to act, mixed static and real-time urban and social data streams and their exploitation in experimentation.

It comprises the following functionalities:

This API is the core engine of the Organicity Urban Data Observatory and it is designed following the OASC principles, as an extension of the NGSI 9/10 standard, specially following the new FIWARE-NGSI v2 Specification

Schemes: http

Base URL: http://discovery.organicity.eu/v0

Summary

Tag: Assets

Operation Description
GET /assets

Retrieve an assets using multiple criteria

GET /assets/ngsiv2

Retrieve an assets using multiple criteria in NGSI V2

GET /assets/{urn}/ngsiv2

Retrieve an assets using multiple criteria in NGSI V2

GET /assets/services

Return the services the assets belong to (under development)

GET /assets/service/{service}

Return a specific service (under development)

GET /assets/sites

Return the sites the assets belong to

GET /assets/sites/{site}

Return a specific site

GET /assets/experiments/{experimentsID}

Return assets from an experiment

GET /assets/experimenters/{experimenterID}

Return assets from from an experimenter

GET /assets/providers

Return the providers the assets belong to

GET /assets/providers/{provider}

Return a specific provider

GET /assets/geo/

Return a list of assets as a GeoJSON Feature Collection

GET /assets/geo/search

Return a list of assets filtered by geolocation

GET /assets/metadata/search

Return a list of assets filtered by specific metadata

GET /assets/{assetUrn}

Return an assets by Unique Resource Name

GET /assets/{assetUrn}/data

The Asset data by Unique Resource Name

GET /assets/{assetUrn}/data/ngsiv2

The Asset data by Unique Resource Name.

GET /assets/{assetUrn}/nearby

Retrieve assets geograpically

Tag: NGSI v2

Operation Description
GET /assets/ngsiv2

Retrieve an assets using multiple criteria in NGSI V2

GET /assets/{urn}/ngsiv2

Retrieve an assets using multiple criteria in NGSI V2

GET /assets/{assetUrn}/data/ngsiv2

The Asset data by Unique Resource Name.

Tag: Types

Operation Description
GET /types/{types}

Return a specific asset type

GET /types

Return the types the assets belong to

Tag: Geo

Operation Description
GET /assets/geo/

Return a list of assets as a GeoJSON Feature Collection

GET /assets/geo/search

Return a list of assets filtered by geolocation

Security

oAuth

authorizationUrl:
https://accounts.organicity.eu/
flow:
implicit
description:
The Urban Discovery API requires setting up an oAuth prior to performing certain actions that require authorisation. More info: https://github.com/OrganicityEu/organicityeu.github.io/blob/master/doc/HowToAccessToken.md

Paths

Retrieve an assets using multiple criteria

GET /assets

Tags: Assets

Retrieve an assets using multiple criteria

urn

Filter assets by their Unique Resource Name

query string
lastUpdated

Filter assets by last updated date

query string (date-time)
type

Filter assets by type

query string
sort

Sort assets. Supported values are to be defined.

query string
filter

Filter assets. Supported values are to be defined.

query string
order

Order assets DESC or ASC.

query string
offset

Return assets with the given offset of N results.

query integer (int32)
page

Return assets for the given page.

query integer (int32)
per

Return N assets per page.

query integer (int32)
sample

Return a random sample of N assets.

query integer (int32)

application/json

200 OK

Body Schema: object[]

Reference: Asset
oAuth
Return assets from from an experimenter

GET /assets/experimenters/{experimenterID}

Tags: Assets

Return assets from from an experimenter

experimenterID

Filter assets by experimenter

path string

application/json

200 OK

Body Schema: object[]

Reference: Asset
Return assets from an experiment

GET /assets/experiments/{experimentsID}

Tags: Assets

Return assets from an experiment

experimentsID

Filter assets by experiment

path string

application/json

200 OK

Body Schema: object[]

Reference: Asset
Return a list of assets as a GeoJSON Feature Collection

GET /assets/geo/

Tags: Assets, Geo

Return a list of assets as an array of GeoJSON Feature Collections grouped by Asset Types

application/geojson

200 OK

Body Schema: object[]

Reference: GeoJSONAssets
Return a list of assets filtered by geolocation

GET /assets/geo/search

Tags: Assets, Geo

Return a list of assets filtered by geolocation as an array of GeoJSON Feature Collections grouped by Asset Types

lat

Center latitude for geographical queries

query number (float)
long

Center longitude for geographical queries

query number (float)
radius

Spherical radius for geographical queries in radians or when km is true in kilometers

query number (float)
km

When true sets radius property to work in kilometers

query boolean
query

At the moment only query="polygon" is supported

query string
points

Array of geographical coordinates

query number[][]
ip

IP address

query string
city

City name for geographical queries

query string

application/geojson

200 OK

Body Schema: object[]

Reference: GeoJSONAssets
Return a list of assets filtered by specific metadata

GET /assets/metadata/search

Tags: Assets

Return a list of assets filtered by specific metadata

query

metadata query string (use + to include multiple queries)

query string

application/json

200 OK

Body Schema: object[]

Reference: Asset
Retrieve an assets using multiple criteria in NGSI V2

GET /assets/ngsiv2

Tags: Assets, NGSI v2

Retrieve an assets using multiple criteria in NGSI V2

urn

Filter assets by their Unique Resource Name

query string
lastUpdated

Filter assets by last updated date

query string (date-time)
type

Filter assets by type

query string
sort

Sort assets. Supported values are to be defined.

query string
filter

Filter assets. Supported values are to be defined.

query string
order

Order assets DESC or ASC.

query string
offset

Return assets with the given offset of N results.

query integer (int32)
page

Return assets for the given page.

query integer (int32)
per

Return N assets per page.

query integer (int32)
sample

Return a random sample of N assets.

query integer (int32)
query

Return a list of assets based on metadatadatatata search

query string

application/json

200 OK

Body Schema: object[]

Reference: AssetNSGI/
oAuth
Return the providers the assets belong to

GET /assets/providers

Tags: Assets

Return the providers the assets belong to

application/json

200 OK

Body Schema: object[]

Reference: Provider
Return a specific provider

GET /assets/providers/{provider}

Tags: Assets

Return a specific provider

provider

Filter providers by provider name

path string

application/json

200 OK
Reference: Provider
Return a specific service (under development)

GET /assets/service/{service}

Tags: Assets

Return a specific service (under development)

service

Filter services by service name

path string

application/json

200 OK
Reference: Service
Return the services the assets belong to (under development)

GET /assets/services

Tags: Assets

Return the services the assets belong to (under development)

application/json

200 OK

Body Schema: object[]

Reference: Service
Return the sites the assets belong to

GET /assets/sites

Tags: Assets

Return the sites the assets belong to

application/json

200 OK

Body Schema: object[]

Reference: Site
Return a specific site

GET /assets/sites/{site}

Tags: Assets

Return a specific site

site

Filter sites by site name

path string
type

Filter site assets by asset type

query string

application/json

200 OK
Reference: Site
Return an assets by Unique Resource Name

GET /assets/{assetUrn}

Tags: Assets

Return an assets by Unique Resource Name

assetUrn

Unique Resource Name of the asset

path string

application/json

200 OK
Reference: Asset
The Asset data by Unique Resource Name

GET /assets/{assetUrn}/data

Tags: Assets

The Asset data following the NGSI 9/10 model defined in Organicity Assets Directory.

assetUrn

Unique Resource Name of the asset

path string

application/json

200 OK
Reference: AssetData
The Asset data by Unique Resource Name.

GET /assets/{assetUrn}/data/ngsiv2

Tags: Assets, NGSI v2

The Asset data following the NGSI v2 approach removing the original XML legacy. It also groups the data based on the Assets structure defined in D2.1 Section 4.5.1, this improve performance on data parsing and presentation.

assetUrn

Unique Resource Name of the asset

path string

application/json

200 OK
Reference: AssetData_NSGI
Retrieve assets geograpically

GET /assets/{assetUrn}/nearby

Tags: Assets

Retrieve assets geograpically close to other assets

assetUrn

Unique Resource Name of the asset

path string
radius

Spherical radius for geographical queries

query string
query

At the moment only query="polygon" is supported

query string
points

Array of geographical coordinates. Assets lat and long are taken as starting point.

query string
city

City name for geographical queries

query string

application/json

200 OK

Body Schema: object[]

Reference: Asset
Retrieve an assets using multiple criteria in NGSI V2

GET /assets/{urn}/ngsiv2

Tags: Assets, NGSI v2

Retrieve an assets using multiple criteria in NGSI V2

urn

Filter assets by their Unique Resource Name

path string

application/json

200 OK

Body Schema: object[]

Reference: AssetNSGI/
oAuth
Return the types the assets belong to

GET /types

Tags: Types

Return the types the assets belong to

application/json

200 OK

Body Schema: object[]

Reference: Types
Return a specific asset type

GET /types/{types}

Tags: Types

Return a specific asset types

types

Filter assets types by assets type name

path string

application/json

200 OK
Reference: Types

Schema definitions

Asset: object

id: string
type: string
context: Reference: Context
related: object
{
"context": {
"experiment": "56991853005557f52f277a88",
"last_reading_at": "2016-03-10T18:03:05.000Z",
"name": "9",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"provider": "phone",
"service": "smartphone"
}
,
"id": "urn:oc:entity:london:smartphone:phone:9",
"related": {
"experiment": {
"id": "56991853005557f52f277a88",
"links": {
"related": {
"href": "http://www.greatexperiment.org/organicity"
}
,
"self": "/experiments/56991853005557f52f277a88"
}
,
"type": "audio"
}
,
"group": {
"type": null
}
,
"provider": {
"type": "phone"
}
,
"service": {
"type": "smartphone"
}
,
"site": {
"id": "urn:oc:entity:london",
"links": {
"avatar": {
"href": "http://cliparts.co/cliparts/LTd/jL4/LTdjL4djc.jpg"
}
,
"related": {
"href": "https://en.wikipedia.org/wiki/London"
}
,
"self": "/assets/sites/urn:oc:entity:london"
}
,
"name": "London",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"type": "city"
}
}
,
"type": "smartphone"
}

AssetData: object

The Assets data following the NGSI 9/10 definition

id: string
type: string
context: Reference: Context
related: object
attributes: object[]
object
type: string
name: string
value: string
metadata: object[]
object
type: string
name: string
value: string
{
"attributes": [
{
"metadata": [
{
"name": "internal",
"type": "boolean",
"value": "false"
},
{
"name": "documentation",
"type": "string",
"value": "https://developer.transportapi.com/"
}
]
,
"name": "historicdata",
"type": "string",
"value": "https://api.transportapi.com/v1/"
},
{
"metadata": [
{
"name": "internal",
"type": "boolean",
"value": "true"
}
]
,
"name": "historicdata",
"type": "string",
"value": "http://santander.organicity.eu/entities/"
},
{
"metadata": [
{
"name": "internal",
"type": "boolean",
"value": "false"
},
{
"name": "mediatype",
"type": "string",
"value": "XML"
}
]
,
"name": "historicdata",
"type": "string",
"value": "http://datos.santander.es/resource?ds=sensores-parking-superficie&id=3b9de218-9678-4ebe-9390-b2bad7cfe6cb&ft=XML"
},
{
"attributes": [
{
"name": "description",
"type": "urn:oc:attributeType:description",
"value": "Edison - IC Room 5"
},
{
"metadata": [
{
"name": "unit",
"type": "urn:oc:uom:decibel",
"value": "decibel"
},
{
"name": "datatype",
"type": "urn:oc:datatype:numeric",
"value": "numeric"
}
]
,
"name": "soundPressureLevel:ambient",
"type": "urn:oc:attributeType:soundPressureLevel:ambient",
"value": "60.0"
}
]
,
"id": "urn:oc:entity:london:enableiot:fixed:02‐00‐86‐76‐97‐26",
"isPattern": "false",
"type": "soundPressureLevel:ambient"
}
]
,
"context": {
"experiment": "56991853005557f52f277a88",
"group": null,
"last_reading_at": "2016-03-10T18:03:05.000Z",
"name": "9",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"provider": "phone",
"recorded_at": "2016-03-10T18:03:05.000Z",
"service": "smartphone"
}
,
"id": "urn:oc:entity:london:smartphone:phone:9",
"type": "rawdata"
}

AssetData_NSGI: object

This is in beta, documentation is not stable! The data model follows NGSI v2 approach removing the original XML legacy. It also groups the data based on the Assets structure defined in D2.1 Section 4.5.1, this improve performance on data parsing and presentation.

id: string
type: string
context: Reference: Context
attributes: object
historic: object[]
object
observations: object[]
object
type: string
value: string
metadata: object
{
"attributes": {
"historic": [
{
"metadata": {
"documentation": {
"type": "href",
"value": "https://developer.transportapi.com/"
}
,
"internal": {
"type": "boolean",
"value": "false"
}
}
,
"type": "dataset",
"value": "https://api.transportapi.com/v1/"
},
{
"metadata": {
"internal": {
"type": "boolean",
"value": "true"
}
}
,
"type": "raw",
"value": "http://santander.organicity.eu/entities/"
},
{
"metadata": {
"internal": {
"type": "boolean",
"value": "false"
}
,
"mediatype": {
"type": "d",
"value": "XML"
}
}
,
"type": "dataservice",
"value": "http://datos.santander.es/resource?ds=sensores-parking-superficie&id=3b9de218-9678-4ebe-9390-b2bad7cfe6cb&ft=XML"
}
]
,
"observations": [
{
"attributes": {
"description": {
"type": "urn:oc:attributeType:description",
"value": "Edison - IC Room 5"
}
,
"soundPressureLevel:ambient": {
"metadata": {
"datatype": {
"type": "urn:oc:datatype:numeric",
"value": "numeric"
}
,
"unit": {
"type": "urn:oc:uom:decibel",
"value": "decibel"
}
}
,
"type": "urn:oc:attributeType:soundPressureLevel:ambient",
"value": "60.0"
}
}
,
"id": "urn:oc:entity:london:enableiot:fixed:02‐00‐86‐76‐97‐26",
"isPattern": "false",
"type": "soundPressureLevel:ambient"
}
]
}
,
"context": {
"experiment": "56991853005557f52f277a88",
"group": null,
"last_reading_at": "2016-03-10T18:03:05.000Z",
"name": "9",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"provider": "phone",
"recorded_at": "2016-03-10T18:03:05.000Z",
"service": "smartphone"
}
,
"id": "urn:oc:entity:london:smartphone:phone:9",
"type": "rawdata"
}

AssetNSGI: object

{
"doc": {
"TimeInstant": {
"metadata": {
}
,
"type": "urn:oc:attributeType:ISO8601",
"value": "2015-11-25T13:55:03.000Z"
}
,
"batteryLevel": {
"metadata": {
}
,
"type": "urn:oc:attributeType:batteryLevel",
"value": "80.00"
}
,
"id": "urn:oc:entity:santander:environmental:fixed:81",
"position": {
"metadata": {
}
,
"type": "coords",
"value": "43.47137,-3.80053"
}
,
"temperature:ambient": {
"metadata": {
}
,
"type": "urn:oc:attributeType:temperature:ambient",
"value": "12.83"
}
,
"type": "urn:oc:entityType:iotdevice"
}
}

AttributesTypes: object

type: string
description: string
units: object[]
object
name: string
description: string
type: string
{
"description": "An Air Quality Sensor for Particle Matter",
"type": "chemicalAgentAtmosphericConcentration:airParticles",
"units": [
{
"description": "The weight in milligrams on a cubic meter volume",
"name": "urn:oc:uom:milligramPerCubicMetre",
"type": "urn:oc:dataType:numeric"
}
]
}

Context: object

service: string
provider: string
name: string
location: object
latitude: number (float)
longitude: number (float)
city: string
country_code: string
country: string
{
"name": "9",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"provider": "phone",
"service": "smartphone"
}

Experiment: object

id: string
type: string
context: Reference: Context
experimenterId: integer
registered: string (date-time)
expirationTime: string (date-time)
startingTime: string (date-time)
status: string
experimentArea: object
latitude: number (float)
longitude: number (float)
keywords: string[]
string
assets: object[]
Reference: Asset
{
"assets": [
{
"context": {
"experiment": "56991853005557f52f277a88",
"group": null,
"last_reading_at": "2016-03-10T18:03:05.000Z",
"name": "9",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"provider": "phone",
"service": "smartphone"
}
,
"id": "urn:oc:entity:london:smartphone:phone:9",
"related": {
"group": {
"type": null
}
,
"provider": {
"type": "phone"
}
,
"service": {
"type": "smartphone"
}
,
"site": {
"id": "urn:oc:entity:london",
"links": {
"avatar": {
"href": "http://cliparts.co/cliparts/LTd/jL4/LTdjL4djc.jpg"
}
,
"related": {
"href": "https://en.wikipedia.org/wiki/London"
}
,
"self": "/assets/sites/urn:oc:entity:london"
}
,
"name": "London",
"position": {
"city": "London",
"country": "Great Britain",
"country_code": "GB",
"latitude": 51.52209641,
"longitude": -0.10705951
}
,
"type": "city"
}
}
,
"type": "smartphone"
}
]
,
"experimentArea": [
{
"position": {
"latitude": 51.52209641,
"longitude": -0.10705951
}
}
]
,
"experimenterId": "da41542651515151514141",
"expirationTime": "2016-10-10T18:03:05.000Z",
"id": "56991853005557f52f277a88",
"keywords": [
"sound",
"device",
"iot"
]
,
"registered": "2016-03-10T18:03:05.000Z",
"startingTime": "2016-04-10T18:03:05.000Z",
"status": "active",
"type": "audio"
}

GeoJSONAssets: object

A GeoJSON Feature Collections http://geojson.org/geojson-spec.html#feature-collection-objects

{
"features": [
{
"geometry": {
"coordinates": [
38.2587374,
21.7463555
]
,
"type": "Point"
}
,
"properties": {
"group": "null",
"id": "urn:oc:entity:patras:dev:fixed:1",
"last_update_at": 1448979138,
"origin": "null",
"provider": "null",
"service": "null",
"site": "patras",
"type": "urn:oc:entitytype:iotdevice"
}
,
"type": "Feature"
}
]
,
"properties": {
"name": "urn:oc:entitytype:iotdevice"
}
,
"type": "FeatureCollection"
}

Provider: object

id: string
type: string
links: object
related: object
{
"id": "135aa31",
"links": {
"related": {
"href": "http://en.wikipedia.com/wiki/phone"
}
}
,
"related": {
"cities": [
{
"attributes": {
"assets": 254,
"offline": 119,
"online": 135
}
,
"id": "1",
"metadata": {
"name": "Barcelona",
"position": {
"latitude": 41.3851,
"longitude": 2.1734
}
}
,
"type": "city"
}
]
}
,
"type": "phone"
}

Service: object

id: string
type: string
related: object
{
"id": "1",
"related": {
"cities": [
{
"attributes": {
"assets": 254,
"offline": 119,
"online": 135
}
,
"id": "1",
"metadata": {
"name": "Barcelona",
"position": {
"latitude": 41.3851,
"longitude": 2.1734
}
}
,
"type": "city"
}
]
}
,
"type": "Environmental"
}

Site: object

id: string
type: string
context: Reference: Context
attributes: object
links: object
{
"attributes": {
"assets": 254,
"offline": 119,
"online": 135
}
,
"context": {
"name": "Barcelona",
"position": {
"latitude": 41.3851,
"longitude": 2.1734
}
}
,
"id": "urn:oc:entity:barcelona",
"links": {
"avatar": {
"href": "http://cliparts.co/cliparts/LTd/jL4/LTdjL4djc.jpg"
}
,
"related": {
"href": "https://en.wikipedia.org/wiki/Barcelona"
}
,
"self": "/assets/sites/urn:oc:entity:barcelona"
}
,
"type": "city"
}

Types: object

type: string
description: string
{
"description": "An internet connected sensor or actuator.",
"type": "urn:oc:entityType:iotdevice"
}