Sensor Web Client, RESTful API Version 0

The following sections provide example links (3 links each) explaining the API. The first link describes the generic form, while the second one links to examples on our deployed demo server. The third link gives developers a quick access to their locally running tomcat instance (on port 8080). The demo instance mostly represents the most up-to-date version.

There is a client explorer consuming the REST API and displays the data in a more human readable format.

Resource URLs

Service Instances

Get an array of all configured SOS instances.

Generic Form:

• GET /api/v0/services
• GET /api/v0/services/<serviceInstance>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services.json

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE.json

Stations

Get an array of all stations available from a configured SOS instance.

Generic Form:

• GET /api/v0/services/<serviceInstance>/stations
• GET /api/v0/services/<serviceInstance>/stations/<stationId>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/stations.json

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations/Bingen_25300200.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/stations/Bingen_25300200.json

Filter Examples: You can filter stations to get only those stations which include a particular parameter (offering, feature, procedure, or phenomenon)

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json?offering=WASSERTEMPERATUR
• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json?phenomenon=Wasserstand
• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json?phenomenon=Wasserstand&feature=Bingen_25300200
• Examples of a spatial filter (radius is in KM):
  • http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json?within={"center":[7,52.5],"radius":500}

Phenomenons

Get an array of all phenomenons available from a configured SOS instance.

Generic Form:

• GET /api/v0/services/<serviceInstance>/phenomenons
• GET /api/v0/services/<serviceInstance>/phenomenons/<phenomenonId>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/phenomenons.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/phenomenons.json

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/phenomenons/Wasserstand.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/phenomenons/Wasserstand.json

Offerings

Get an array of all offerings available from a configured SOS instance.

Generic Form:

• GET /api/v0/services/<serviceInstance>/offerings
• GET /api/v0/services/<serviceInstance>/offerings/<offeringId>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/offerings.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/offerings.json

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/offerings/WASSERTEMPERATUR.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/offerings/WASSERTEMPERATUR.json

Procedures

Get an array of all procedures available from a configured SOS instance.

Generic Form:

• GET /api/v0/services/<serviceInstance>/procedures
• GET /api/v0/services/<serviceInstance>/procedures/<procedureId>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/procedures.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/procedures.json

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/procedures/Wasserstand-Bingen_25300200.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/procedures/Wasserstand-Bingen_25300200.json

Features

Get an array of all features available from a configured SOS instance.

Generic Form:

• GET /api/v0/services/<serviceInstance>/features
• GET/api/v0/services/<serviceInstance>/features/<FeatureId>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/features.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/features.json

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/features/Bingen_25300200.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/features/Bingen_25300200.json

Timeseries Data

Timeseries data can be retrieved in either pre-rendered image files or as raw data. Single and multiple timeseries can be retrieved in one request. When image/png is accepted multiple timeseries get rendered as one timeseries graph (with random colors).

While a pre-rendered image does guarantee a constant size of transferred data the raw data (as json) can be used for custom timeseries rendering or even processing on client side. Note, that requesting multiple timeseries with a large timespan may result in large traffic throughput. If this is an issue, and pre-rendered timeseries graphs are sufficient we recommend to request image data. However, this are older experiences we made. A performance test on current browser engines to verify if this is still an issue is an open task.

Get Overview of Timeseries available

Generic Form:

• GET /api/v0/services/<serviceInstance>/timeseries
• GET /api/v0/services/<serviceInstance>/timeseries/<timeseriesId>

Collection Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/timeseries.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/timeseries.json

Get Raw Data

Generic Form:

• GET /api/v0/services/<serviceInstance>/timeseries
• GET/api/v0/services/<serviceInstance>/timeseries/<timeseriesId>
• POST /api/v0/timeseries (to request multiple timeseries)
• POST /api/v0/timeseries/<serviceInstance> (to request multiple timeseries)

Individuum Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/timeseries/ts_2b292cda999ab155c8777629bb87736f.json
• http://localhost:8080/sensorwebclient-webapp/api/v0/services/PEGELONLINE/timeseries/ts_2b292cda999ab155c8777629bb87736f.json

Request Multiple Timeseries: Multiple timeseries data from different data sources (configured SOS instances) can be retrieved. The request context is not bound to one service instance as the examples above. The POST endpoints are

• • http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/timeseries
  • http://localhost:8080/sensorwebclient-webapp-stable/api/v0/timeseries

To retrieve data the following information has to be sent to the HTTP POST endpoints (note: set the Accept request header to application/json):

{
    "timespan": "PT6h/2013-05-28TZ",
    "timeseries": [
        "ts_46d3a18491aee6ae456bc80733b66903",
        "ts_f8ce3a93a6d7b7634b512cd164345991",
        "ts_60d531379494324f27589573b27acd1c"
    ]
}

The timespan is an ISO8601 interval (excluding the period only option). As noted above the =timeseriesId=s can be provided by different SOS instances.

Get image data

If raw timeseries is not of interest, pre-rendered graph can be requested instead which can be shown easily by the client as normal image. The POST endpoints are

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/timeseries
• http://localhost:8080/sensorwebclient-webapp-stable/api/v0/timeseries

To keep reference to the requested set of timeseries and the actual output the client can add rendering options like colors or different line widths (note: set the Accept request header to image/png):

{
    "timespan": "PT6h/2013-05-28TZ",
    "width": 300,
    "height": 200,
    "timeseries": {
        "ts_46d3a18491aee6ae456bc80733b66903": {
            "hexColor": "#FF0000",
            "lineWidth": 1
        },
        "ts_60d531379494324f27589573b27acd1c": {
            "hexColor": "#00FF00",
            "lineWidth": 2
        },
        "ts_f8ce3a93a6d7b7634b512cd164345991": {
            "hexColor": "#0000FF",
            "lineWidth": 3
        }
    }
}

Each requested color can be included in a legend so that the user can keep reference which timeseries has what color on the graph (if no color is given a random color will be chosen).

The timespan (optional) is an ISO8601 interval (excluding the period only option). The size (optional) is in =<width>,<height> pixels.

Paging

Each result can be paged by adding KVP parameters offset (mandatory) and size (optionally: if missing a default value will be used).

Examples:

• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json?offset=0&size=5 (The first five stations of the PEGELONLINE instance)
• http://sensorweb.demo.52north.org/sensorwebclient-webapp-stable/api/v0/services/PEGELONLINE/stations.json?offset=10&size=20 (twenty stations starting from 10th until 29th station)