About

The 52°North Series API provides a thin access layer to series datasets via RESTful Web binding. It provides different output formats like json, pdf or png.

This API development intends to make near realtime sensor data (provided by OGC Sensor Observation Services) better accessible for leightweight clients like mobile devices. However, in addition to the actual Web access layer the Series API offers a Service Provider Interface (SPI) which can be implemented to adapt arbitrary data sources.

The formally known Timeseries API has been renamed to Series API. Before version 2.0, only stationary insitu (located at a fixed location) timeseries data were supported. Since version 2.0, the API supports new observation types (beyond just timeseries) and sensor platforms.

With the new capabilities the API stays completely backwards compatible. An own section explains how backwards compatibility is achieved. However, where applicable a side note gives an explanation how previous endpoints relate to the new features version 2.0 brings along.

Overview

bigPicture

Document status

What When
Made several changes:
  • Added endpoints /platforms, /datasets and /geometries
  • Add side notes how previous endpoints relate to new features
  • Add plural filter parameters to general query section
  • Removed paging section as no implementation exists and led to confusion so far
  • Reviewed document to rename Timeseries API to Series API
2016-07-27
Added extras metadata. 2015-12-14
Added generalization section. 2015-07-06
Added station to general query parameters. 2014-02-06
Create legacy section and add low-level SOS concepts. 2013-12-16

What's New?

With the new version further types of sensor platforms and observation types. That's why a few new endpoints are available from v2. These provide access to all types of sensor platforms and observation types made.

However, to keep the easy access to (the most common case so far) measurement data from stationary insitu sensors and to ensure backwards compatibility, we introduced two filter parameters ( platformTypes and datasetTypes ) which can be used to declare which types of platforms/datasets are of interest.

It is worth to mention, that if both parameters are missing, all returning data from the API will relate to just stationary insitu platforms and measurement datasets!

Platforms

Since v2.0 the following sensor platforms are supported:

  • stationary sensor platforms
  • mobile sensor platforms
  • insitu sensor platforms
  • remote sensor platforms

The former Stations resource collection relates to the combination of stationary and insitu platforms. So retrieving getting the former output under platforms endpoint one can filter via platforms?platformTypes=stationary,insitu (yes, and AND filter) or get the collection via /stations .

The query parameter platformTypes can be used to filter on all resources which ensures to only get those resources related to the given filter.

Datasets

Since v2.0 the following dataset types are supported:

  • measurement
  • count
  • text

The former Timeseries resource collection relates to measurement . The others are new types and you can expect more to come.

The query parameter datasetTypes can be used to filter on all resources which ensures to only get those resources related to the given filter.

Content-Types

The API provides different content types which can be used to retrieve different types of representation of a requested resource. The actual content types differ for each resource so the ones supported are documented in the appropriate section.

Within the extended services output, the supported content types are now listed for each dataset type.

The content type supported by each resource is application/json . It is set as the default content type but can be set either via HTTP header or by .json extension.

Common Query Parameters

Each parameter is optional and can only contain one value. Multiple parameters are combined to an AND query. A resource may specify further query parameters to control/filter output. Special query parameters are described in each section.

Parameter Example Description
expanded
expanded=true

If true a list of partially expanded resource items is returned. The expansion provides more detailed information up to a certain point. However, it does not necessarily provide all item information as one may get when request the resource item itself.

The expanded works almost only for resource collection. However, exceptions may exist (e.g. for timeseries raw data). Exceptions are explicitly documented.

The default is false .

platformTypes
platformTypes=mobile,insitu
platformTypes=all

Filters the resources to get only those related to the platform type filter.

Allowed values are stationary , mobile , insitu , remote , all

The default is stationary,insitu .

datasetTypes
datasetTypes=measurement
datasetTypes=all

Filters the resources to get only those related to the dataset type filter.

Allowed values are measurement , count , text , all or any other custom types given by the implementing backend.

The default is measurement .

services
services=srv1
services=srv1,srv2
All resources where the given service id does match. The single form (service) is kept for backwards compatibility. Please use the plural form to filter on multiple ids.
platforms
platforms=pl1,pl2
All resources where the given platforms id(s) does match.
categories
categories=cat1,cat2
All resources where the given category id does match. The single form (category) is kept for backwards compatibility. Please use the plural form to filter on multiple ids.
phenomena
phenomena=phen1,phen2
All resources where the given phenomenon id match. The single form (phenomenon) is kept for backwards compatibility. Please use the plural form to filter on multiple ids.
station
station=sta_sadf2d
All resources where the given station id does match.
locale
locale=de

Specifies the language as ISO639 code. Subdivisions are respected by an _ , e.g. en_US for American English.

The REST-API should consider the following order to detect a locale:

  1. User-agent (e.g. header information)
  2. locale parameter

A fallback language cannot be specified as it depends on the data of the service provider.

Note that for GET requests the options have to be URL-encoded appropriately!

Common Status Codes

A client shall expect the following HTTP status codes returned by the API.

Code When
200 Status OK. All went fine.
400 Status Bad Request. The request data cannot be read.
404 Status Not Found. The resource is not available.
500 Status Internal Server Error. Please contact the webadmin. In some cases an error message will be shown. But in general the server logs will help to trace the problem.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/ application/json Lists all resource collections available.

Examples

Simple View

GET /api/v1/ HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "services",
    "label": "Service Provider",
    "description": "A service provider offers timeseries data."
  },
  {
    "id": "stations",
    "label": "Station",
    "description": "A station is the place where measurement takes place."
  },
  {
    "id": "timeseries",
    "label": "Timeseries",
    "description": "Represents a sequence of data values measured over time."
  },
  {
    "id": "categories",
    "label": "Category",
    "description": "A category groups available timeseries."
  },
  {
    "id": "offerings",
    "label": "Offering",
    "description": "An organizing unit to filter resources."
  },
  {
    "id": "features",
    "label": "Feature",
    "description": "An organizing unit to filter resources."
  },
  {
    "id": "procedures",
    "label": "Procedure",
    "description": "An organizing unit to filter resources."
  },
  {
    "id": "phenomena",
    "label": "Phenomenon",
    "description": "An organizing unit to filter resources."
  },
  {
    "id": "platforms",
    "label": "Platforms",
    "description": "A sensor platform where observations are made."
  },
  {
    "id": "datasets",
    "label": "Datasets",
    "description": "Represents a sequence of data values observed over time."
  },
  {
    "id": "geometries",
    "label": "Geometries",
    "description": "A geometry where observations are made or that was observed."
  }
]

Expanded View

