Documentation Series REST-API, Version 1

About

The 52°North Helgoland 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 Helgoland API offers a Service Provider Interface (SPI) which can be implemented to adapt arbitrary data sources.

The formally known TimeHelgoland API has been renamed to Helgoland 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

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 TimeHelgoland API to Helgoland 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: User-agent (e.g. header information) `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!

Search

The query parameter q allows simple search over resources. Note that the searching respects the current locale being selected.

Method	Path	Content-Type	Description
`GET`	`/api/v1/search?q=mySearch`	`application/json`	Searches globally over available resources.

Combined search terms are not supported with this API version.

Output Example

A search generates a result collection containing all matching resources as items. An item describes a label where search took place on, a resource type hint and a link to the resource itself.

GET /api/v1/search?q=sylt HTTP/1.1
Host: sensorweb.demo.52north.org
Accept: application/json

HTTP/1.1 200 OK

[
  {
    "id": "sta_a4bff7499d440d9bb67ad73e048c5a47",
    "label": "List_Auf_Sylt_9570070",
    "type": "station",
    "href": "./stations/sta_a4bff7499d440d9bb67ad73e048c5a47"
  },
  {
    "id": "ts_c8ed5ddbb89c19b2e385de23eecbde98",
    "label": "Wasserstand@List_Auf_Sylt_9570070",
    "type": "timeseries",
    "href": "./timeseries/ts_c8ed5ddbb89c19b2e385de23eecbde98"
  },
  {
    "id": "foi_25e09ee3155ab0fbf3e4684ad2edffbf",
    "label": "List_Auf_Sylt_9570070",
    "type": "feature",
    "href": "./features/foi_25e09ee3155ab0fbf3e4684ad2edffbf"
  },
  {
    "id": "pro_e878d48e49ebc2a156e2810470bae9a2",
    "label": "Wasserstand-List_Auf_Sylt_9570070",
    "type": "procedure",
    "href": "./procedures/pro_e878d48e49ebc2a156e2810470bae9a2"
  }
]

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
      }
    }
  }
}

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

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.

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

{
  "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

{
  "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.

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}`.

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"
    }
  }
}

About

Overview

Document status

Backwards Compatibility

What's New?

Platforms

Datasets

General

Content-Types

Common Query Parameters

Search

Output Example

Common Status Codes

Collections

URLs

Examples

Simple View

Expanded View

Platforms

URLs

Query Parameters

Examples

Simple Collection

Expanded Collection

Item

Stations

URLs

Query Parameters

Examples

Simple Collection

Expanded Collection

Item

Datasets

URLs

Request Data

Query Parameters

Examples

Simple Collection

Expanded Collection

Simple Item

Data of a single datasets

Data of multiple timeseries

Image Data of combined datasets

Timeseries

URLs

Request Data

Query Parameters

Examples

Simple Collection

Expanded Collection

Simple Item

Data of a single timeseries

Raw Data of multiple timeseries

Image Data of combined timeseries

Data

Geometries

URLs

Query Parameters

Examples

Simple Collection

Expanded Collection

Item

Diagram Styles

Line Charts

Example

Bar Charts

Example

Data Formats

Default Format

Example (Single Timeseries)

Example (Multiple Timeseries)

Highchart Format

Example (Single Timeseries)

Example (Multiple Timeseries)

Generalization

Douglas-Peucker Downsampling

Largest-Triangle-Three Bucket Downsampling

Parameters

Services

URLs