REST API

Spatial Data Library (SDL) REST API

What is the Spatial Data Library

The Spatial Data Library is a web service to retrieve Worldclim (Hijmans et al. 2006) variables from a high-performance data store.

Get cells from coordinates, cell keys, bounding box, or variable value ranges

http://canary.geo-ds.appspot.com/api/cells/values?r=alt,400,500

Parameter	Description	Example
xy	Get cells from lon/lat pairs, separated by commas (",") with pairs separated by pipes ("|").	xy=42.88,-0.008 xy=42.8,-0.008|42.88,-0.008
k	Cell keys to get, separated by commas (",")	k=28037-11350 k=28036-11350,28037-11350
v	Show variables in response. Names separated by commas (",") or omit for all variables.	v=tmax12 v=tmax10,tmax11,tmax12
c	Show coordinates in response if true.	c=true
si	Converts variable values to SI units if true.	si=true
bb	Return cells within a bounding box (encoded as north,west|south,east). If bb is present, k and xy are ignored.	bb=-122,40|-116,34
bb_offset	The offset for paging a bounding box request.	bb_offset=5335-6000
offset	The offset for paging.	offset=100
limit	The limit for paging.	limit=10
gte	Greater than or equal value for a range query.	gte=10
lt	Less than value for a range query.	lt=100
var	Variable for a range query (current alt, bio1, bio12 are supported)	var=alt
r	Returns cells within a range (alt, bio1, bio12 are currently supported)	r=alt,100,200 r=alt,100,200&r=bio1,20,40

Example

Get 3 cells for variable alt greater than or equal to 0 and less than 256 (between 0 and 255) with at most 3 results.

/api/cells/values?var=alt&gte=0&lt=256&limit=3

Example JSON response

[
  {
    "cell_key":"4369-4956",
    "cell_values":{
      "alt":71
    }
  },
  {
    "cell_key":"4369-4957",
    "cell_values":{
      "alt":67
    }
  },
  {
    "cell_key":"4370-4956",
    "cell_values":{
      "alt":100
    }
  }
]

Example

Get 3 cells for variable alt within a bounding box starting at cell key 5335-6000.

/api/cells/values?bb=-122,40|-116,34&v=alt&bb_offset=5335-6000&limit=3

Example JSON response

{
  "cells":[
    {
      "cell_key":"5335-6000",
      "cell_values":{
        "alt":436
      }
    },
    {
      "cell_key":"5337-6000",
      "cell_values":{
        "alt":480
      }
    },
    {
      "cell_key":"5336-6000",
      "cell_values":{
        "alt":495
      }
    }
  ],
  "offset_cell_key":"5338-6000"
}

###Example Get values of tmax10, tmax11, and tmax12 converted to SI units for the cell having key '28037-11350' and include the coordinates for the cell in the response.

GET /api/cells/values?k=28037-11350&v=tmax10,tmax11,tmax12&c=true&si=true

Example JSON response

[
  {
    "cell_key":"28037-11350",
    "cell_coords":[
      [
        "55.9520559",
        "-4.5833333"
      ],
      [
        "55.9520559",
        "-4.5916667"
      ],
      [
        "55.9604717",
        "-4.5916667"
      ],
      [
        "55.9604717",
        "-4.5833333"
      ],
      [
        "55.9520559",
        "-4.5833333"
      ]
    ],
    "cell_values":{
      "tmax12":28.3,
      "tmax11":28.9,
      "tmax10":28.3
    }
  }
]

###Example Get values of all variables for the cells at geographic locations lon/lat -123,39 and -123,38 and do not include the coordinates or SI conversions for the cell in the response.

GET /api/cells/values?xy=-123,39|-123,38

Example JSON response

[
  {
    "cell_key":"5308-6120",
    "cell_values":{
      "bio3":50,
      "alt":803,
      "bio1":116
    }
  },
  {
    "cell_key":"5381-6240",
    "cell_values":{
      "bio3":58,
      "alt":38,
      "bio1":126
    }
  }
]

List all variables or get variable by name

Note: Not implemented yet. ###Example List all variables.

GET /api/variables

Example JSON response

[
  {
    "bio1": {
      "maxval": 293,
      "name": "Annual Mean Temperature",
      "created": "2006-01-04 00:00:00",
      "minval": -50,
      "datum": "WGS84",
      "database": "WorldClim",
      "version": "1.4",
      "key": "bio1",
      "release": 3,
      "projection": "Geographic"
    },
    ...
  }
]

###Example List metadata for variable bio1.

GET /api/variables/bio1

Example JSON response

{
  "maxval": 293,
  "name": "Annual Mean Temperature",
  "created": "2006-01-04 00:00:00",
  "minval": -50,
  "datum": "WGS84",
  "database": "WorldClim",
  "version": "1.4",
  "key": "bio1",
  "release": 3,
  "projection": "Geographic"
}