GET /api/v1/?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "services",
    "label": "Service Provider",
    "description": "A service provider offers timeseries data.",
    "size": 7
  },
  {
    "id": "stations",
    "label": "Station",
    "description": "A station is the place where measurement takes place.",
    "size": 1393
  },
  {
    "id": "timeseries",
    "label": "Timeseries",
    "description": "Represents a sequence of data values measured over time.",
    "size": 5434
  },
  {
    "id": "categories",
    "label": "Category",
    "description": "A category group available timeseries.",
    "size": 0
  },
  {
    "id": "offerings",
    "label": "Offering",
    "description": "An organizing unit to filter resources.",
    "size": 72
  },
  {
    "id": "features",
    "label": "Feature",
    "description": "An organizing unit to filter resources.",
    "size": 1393
  },
  {
    "id": "procedures",
    "label": "Procedure",
    "description": "An organizing unit to filter resources.",
    "size": 1770
  },
  {
    "id": "phenomena",
    "label": "Phenomenon",
    "description": "An organizing unit to filter resources.",
    "size": 62
  }
]

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/platforms application/json Lists all platforms available.
GET /api/v1/platforms/{id} application/json Lists the platforms with id {id}.

Query Parameters

Please refer to the stations section. All query parameters are still valid for platforms.
For this resource common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Simple Collection

GET /api/v1/platforms/ HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "stationary_insitu_9",
    "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_9",
    "domainId": "http://www.52north.org/test/featureOfInterest/8",
    "label": "DLZ-IT",
    "platformType": "stationary_insitu"
  },
  {
    "id": "stationary_insitu_8",
    "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_8",
    "domainId": "http://www.52north.org/test/procedure/8",
    "label": "DLZ-IT",
    "platformType": "stationary_insitu"
  }
]
As noted above expanded=false is the default. Setting the parameter to false explicitly will have the same effect.

Expanded Collection

GET /api/v1/platforms/?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "stationary_insitu_10",
    "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_10",
    "domainId": "http://www.52north.org/test/featureOfInterest/Heiden",
    "label": "Heiden",
    "extras": [
      "license"
    ],
    "platformType": "stationary_insitu",
    "series": [
      {
        "id": "text_9",
        "href": "http://localhost:8080/api/v1/datasets/text_9",
        "label": "developer http://www.52north.org/test/procedure/developer, Heiden",
        "datasetType": "text"
      }
    ],
    "geometry": {
      "type": "Point",
      "coordinates": [
        6.932416,
        51.826044
      ]
    }
  },
  {
    "id": "stationary_insitu_7",
    "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_7",
    "domainId": "http://www.52north.org/test/featureOfInterest/6",
    "label": "Hochschule Bochum",
    "extras": [
      "license"
    ],
    "platformType": "stationary_insitu",
    "series": [
      {
        "id": "measurement_6",
        "href": "http://localhost:8080/api/v1/datasets/measurement_6",
        "label": "test_observable_property_6 Hochschule Bochum, Hochschule Bochum",
        "datasetType": "measurement"
      }
    ],
    "geometry": {
      "type": "Point",
      "coordinates": [
        7.270806,
        51.447722
      ]
    }
  }
]

Item

GET /api/v1/stations/stationary_insitu_7/ HTTP/1.1
  Host: sensorweb.demo.52north.org
  Accept: application/json
HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8

{
  "id": "stationary_insitu_7",
  "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_7",
  "domainId": "http://www.52north.org/test/featureOfInterest/6",
  "label": "Hochschule Bochum",
  "extras": [
    "license"
  ],
  "platformType": "stationary_insitu",
  "series": [
    {
      "id": "measurement_6",
      "href": "http://localhost:8080/api/v1/datasets/measurement_6",
      "label": "test_observable_property_6 Hochschule Bochum, Hochschule Bochum",
      "datasetType": "measurement"
    }
  ],
  "geometry": {
    "type": "Point",
    "coordinates": [
      7.270806,
      51.447722
    ]
  }
}

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/stations application/json Lists all stations available.
GET /api/v1/stations/{id} application/json Lists the stations with id {id}.

Query Parameters

Please refer to the Geometries section what spatial query parameters can be used on the stations collection.
For this resource further common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Simple Collection

GET /api/v1/stations/ HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "properties": {
      "id": "sta_5791c95b6d7f4bc70002be938b199cb1",
      "label": "Bramsche"
    },
    "geometry": {
      "coordinates": [
        "7.978186816994513",
        "52.3961713226858"
      ],
      "type": "Point"
    },
    "type": "Feature"
  },
  {
    "properties": {
      "id": "sta_316a8a47dd628e37c93a9fced3292afd",
      "label": "Deggendorf",
    },
    "geometry": {
      "coordinates": [
        "8.978186816994513",
        "51.3961713226858"
      ],
      "type": "Point"
    },
    "type": "Feature"
  }
]
As noted above expanded=false is the default. Setting the parameter to false explicitly will have the same effect.

Expanded Collection

GET /api/v1/stations/?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "properties": {
      "id": "sta_a1164b01586abf442ad312211d9f18e",
      "timeseries": {
        "ts_e6a9b2f10f2ff6a47da6ffeab747dc5a": {
          "phenomenon": {
            "id": "phe_4af57a13bb7fb9af7618fc6d74af3523",
            "label": "Abfluss"
          },
          "service": {
            "id": "srv_1a5bde0a6d702f193f7be463402ec12f",
            "label": "PEGELONLINE SOS"
          },
          "feature": {
            "id": "foi_c0ac9e8284131ef14094dcc3795925ae",
            "label": "Hattingen_2769510000100"
          },
          "offering": {
            "id": "off_5ba539e42edf995faaf923414760b9a5",
            "label": "ABFLUSS_ROHDATEN"
          },
          "procedure": {
            "id": "pro_89fc01ce9c37de1b787a3f75082a0632",
            "label": "Abfluss-Hattingen_2769510000100"
          }
        }
      },
      "label": "Hattingen_2769510000100"
    },
    "geometry": {
      "coordinates": [
        7.161047770931211,
        51.39975938475634
      ],
      "type": "Point"
    },
    "type": "Feature"
  },
  {
    "properties": {
      "id": "sta_98a0659ad84f3cfe14e0497b887dacfe",
      "timeseries": {
        "ts_7e0faa5796eabd3f0afddbf6112947f9": {
          "phenomenon": {
            "id": "phe_4af57a13bb7fb9af7618fc6d74af3523",
            "label": "Abfluss"
          },
          "service": {
            "id": "srv_1a5bde0a6d702f193f7be463402ec12f",
            "label": "PEGELONLINE SOS"
          },
          "feature": {
            "id": "foi_215db512cff2862ac8b2c1e0e345de0c",
            "label": "Ruhrort_2770010"
          },
          "offering": {
            "id": "off_5ba539e42edf995faaf923414760b9a5",
            "label": "ABFLUSS_ROHDATEN"
          },
          "procedure": {
            "id": "pro_a61248f63725cacc648f1ca3706048fd",
            "label": "Abfluss-Ruhrort_2770010"
          }
        },
        "ts_795f67d458d00de0f2686afa796a898b": {
          "phenomenon": {
            "id": "phe_f60bcfb1f6ac3d37210b5d757a1bf48e",
            "label": "Wasserstand"
          },
          "service": {
            "id": "srv_1a5bde0a6d702f193f7be463402ec12f",
            "label": "PEGELONLINE SOS"
          },
          "feature": {
            "id": "foi_215db512cff2862ac8b2c1e0e345de0c",
            "label": "Ruhrort_2770010"
          },
          "offering": {
            "id": "off_c599e9b089385d08aa00b7c9c4c6f3ef",
            "label": "WASSERSTAND_ROHDATEN"
          },
          "procedure": {
            "id": "pro_1f466baf90e7b1fb87d42a68274c13bf",
            "label": "Wasserstand-Ruhrort_2770010"
          }
        }
      },
      "label": "Ruhrort_2770010"
    },
    "geometry": {
        "coordinates": [
            6.7279422870428505,
            51.455354763381585
        ],
        "type": "Point"
    },
    "type": "Feature"
  }
]
Please refer to the GeoJSON specification if you need more detailed information about the geometry types used.

