Skip to content

Sensor Discovery API Documentation

Jump to bottom
liangsteve edited this page Aug 27, 2013 · 14 revisions

Introduction

The Sensor Discovery API provides a web service allowing applications to access to our OGC Web Service database through a REST-like web API. Using this API, you can search for SOS, SPS, and WMS layers that we have catalogued, and integrate this data with your own applications.

Get Started (Get API Key)

To use the API, you will need to register an account. Next, you must activate the API Key for you account. You can do this from your account page, by clicking "Generate API Key". The page will reload, and your 20-character Search API Key will be displayed. Do not share this key, as it is tied to your account only. If you believe your key has been compromised, you can reset or clear your key from your account page.

After you have your key, you may access the Sensor Discovery API. Please refer to the API reference documentation below for details on how to access the API.

API Documentation

Queries to the Sensor Discovery API are made using HTTP GET requests to a specific URL. For the following examples, apikey is assumed to be a valid API key. In your use, you should substitute the API key you generated from your account page.

The API responds in JSON format. For example, retrieving a layer may produce this response:

{
  "layers": [
    {
      "service_title": "GSW SOS",
      "service_type": "SOS",
      "property": "urn:ogc:def:phenomenon:OGC:1.0.30:Temperature",
      "service_provider": "Dept. of Geomatics Engineering, University of Calgary",
      "bbox": "-22.017000198364258,-177.75,71.29000091552734,179.2169952392578",
      "domain": "gsw.geocens.ca:9182",
      "service_rank": "2",
      "short_name": "Temperature",
      "service_url": "http://gsw.geocens.ca:9182/GSWSOSTJSv1NOAA2d/sos",
      "name": "urn:ogc:def:phenomenon:OGC:1.0.30:Temperature",
      "offering": "NOAA_Weather",
      "service_name": "http://gsw.geocens.ca:9182/GSWSOSTJSv1NOAA2d/sos"
    }
  ],
  "message": ""
}

Using the API can be broken down into some useful scenarios. These will cover what to expect from using the API.

Scenario: Retrieve layers for a keyword

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=temperature&api_key=apikey
  • Then the response should be 200
  • And the response should have an array of layers

###Scenario: Retrieve layers for a keyword with a spatial boundary

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=temperature&bbox=35.079,-114.132,51.081,-114.152,51.073,-114.149,35.074,-114.118,51.082,-114.125&api_key=apikey
  • Then the response should be 200
  • And the response should have an array of layers
  • And the layers should be in the bounding box 35.079,-114.132,51.081,-114.152,51.073,-114.149,35.074,-114.118,51.082,-114.125

###Scenario: Retrieve WMS layers for a keyword

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=wms:temperature&api_key=apikey
  • Then the response should be 200
  • And the response should have an array of layers
  • And all the layers should be WMS

###Scenario: Retrieve SPS layers for a keyword

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=sps:temperature&api_key=apikey
  • Then the response should be 200
  • And the response should have an array of layers
  • And all the layers should be SPS

###Scenario: Display message for no results for a keyword

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=empty&api_key=apikey
  • Then the response should be 200
  • And I should receive no layers
  • And the response should have a No results for keyword message

###Scenario: Retrieve limited layers for a keyword

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=temperature&limit=10&api_key=apikey
  • Then the response should be 200
  • And the response should have an array of 10 layers

###Scenario: Retrieve limited layers with an offset for a keyword

  • Given there are "18" layers for the keyword temperature
  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=temperature&limit=10&offset=10&api_key=apikey
  • Then the response should be 200
  • And the response should have an array of 8 layers

###Scenario: Retrieve a layer by its UID

  • Given I know a layer with the following attributes: ** URL: http://firefly.geog.umd.edu/wms/wms and offeringId: fires24
  • When I md5 http://firefly.geog.umd.edu/wms/wms|fires24
  • Then I should get the hash e863d8fe1fc5a8d913b0e7ebaccace66
  • When I send a GET request for http://dev.geocens.ca/api/v1/layers/e863d8fe1fc5a8d913b0e7ebaccace66?api_key=apikey
  • Then the response should be 200
  • And the response should have a layer
  • And the layer should have attributes: ** URL: http://firefly.geog.umd.edu/wms/wms; offeringId: fires24; ServiceType: wms; LayerName: Fires - Past 24 hours; and UID: e863d8fe1fc5a8d913b0e7ebaccace66

###Scenario: Exceeding query rate displays error

  • When I issue more than one GET request per second
  • Then the response should be 403
  • And the response should have a 403 Forbidden (Rate Limit Exceeded) message

###Scenario: Exceeding query limit displays error

  • When I issue more than 360 GET requests per hour
  • Then the response should be 403
  • And the response should have a 403 Forbidden (Rate Limit Exceeded) message

###Scenario: Displays an error when the Sensor Discovery RPI database is unavailable

  • Given the Sensor Discovery RPI database is unavailable
  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=empty&api_key=apikey
  • Then the response should be 504
  • And I should receive no layers
  • And the response should have a Search service unavailable message

###Scenario: Display error message for missing API key

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=temperature
  • Then the response should be 401
  • And the response should have a 401 Unauthorized (Missing API Key) message

###Scenario: Display error message for invalid API key

  • When I send a GET request for http://dev.geocens.ca/api/v1/layers?keyword=temperature&api_key=fakekey
  • Then the response should be 401
  • And the response should have a 401 Unauthorized (Invalid API Key) message

#Service Level Agreement ##Request Limits

  • We current limit each application issuing maximum 360 request per hour.

Clone this wiki locally