GeoCENS API Reference

Queries to the GeoCENS API are made using HTTP GET requests to specific URLs on the GeoCENS site. For the following examples, apikey is assumed to be a valid GeoCENS 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 attributes:
    URLofferingId
    http://firefly.geog.umd.edu/wms/wmsfires24
  • 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 offeringId ServiceType LayerName UID
    http://firefly.geog.umd.edu/wms/wms fires24 wms Fires - Past 24 hours 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 GeoCENS OWS database is unavailable

  • Given the GeoCENS OWS 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