Item

GET /api/v1/stations/sta_a1164b01586abf442ad312211d9f18e/ HTTP/1.1
  Host: sensorweb.demo.52north.org
  Accept: application/json
HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8

  {
    "properties": {
      "id": "sta_a1164b01586abf442ad312211d9f18e",
      "timeseries": {
        "ts_e6a9b2f10f2ff6a47da6ffeab747dc5a": {
          "phenomenon": {
            "id": "phe_4af57a13bb7fb9af7618fc6d74af3523",
            "label": "Abfluss"
          },
          "service": {
            "id": "srv_1a5bde0a6d702f193f7be463402ec12f",
            "label": "PEGELONLINE SOS"
          },
          "feature": {
            "id": "foi_c0ac9e8284131ef14094dcc3795925ae",
            "label": "Hattingen_2769510000100"
          },
          "offering": {
            "id": "off_5ba539e42edf995faaf923414760b9a5",
            "label": "ABFLUSS_ROHDATEN"
          },
          "procedure": {
            "id": "pro_89fc01ce9c37de1b787a3f75082a0632",
            "label": "Abfluss-Hattingen_2769510000100"
          }
        }
      },
      "label": "Hattingen_2769510000100"
    },
    "geometry": {
      "coordinates": [
        7.161047770931211,
        51.39975938475634
      ],
      "type": "Point"
    },
    "type": "Feature"
  }

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/datasets application/json Lists all timeseries available.
GET /api/v1/datasets/{id} application/json

Lists the metadata of dataset with id {id} .

GET /api/v1/dataset/{id}/extras application/json Lists extra metadata which may vary from instance to instance. The available metadata fields are listed in the extras metadata section of a datasets. You can query just the ones you are interested in by appending the fields query parameter and passing a comma-separated value list to it. For example http://localhost:8080/api/v1/datasets/{id}/extras?fields=license
GET /api/v1/datasets/{id}/{interval} image/png Returns an image of datasets with id {id} for the given {interval}. Allowed interval values are
  • lastDay
  • lastWeek
  • lastMonth

Datasets of type measurement can be pre-rendered by a regular task. If pre-rendering is enabled for a given datasets depends on the API provider as it is a configuration issue.

If a datasets has no pre-rendered chart a 404 (Resource not found) error is returned. In particular cases this is also true when the chart is currently being re-rendered.

Request Data

Datasets data is actually not modelled as a resource itself. Data requests can be triggered by appending the data verb.

Method Path Content-Type Description
GET /api/v1/datasets/{id}/data application/json

Lists the data of dataset with id {id} .

GET /api/v1/datasets/{id}/data image/png

Draws a graph of the data of dataset with id {id} .

POST /api/v1/datasets/data application/json

Request the metadata for multiple datasets. The requested dataset ids have to be contained in the POST request.

Have a look at the POST request example how a POST request shall look like to get data for multiple datasets.

POST /api/v1/datasets/data image/png
application/pdf

Exports the given stack of datasets to the given output format. The requested dataset ids have to be contained in the POST request.

Each dataset can be styled (chart type, color, widths, etc) by passing style options. Have a look at the POST request example how a POST request shall look like to render multiple datasets.

What kind of content types for what dataset type are supported in concrete is listed in the service 's expanded output /api/v1/services?expanded=true

Query Parameters

Please refer to the timeseries section. All query parameters are still valid for datasets.
For this resource common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Simple Collection

GET /api/v1/datasets HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "text_9",
    "href": "http://localhost:8080/api/v1/datasets/text_9",
    "label": "developer http://www.52north.org/test/procedure/developer, Heiden",
    "datasetType": "text"
  },
  {
    "id": "measurement_1",
    "href": "http://localhost:8080/api/v1/datasets/measurement_1",
    "label": "test_observable_property_1 con terra, con terra",
    "datasetType": "measurement"
  }
]
As noted above expanded=false is the default. Setting the parameter to false explicitly will have the same effect.

Expanded Collection

GET /api/v1/datasets/?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "text_9",
    "href": "http://localhost:8080/api/v1/datasets/text_9",
    "label": "developer http://www.52north.org/test/procedure/developer, Heiden",
    "extras": [
      "license"
    ],
    "datasetType": "text",
    "seriesParameters": {
      "phenomenon": {
        "id": "9",
        "href": "http://localhost:8080/api/v1/phenomena/9",
        "label": "developer"
      },
      "procedure": {
        "id": "9",
        "href": "http://localhost:8080/api/v1/procedures/9",
        "label": "http://www.52north.org/test/procedure/developer"
      },
      "category": {
        "id": "9",
        "href": "http://localhost:8080/api/v1/categories/9",
        "label": "developer"
      },
      "offering": {
        "id": "9",
        "href": "http://localhost:8080/api/v1/offerings/9",
        "label": "http://www.52north.org/test/procedure/developer"
      },
      "feature": {
        "id": "10",
        "href": "http://localhost:8080/api/v1/features/10",
        "label": "Heiden"
      },
      "service": {
        "id": "1",
        "href": "http://localhost:8080/api/v1/services/1",
        "label": "My RESTful Dataset Service."
      },
      "platform": {
        "id": "stationary_insitu_9",
        "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_9",
        "label": "http://www.52north.org/test/procedure/developer",
        "platformType": "stationary_insitu"
      }
    },
    "firstValue": {
      "timestamp": 1225234800000,
      "value": "Carsten Hollmann"
    },
    "lastValue": {
      "timestamp": 1225234800000,
      "value": "Carsten Hollmann"
    }
  },
  {
    "id": "measurement_1",
    "href": "http://localhost:8080/api/v1/datasets/measurement_1",
    "label": "test_observable_property_1 con terra, con terra",
    "extras": [
      "license"
    ],
    "datasetType": "measurement",
    "seriesParameters": {
      "phenomenon": {
        "id": "1",
        "href": "http://localhost:8080/api/v1/phenomena/1",
        "label": "test_observable_property_1"
      },
      "procedure": {
        "id": "1",
        "href": "http://localhost:8080/api/v1/procedures/1",
        "label": "con terra"
      },
      "category": {
        "id": "1",
        "href": "http://localhost:8080/api/v1/categories/1",
        "label": "test_observable_property_1"
      },
      "offering": {
        "id": "1",
        "href": "http://localhost:8080/api/v1/offerings/1",
        "label": "con terra"
      },
      "feature": {
        "id": "2",
        "href": "http://localhost:8080/api/v1/features/2",
        "label": "con terra"
      },
      "service": {
        "id": "1",
        "href": "http://localhost:8080/api/v1/services/1",
        "label": "My RESTful Dataset Service."
      },
      "platform": {
        "id": "stationary_insitu_1",
        "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_1",
        "label": "con terra",
        "platformType": "stationary_insitu"
      }
    },
    "firstValue": {
      "timestamp": 1353326400000,
      "value": 1,
      "validTime": {
        "start": 1381528800000,
        "end": 1386802800000
      },
      "bar": "alice",
      "foo": 3.4
    },
    "lastValue": {
      "timestamp": 1353326940000,
      "value": 1.9
    },
    "uom": "test_unit_1"
  }
]

Simple Item

GET /api/v1/datasets/text_9 HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "text_9",
  "href": "http://localhost:8080/api/v1/datasets/text_9",
  "label": "developer http://www.52north.org/test/procedure/developer, Heiden",
  "extras": [
    "license"
  ],
  "datasetType": "text",
  "seriesParameters": {
    "phenomenon": {
      "id": "9",
      "href": "http://localhost:8080/api/v1/phenomena/9",
      "label": "developer"
    },
    "procedure": {
      "id": "9",
      "href": "http://localhost:8080/api/v1/procedures/9",
      "label": "http://www.52north.org/test/procedure/developer"
    },
    "category": {
      "id": "9",
      "href": "http://localhost:8080/api/v1/categories/9",
      "label": "developer"
    },
    "offering": {
      "id": "9",
      "href": "http://localhost:8080/api/v1/offerings/9",
      "label": "http://www.52north.org/test/procedure/developer"
    },
    "feature": {
      "id": "10",
      "href": "http://localhost:8080/api/v1/features/10",
      "label": "Heiden"
    },
    "service": {
      "id": "1",
      "href": "http://localhost:8080/api/v1/services/1",
      "label": "My RESTful Dataset Service."
    },
    "platform": {
      "id": "stationary_insitu_9",
      "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_9",
      "label": "http://www.52north.org/test/procedure/developer",
      "platformType": "stationary_insitu"
    }
  },
  "firstValue": {
    "timestamp": 1225234800000,
    "value": "Carsten Hollmann"
  },
  "lastValue": {
    "timestamp": 1225234800000,
    "value": "Carsten Hollmann"
  }
}

Data of a single datasets

Additional data (if available) can be requested via expanded=true .

GET /api/v1/datasets/measurement_1/data?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "measurement_1": {
    "values": [
      {
        "timestamp": 1353326400000,
        "value": 1,
        "validTime": {
          "start": 1381528800000,
          "end": 1386802800000
        },
        "bar": "alice",
        "foo": 3.4
      },
      {
        "timestamp": 1353326460000,
        "value": 1.1,
        "bar": "bob",
        "foo": 5
      }
    ]
  }
}

Data for a given dataset can get huge quickly depending on how often new values are measured and how long data is stored in the corresponding data backend! Naive clients can bother data providers when trying to request huge datasets by accident. Therefore data requests may be limited to a maximum timespan (per configuration).

However, most probably consuming huge datasets may also not be of client's interest. Have a look at the paging documentation how to get data in smaller chunks.

Data of multiple timeseries

POST /api/v1/datasets/data HTTP/1.1
Host: sensorweb.demo.52north.org
Content-Type: application/json
Accept: application/json

{
    "timespan" : "P1D/2012-11-20",
    "seriesIds": [
        "text_5",
        "measurement_1"
    ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "measurement_1": {
    "values": [
      {
        "timestamp": 1353326460000,
        "value": 1.1
      },
      {
        "timestamp": 1353326520000,
        "value": 1.2
      }
    ]
  },
  "text_5": {
    "values": [
      {
        "timestamp": 1353326400000,
        "value": "test_text_0"
      },
      {
        "timestamp": 1353326460000,
        "value": "test_text_1"
      }
    ]
  }
}

Image Data of combined datasets

Please refer to the timeseries section where an example is given how to combine data of multiple datasets in a graph.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/timeseries application/json Lists all timeseries available.
GET /api/v1/timeseries/{id} application/json

Lists the metadata of timeseries with id {id} .

GET /api/v1/timeseries/{id}/extras application/json Lists extra metadata which may vary from instance to instance. The available metadata fields are listed in the extras metadata section of a timeseries. You can query just the ones you are interested in by appending the fields query parameter and passing a comma-separated value list to it. For example http://localhost:8080/api/v1/timeseries/{id}/extras?fields=license
GET /api/v1/timeseries/{id}/{interval} image/png Returns an image of timeseries with id {id} for the given {interval}. Allowed interval values are
  • lastDay
  • lastWeek
  • lastMonth

Timeseries can be pre-rendered by a regular task. If pre-rendering is enabled for a given timeseries depends on the API provider as it is a configuration issue.

If a timeseries has no pre-rendered chart a 404 (Resource not found) error is returned. In particular cases this is also true when the chart is currently being re-rendered.

Request Data

Timeseries data is actually not modelled as a resource itself. Data requests can be triggered by appending the getData verb.

Method Path Content-Type Description
GET /api/v1/timeseries/{id}/getData application/json

Lists the raw data of timeseries with id {id} .

GET /api/v1/timeseries/{id}/getData image/png

Draws a graph of the data of timeseries with id {id} .

POST /api/v1/timeseries/getData application/json

Request the metadata for multiple timeseries. The requested timeseries ids have to be contained in the POST request.

Have a look at the POST request example how a POST request shall look like to get raw data for multiple timeseries.

POST /api/v1/timeseries/getData image/png
application/pdf

Exports the given stack of timeseries to the given output format. The requested timeseries ids have to be contained in the POST request.

Each timeseries can be styled (chart type, color, widths, etc) by passing style options. Have a look at the POST request example how a POST request shall look like to render multiple timeseries.

Query Parameters

Timeseries data can be queried with the following filter parameters.

Parameter Example Description
expanded
expanded=true

The expanded parameter works for collection data and also when requesting raw timeseries data.

Timeseries may provide additional data which changes over time (and therefore is not core metadata anymore). Best example are reference values which can be used to provide better interpretation to actual data values.

timespan
timespan=PT12H/2013-08-06
An ISO8601 formatted period. Only backslash formatted values are supported.
width
width=200
If image/png is requested, width determines the width in pixels.
height
height=200
If image/png is requested, height determines the width in pixels.
style
style={
  "chartType": "line",
  "properties": {
    "color": "#2f2f2f",
    "lineType": "solid",
    "width": 2
  }
}

Style options how the timeseries shall be rendered if an image/png shall be the output.

A more detailed explanation about styling can be found under the styles section.

legend
legend=true
Indicates if a legend shall be rendered directly on the image output (if image/png shall be the output).
generalize
generalize=true
Indicates that timeseries data shall be generalized. See genralization section for details.
force_latest_values
force_latest_values=true

The force_latest_values parameter can be used to force last value requests on a collection of timeseries.

Please note that this enforcement (in combination with expanded=true ) may result is long response times as the last value has to be requested for each timeseries of the requested collection. Use this enforcement only on filtered queries.

format
format=highcharts
Controls the output format of raw timeseries data. This avoids converting between different data formats on client side which uses a 3rd party chart rendering API. Currently, supported formats:
  • tvp: Time value pairs (the default)
  • highcharts: Highcharts series data format.
Refer to the Format section for detailed information how the formats will look like.
base64
base64=true

Indicates binary images shall be encoded to a base64 string on server side. This makes it easily possible to display images from JavaScript (you would need a byte parsing library otherwise).

Here is an example how to embed encoded base64 string:

<img src='data:image/png;base64," + encodedString + "' />
For this resource further common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Simple Collection

GET /api/v1/timeseries HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "ts_69a0a0df67ef791cd655f0a8bab9b62c",
    "label": "Snow_patchiness@1550",
    "station": {
      "properties": {
        "id": "sta_22bbc8df377555caf3a4d48fc56ce09c",
        "label": "1550"
      },
      "geometry": {
        "coordinates": [
          23.233991038000056,
          63.88340191100008
        ],
        "type": "Point"
      },
      "type": "Feature"
    }
  },
  {
    "id": "ts_3a4086d952d52f5aa37cda266487ceb2",
    "label": "Snow_water_equivalent@1501",
    "station": {
      "properties": {
        "id": "sta_209f40d2931eabd2c31fd856ce40e1e1",
        "label": "1501"
      },
      "geometry": {
        "coordinates": [
          31.06271994100007,
          63.06610459800004
        ],
        "type": "Point"
      },
      "type": "Feature"
    }
  }
]
As noted above expanded=false is the default. Setting the parameter to false explicitly will have the same effect.

Expanded Collection

GET /api/v1/timeseries/?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "ts_5fe646c5a8f99bf4e267bba9c2b9df2c",
    "label": "Snow_patchiness@1499",
    "station": {
      "properties": {
        "id": "sta_d950ac5e991045386221942560a04678",
        "label": "1499"
      },
      "geometry": {
        "coordinates": [
          30.426456999000038,
          62.79975521500006
        ],
        "type": "Point"
      },
      "type": "Feature"
    },
    "parameters": {
      "service": {
        "id": "srv_1121a9ada17a3e77dffcebdac5b31d50",
        "serviceUrl": "http://paikkatieto.ymparisto.fi/arcgis/rest/services/InSitu/SYKE_SnowCoursesInSitu/MapServer/exts/SOSExtension/"
      },
      "offering": {
        "id": "off_1e5d8b26d6aeca8edda62827f005de14",
        "label": "Patchiness -Offering"
      },
      "feature": {
        "id": "foi_e88d7dbbfba57d60aecdd3e09340ced1",
        "label": "1499"
      },
      "procedure": {
        "id": "pro_d24427415643fd7ac6d3d5bc5c9cf6ea",
        "label": "2"
      },
      "phenomenon": {
        "id": "phe_6639a8b1c9240706a20257573fdf108",
        "label": "Snow_patchiness"
      },
      "category": {
        "id": "cat_6639a8b1c9240706a20257573fdf108",
        "label": "Snow_patchiness"
      }
    }
  },
  {
    "id": "ts_2c3687d6ec86c85e36943a49c6a09ca7",
    "label": "Snow_depth@1537",
    "station": {
      "properties": {
        "id": "sta_e340eb0c274f5f6e1e33fcbbae769d35",
        "label": "1537"
      },
      "geometry": {
        "coordinates": [
          24.593801936000034,
          61.10789034100003
        ],
        "type": "Point"
      },
      "type": "Feature"
    },
    "parameters": {
      "service": {
        "id": "srv_1121a9ada17a3e77dffcebdac5b31d50",
        "serviceUrl": "http://paikkatieto.ymparisto.fi/arcgis/rest/services/InSitu/SYKE_SnowCoursesInSitu/MapServer/exts/SOSExtension/"
      },
      "offering": {
        "id": "off_a19e342c3787f923452d58d70bd46b0e",
        "label": "Snow Depth -Offering"
      },
      "feature": {
        "id": "foi_8391ce65de5246a4b35401c55ae6cd53",
        "label": "1537"
      },
      "procedure": {
        "id": "pro_9847ec590cc768cfe311ab65b7ad7873",
        "label": "1"
      },
      "phenomenon": {
        "id": "phe_c787cc873ab395055d0d4841cb43b0f0",
        "label": "Snow_depth"
      },
      "category": {
        "id": "cat_c787cc873ab395055d0d4841cb43b0f0",
        "label": "Snow_depth"
      }
    }
  }
]

Simple Item

GET /api/v1/timeseries/ts_c8ed5ddbb89c19b2e385de23eecbde98 HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "ts_c8ed5ddbb89c19b2e385de23eecbde98",
  "label": "Wasserstand@List_Auf_Sylt_9570070",
  "uom": "cm",
  "station": {
    "properties": {
      "id": "sta_a4bff7499d440d9bb67ad73e048c5a47",
      "label": "List_Auf_Sylt_9570070"
    },
    "geometry": {
      "coordinates": [
        8.440430928792344,
        55.016536566762
      ],
      "type": "Point"
    },
    "type": "Feature"
  },
  "lastValue": {
    "timestamp": 1379635200000,
    "value": 532.7
  },
  "parameters": {
    "service": {
      "id": "srv_1a5bde0a6d702f193f7be463402ec12f",
      "serviceUrl": "http://pegelonline.wsv.de/webservices/gis/gdi-sos"
    },
    "offering": {
      "id": "off_c599e9b089385d08aa00b7c9c4c6f3ef",
      "label": "WASSERSTAND_ROHDATEN"
    },
    "feature": {
      "id": "foi_25e09ee3155ab0fbf3e4684ad2edffbf",
      "label": "List_Auf_Sylt_9570070"
    },
    "procedure": {
      "id": "pro_e878d48e49ebc2a156e2810470bae9a2",
      "label": "Wasserstand-List_Auf_Sylt_9570070"
    },
    "phenomenon": {
      "id": "phe_f60bcfb1f6ac3d37210b5d757a1bf48e",
      "label": "Wasserstand"
    },
    "category": {
      "id": "cat_f60bcfb1f6ac3d37210b5d757a1bf48e",
      "label": "Wasserstand"
    }
  },
  "refValues": [
    {
      "referenceValueId": "ref_2adf9285e96f72c441a6344e151eb630",
      "label": "Pegelnullpunkt über NN",
      "lastValue": {
        "timestamp": 1379667208477,
        "value": -5
      }
    },
    {
      "referenceValueId": "ref_c99577da99e17df8b93731886e35578a",
      "label": "Niedrigstes Tideniedrigwasser",
      "lastValue": {
        "timestamp": 1379667208477,
        "value": 242
      }
    }
  ]
}

Data of a single timeseries

GET /api/v1/timeseries/ts_c8ed5ddbb89c19b2e385de23eecbde98/getData?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "ts_c8ed5ddbb89c19b2e385de23eecbde98": {
    "values": [
      {
        "timestamp": 1376563000000,
        "value": 442.8
      },
      {
        "timestamp": 1376568060000,
        "value": 441.8
      },
    ],
    "extra": {
      "referenceValues": {
        "ref_68192ce0f01b2b47821bac2547f9f9c0": {
          "values": [
            {
              "timestamp": 1376563000000,
              "value": 408
            },
            {
              "timestamp": 1376568060000,
              "value": 408
            }
          ]
        }
      }
    }
  }
}

Timeseries data can get huge quickly depending on how often new values are measured and how long data is stored in the corresponding data backend! Naive clients can bother data providers when trying to request huge datasets by accident. Therefore data requests may be limited to a maximum timespan (per configuration).

However, most probably consuming huge datasets may also not be of client's interest. Have a look at the paging documentation how to get data in smaller chunks.

Raw Data of multiple timeseries

POST /api/v1/timeseries/getData HTTP/1.1
Host: sensorweb.demo.52north.org
Content-Type: application/json
Accept: application/json

{
  "timespan": "PT6h/2013-08-16TZ",
  "timeseries": [
    "ts_c8ed5ddbb89c19b2e385de23eecbde98",
    "ts_ad3edeff973ab62e39f76c14f95d1e82"
  ]
}
                                
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "allTimeseries": {
    "ts_ad3edeff973ab62e39f76c14f95d1e82": {
      "values": []
    },
    "ts_c8ed5ddbb89c19b2e385de23eecbde98": {
      "values": [
        {
          "timestamp": 1376610900000,
          "value": 479
        },
        {
          "timestamp": 1376610960000,
          "value": 478.8
        },
        {
          "timestamp": 1376611020000,
          "value": 478
        },
        {
          "timestamp": 1376611080000,
          "value": 477
        },
        {
          "timestamp": 1376611140000,
          "value": 476.8
        },
        {
          "timestamp": 1376611200000,
          "value": 476
        }
      ]
    }
  }
}

Image Data of combined timeseries

POST /api/v1/timeseries/getData HTTP/1.1
Host: sensorweb.demo.52north.org
Content-Type: application/json
Accept: image/png

{
  "legend": true,
  "timespan": "P0Y0M3D/2013-01-31TZ",
  "width": 400,
  "height": 300,
  "language": "de",
  "grid": true,
  "styleOptions": {
    "ts_eafa3af4e61db76b367746980d149b7e": {
      "chartType": "line",
      "properties": {
        "color": "#0000FF",
        "lineType": "solid",
        "width": 1
      }
    },
    "ts_92385cd6fb670e886cab8e542185e847": {
      "chartType": "bar",
      "properties": {
        "color": "#2f2f2f",
        "interval": "byHour",
        "width": 0.7
      }
    }
  }
}
combinedCharts

If you are interested in the PNG output you can either parse it from your favorite programming language. For a quick review you can use Curl from command line (adapt parameters as needed, e.g. if you want a PDF report instead):

curl -X POST -d 'PASTE IN HERE YOUR POST REQUEST' \
-H "content-type:application/json" -H "accept:image/png" \
http://localhost:8080/api/v1/timeseries/getData > img.png
                                    
Add documentation for
  • measurement data
  • count data
  • text data
  • ...
Please refer to the GeoJSON specification if you need more detailed information about the geometry types used.

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/geometries application/json Lists all geometries available.
GET /api/v1/geometries/{id} application/json

Lists the geometry with id {id} .

Query Parameters

The collection can be queried by optional filter parameters.

Parameter Example Description
crs
crs=EPSG:25832

The client indicates that input geometries shall be interpreted as being referenced by the given CRS (in this case to 'EPSG:25832' (ETRS89 / UTM zone 32N)).

Per default geometries are referenced by the WGS84 CRS (precisely: CRS84, lon/lat order). If crs value differs from default, all output geometries are transformed to match the asked CRS.

Please note that some CRS switch coordinate axes. Double check axes ordering before interpreting coordinates!

Future versions of the API may provide kind of a strictXY parameter or similar to give clients more control on this.
bbox
bbox={
  "ll": {
    "type": "Point",
    "coordinates": [<x>,<y>]
  },
  "ur": {
    "type": "Point",
    "coordinates": [<x>,<y>]
  }
}

Stations within a given bounding box (in WGS84 by default). Refer to the crs parameter if a non-default CRS shall be used.

near
near={
  "center": {
    "type": "Point",
    "coordinates": [<x>,<y>]
  },
  "radius":500
}

Stations around a given point (in WGS84 by default). The radius unit is in kilometers (km). Refer to the crs parameter if a non-default CRS shall be used.

For this resource further common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Simple Collection

GET /api/v1/geometries/ HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "href": "http://localhost:8080/api/v1/geometries/platform_site_10",
    "id": "platform_site_10",
    "geometryType": "platform_site",
    "platform": {
      "id": "stationary_insitu_10",
      "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_10",
      "domainId": "http://www.52north.org/test/featureOfInterest/Heiden",
      "label": "Heiden",
      "platformType": "stationary_insitu"
    }
  },
  {
    "href": "http://localhost:8080/api/v1/geometries/platform_site_11",
    "id": "platform_site_11",
    "geometryType": "platform_site",
    "platform": {
      "id": "stationary_insitu_11",
      "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_11",
      "domainId": "http://www.52north.org/test/featureOfInterest/Münster/FE101",
      "label": "Münster/FE101",
      "platformType": "stationary_insitu"
    }
  }
]
As noted above expanded=false is the default. Setting the parameter to false explicitly will have the same effect.

Expanded Collection

GET /api/v1/geometries/?expanded=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "type": "Feature",
    "id": "platform_site_10",
    "properties": {
      "href": "http://localhost:8080/api/v1/geometries/platform_site_10",
      "id": "platform_site_10",
      "geometryType": "platform_site",
      "platform": {
        "id": "stationary_insitu_10",
        "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_10",
        "domainId": "http://www.52north.org/test/featureOfInterest/Heiden",
        "label": "Heiden",
        "platformType": "stationary_insitu"
      }
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        6.932416,
        51.826044
      ]
    }
  },
  {
    "type": "Feature",
    "id": "platform_site_11",
    "properties": {
      "href": "http://localhost:8080/api/v1/geometries/platform_site_11",
      "id": "platform_site_11",
      "geometryType": "platform_site",
      "platform": {
        "id": "stationary_insitu_11",
        "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_11",
        "domainId": "http://www.52north.org/test/featureOfInterest/Münster/FE101",
        "label": "Münster/FE101",
        "platformType": "stationary_insitu"
      }
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        7.631538,
        51.947777
      ]
    }
  }
]

Item

GET /api/v1/geometries/platform_site_12/ HTTP/1.1
  Host: sensorweb.demo.52north.org
  Accept: application/json
HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8

{
  "type": "Feature",
  "id": "platform_site_12",
  "properties": {
    "href": "http://localhost:8080/api/v1/geometries/platform_site_12",
    "id": "platform_site_12",
    "geometryType": "platform_site",
    "platform": {
      "id": "stationary_insitu_12",
      "href": "http://localhost:8080/api/v1/platforms/stationary_insitu_12",
      "domainId": "http://www.52north.org/test/featureOfInterest/Portland",
      "label": "Portland",
      "platformType": "stationary_insitu"
    }
  },
  "geometry": {
    "type": "Point",
    "coordinates": [
      -122.6819,
      45.52
    ]
  }
}

The following diagram types are available and can be set via style options:

  • line charts
  • bar charts

Styles can be used whereever a chart is rendered. It does not matter if you request an image or a report (which embeds the timeseries chart).

Line Charts

The following style properties can be set.

Property Description
lineType

The line style. Possible values are solid , dotted or dashed

width The thickness of a line as integer, dash gap, point size (dependend on the chart type to be rendered).
color A 6-digit hex color value, e.g. #5f5f5f.

Example

lineChart
{
  "chartType": "line",
  "properties": {
    "type": "dashed",
    "width": 4,
    "color": "#0000ff"
  }
}

Bar Charts

Property Description
interval The time period a bar shall represent. Possible values are byDay, byWeek, byMonth.
width Value between 0 and 1, which defines the bar width in percent (width=1 means maximum width, i.e. bar next to bar).
color A 6-digit hex color value, e.g. #5f5f5f.

Example

barChart
{
  "chartType": "bar",
  "properties": {
    "interval": "byDay",
    "width": 0.8,
    "color": "#0000ff"
  }
}

Raw data can be requested in a specific format. This can be useful if you work with a specific chart API and want to avoid to convert data outout from one format to another. Possible formats are:

  • tvp (the default)
  • highchart

To retrieve extra reference values (if available for that timeseries) valid for the requested timespan just add expand=true .

Serving arbitrary formats is limited. Most probably you have to combine timeseries metadata and the actual data differently within the used API. Please refer to the actual data output so that it can be used as intended by the 3rd party API.

Default Format

The format returns timeseries data as time-value tuples.

Example (Single Timeseries)

{
  "values": [
    {
      "timestamp": 1376524800000,
      "value": 433.0
    },
    {
      "timestamp": 1376524860000,
      "value": 432.4
    },
    {
      "timestamp": 1376524920000,
      "value": 432.0
    },
    {
      "timestamp": 1376524980000,
      "value": 431.1
    }
  ]
}

Example (Multiple Timeseries)

{
  "ts_ad3edeff973ab62e39f76c14f95d1e82": {
    "values": []
  },
  "ts_c8ed5ddbb89c19b2e385de23eecbde98": {
    "values": [
      {
        "timestamp": 1376589600000,
        "value": 546
      },
      {
        "timestamp": 1376589660000,
        "value": 546.6
      },
      {
        "timestamp": 1376589720000,
        "value": 547
      }
    ]
  }
}
Please note that when adding expanded=true , reference values will be added as a timeseries on their own. You can track reference values with the corresponding identifiers available from the timeseries metadata.

Highchart Format

The format returns timeseries data in Highcharts series format. To add metadata or a readable series name you will have to replace the timeseriesId with a readable label taken from the Timeseries metadata.

Example (Single Timeseries)

{
  "name": "ts_c8ed5ddbb89c19b2e385de23eecbde98",
  "data": [
    [
      1376524800000,
      433.3
    ],
    [
      1376524860000,
      432.4
    ],
    [
      1376524920000,
      432.1
    ]
  ]
}

Example (Multiple Timeseries)

[
  {
    "name": "ts_ad3edeff973ab62e39f76c14f95d1e82",
    "data": []
  },
  {
    "name": "ts_c8ed5ddbb89c19b2e385de23eecbde98",
    "data": [
      [
        1376589600000,
        546
      ],
      [
        1376589660000,
        546.6
      ],
      [
        1376589720000,
        547
      ],
      [
        1376589780000,
        548
      ]
    ]
  }
]

Depending on sampling resolution and timespan timeseries data can be huge. Generalizing data can make sense in more than just a low bandwidth use case (e.g. smoothing the curve).

The API supports two generalization algorithms which can be enabled by generalize=true . Default generalization behaviour is set to false (may be configurable in future). More algorithms can be added easily.

Douglas-Peucker Downsampling

  • Downsamples timeseries values by using a threshold value (Details)
  • Parameters
    • generalize=true
    • generalizing_algorithm=dp
    • tolerance_value=<double-value> (default is 0.1)

Largest-Triangle-Three Bucket Downsampling

  • Downsamples to a fix amount of output values (Details)
  • Parameters
    • generalize=true
    • generalizing_algorithm=lttb
    • threshold=<int-value> (default is 200)
Use the query parameters platformTypes and/or datasetTypes to get access to those parameters related to the given filter. To enable easy access to the most common use case (and for backwards compatibility) the default filter is set on platformTypes=stationary,insitu (and AND filter) and datasetTypes=measurement .

Services

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/services application/json Lists all services available.
GET /api/v1/services/{id} application/json Lists the service with id {id}.

Query Parameters

For this resource common query parameters can be used.

Examples

Collection

GET /api/v1/services/ HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "srv_823sd",
    "label": "PEGELONLINE"
  },
  {
    "id": "srv_8asdfd",
    "label": "Wupperverband"
  }
]

Item

GET /api/v1/services/srv_823sd HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "srv_1a5bde0a6d702f193f7be463402ec12f",
  "label": "PEGELONLINE SOS",
  "serviceUrl": "http://pegelonline.wsv.de/webservices/gis/gdi-sos",
  "version": "1.0.0",
  "type": "SOS",
  "supportsFirstLatest": true,
  "quantities": {
    "categories": 10,
    "phenomena": 10,
    "stations": 551,
    "timeseries": 740
  }
}

An expanded view gives you a bit more metadata about a service instance. It counts the amount of available resources and gives you information about the serivce's capabilities, e.g. if first and latest value requests are supported.

Categories

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/categories application/json Lists all measured categories available.
GET /api/v1/categories/{id} application/json Lists the measured categories with id {id}.

Query Parameters

For this resource common query parameters can be used.

Examples

Collection

GET /api/v1/categories HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "cat_h7234u",
    "label": "Water"
  },
  {
    "id": "cat_eddfnq",
    "label": "Air"
  }
]

Item

GET /api/v1/categories/cat_eddfnq HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "cat_eddfnq",
  "label": "Air",
  "service": {
    "id": "../services/srv_823sd",
    "label": "PEGELONLINE"
  }
}

Phenomena

URLs

API calls are triggered by using the following URLs.

Method Path Conetnet-Type Description
GET /api/v1/phenomena application/json Lists all measured phenomena available.
GET /api/v1/phenomena/{id} application/json Lists the measured phenomenon with id {id}.

Query Parameters

For this resource common query parameters can be used.

Examples

Collection

GET /api/v1/phenomena HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "phe_adsf221",
    "label": "Lufttemperatur"
  },
  {
    "id": "phe_adsf221",
    "label": "Wasserstand"
  }
]

Item

GET /api/v1/phenomena/phe_adsf221 HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "phe_adsf221",
  "label": "Wasserstand",
  "service": {
    "id": "../services/srv_823sd",
    "label": "PEGELONLINE"
  }
}
This section describe non public functionlity which may be either unstable or legacy to be kept for backward compatibility.

Offerings

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/offerings application/json Lists all offerings available.
GET /api/v1/offerings/{id} application/json Lists the offering with id {id}.

Query Parameters

For this resource common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Collection

GET /api/v1/offerings HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "off_h7234u",
    "label": "ABFLUSS_ROHDATEN"
  },
  {
    "id": "off_eddfnq",
    "label": "WINDGESCHWINDIGKEIT"
  }
]

Item

GET /api/v1/offerings/off_h7234u HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "off_h7234u",
  "label": "ABFLUSS_ROHDATEN"
  "service": "../services/srv_823sd"
}

Features

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/features application/json Lists all features available.
GET /api/v1/features/{id} application/json Lists the feature with id {id}.

Query Parameters

For this resource common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Collection

GET /api/v1/features HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "foi_h7234u",
    "label": "Bramsche"
  },
  {
    "id": "foi_adsf221",
    "label": "Suelfeld"
  }
]

Item

GET /api/v1/features/foi_h7234u HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "foi_h7234u",
  "label": "Bramsche",
  "service": {
    "id": "../services/srv_823sd",
    "label": "PEGELONLINE"
  }
}

Procedures

URLs

API calls are triggered by using the following URLs.

Method Path Content-Type Description
GET /api/v1/procedures application/json Lists all procedures available.
GET /api/v1/procedures/{id} application/json Lists the procedure with id {id}.

Query Parameters

For this resource common query parameters can be used.
Note that for GET requests the options have to be URL-encoded appropriately!

Examples

Collection

GET /api/v1/procedures HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "id": "pro_h7234u",
    "label": "Year.Cmd.MHQ"
  },
  {
    "id": "pro_adsf221",
    "label": "Bad Hersfeld 1_Q#TagMittel"
  }
]

Item

GET /api/v1/procedures/pro_adsf221 HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "pro_h7234u",
  "label": "Wasserstand-Berlin-Ploetzensee_Op_586640",
  "service": {
    "id": "../services/srv_823sd",
    "label": "PEGELONLINE"
  }
}

Timeseries

Query Parameters

The features status_intervals and rendereing_hints are now available from the /api/v1/timeseries/{id}/extras endpoint. The /api/v1/timeseries will still keep the outputs for backwards compatibility. However, clients should tend to change access how both extra information can be accessed.

Two new parameter are implemented:

Parameter Example Description
status_intervals
status_intervals=true
Information about the current status of a timeseries. A client should receive metadata how the last measured value can be interpreted by means of defined status "scales".
rendering_hints
rendering_hints=true
Responds the timeseries resource with a rendering hing, which describes how the timeseries can look like. The styling options are similar to the previous descripted Styles.

Examples

Item

GET api/v1/timeseries/ts_2395d0548435a7ab701f63e2032eaaeb?status_intervals=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  id: "ts_2395d0548435a7ab701f63e2032eaaeb",
  label: "Lufttemperatur@Barmen_Wupperverband",
  uom: "Grad Celsius",
  station: {
    properties: {
      id: "sta_254b3e34bbefac4119acd69ec76e647f",
      label: "Barmen_Wupperverband"
    },
    geometry: {
      coordinates: [
        7.204441970508681,
        51.266086785330224
      ],
      type: "Point"
    },
    type: "Feature"
  },
  referenceValues: [ ],
  firstValue: {
    timestamp: 1053934200000,
    value: 15.4
  },
  lastValue: {
    timestamp: 1371057750000,
    value: 20.3
  },
  parameters: {
    service: {
      id: "srv_738111ed219f738cfc85be0c8d87843c",
      label: "Wupperverband SOS"
    },
    offering: {
      id: "off_4f4c3d989f9cee86eb36abadaec6fcba",
      label: "Luft"
    },
    feature: {
      id: "foi_d6bea596d0a9b87cf8f7813acd480080",
      label: "Barmen_Wupperverband"
    },
    procedure: {
      id: "pro_3eb970971e126124ad0a731c2ddd4f30",
      label: "Lufttemperatur_Barmen_Wupperverband"
    },
    phenomenon: {
      id: "phe_1965ee24af8af96270002b4a434a4250",
      label: "Lufttemperatur"
    },
    category: {
      id: "cat_b43c06883f4f439241b59f28033830ad",
      label: "Lufttemperatur"
    }
  },
  statusIntervals: [
    {
      lower: "20.0",
      name: "over 20",
      color: "#FF0000"
    },
    {
      lower: "15.0",
      upper: "20.0",
      name: "15 - 20",
      color: "#BF003F"
    },
    {
      lower: "10.0",
      upper: "15.0",
      name: "10 - 15",
      color: "#7F007F"
    },
    {
      lower: "5.0",
      upper: "10.0",
      name: "5 - 10",
      color: "#3F00BF"
    },
    {
      lower: "0.0",
      upper: "5.0",
      name: "0 - 5",
      color: "#0000FF"
    }
  ]
}

Item

GET api/v1/timeseries/ts_5c305e686027a27b5c09b0e4d7397bdd?rendering_hints=true HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  id: "ts_5c305e686027a27b5c09b0e4d7397bdd",
  label: "Niederschlagshoehe@RS-Herrmannsmuehle",
  uom: "mm/h",
  station: {
    properties: {
      id: "sta_a6b8ef2480c7363d440fc299dc8841eb",
      label: "RS-Herrmannsmuehle"
    },
    geometry: {
      coordinates: [
        7.226317896922862,
        51.19657532705112
      ],
      type: "Point"
    },
    type: "Feature"
  },
  referenceValues: [ ],
  firstValue: {
    timestamp: 1149595200000,
    value: 0
  },
  lastValue: {
    timestamp: 1372892400000,
    value: 0
  },
  parameters: {
    service: {
      id: "srv_738111ed219f738cfc85be0c8d87843c",
      label: "Wupperverband SOS"
    },
    offering: {
      id: "off_f1f50366e5af4c86d57628adc67064a6",
      label: "Niederschlag"
    },
    feature: {
      id: "foi_abaac0b717c43a395b547fb9c70029d2",
      label: "RS-Herrmannsmuehle"
    },
    procedure: {
      id: "pro_40aaea656ee27e215eb6b150525875fb",
      label: "Niederschlagshoehe_RS-Herrmannsmuehle__Stundensumme"
    },
    phenomenon: {
      id: "phe_39b6c8bd9f50fc1892b407c9268cf557",
      label: "Niederschlagshoehe"
    },
    category: {
      id: "cat_dc4c2df7e0450c33a5477c6b8dafab4d",
      label: "Niederschlagshoehe"
    }
  },
  renderingHints: {
    chartType: "bar",
    properties: {
      interval: "byHour",
      width: "0.8",
      color: "#0000ff"
    }
  }
}