Skip to content

REST API

Jump to bottom
tucotuco edited this page Jul 14, 2011 · 30 revisions

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 or cell keys

Parameter Description Example
xy A longitude/latitude pair separated by a comma (",").
List of pairs separated by pipes ("|")		 xy=42.88,-0.008
xy=42.8,-0.008|42.88,-0.008
k Cell keys separated by commas (",") k=28037-11350
k=28036-11350,28037-11350
v Variable names separated by commas (",").
Omit parameter to get all variables		 v=tmax12
v=tmax10,tmax11,tmax12

Example - "Get values of tmax10, tmax11, and tmax12 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

Example JSON response

[
  {
    "cell-values":
      {"tmax10": "283", "tmax11": "289", "tmax12": "283"}, 
    "cell-coords": 
      [
        ["55.9520559", "-4.5833333"], 
        ["55.9520559", "-4.5916667"], 
        ["55.9604717", "-4.5916667"], 
        ["55.9604717", "-4.5833333"], 
        ["55.9520559", "-4.5833333"]
      ], 
    "cell-key": 
      "28037-11350"
  }
]

Example - "Get cell values for a list of variables that correspond to a list of coordinates (or cell keys)"

GET /api/cells/values?xy=1,2|7,3&v=bio1,bio2

Example JSON response

[
  {
    "coordinate": [1,2], 
    "cell-key": "1-2", 
    "cell-values": 
      [
        {"name": "bio1", "value": -50},
        {"name": "bio2", "value": -89}
      ]
  },
  {
    "coordinate": [7,3], 
    "cell-key": "2-8", 
    "cell-values": 
      [
        {"name": "bio1", "value": -22},
        {"name": "bio2", "value": 77}
      ]
  }
]

Get cell coordinates by cell key

Example - "Get the cell coordinates for cells 1-2 and 2-8"

GET /api/cells/coordinates?k=1-2,2-8

Parameter Description
k Cell keys separated by a comma (",")

Example JSON response

[
  {
    "cell-key": "1-2",
    "coordinates": 
      [
        [-122.2887875,37.8603069],
        [-122.2774275,37.8603069],
        [-122.2729888,37.8686002],
        [-122.2843488,37.8686002],
        [-122.2887875,37.8603069]
      ],
  },
  {
    "cell-key": "2-8",
    "coordinates": 
      [
        [-122.2887875,37.8603069],
        [-122.2774275,37.8603069],
        [-122.2729888,37.8686002],
        [-122.2843488,37.8686002],
        [-122.2887875,37.8603069]
      ]
  }
]

List all variables

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"
    },
    ...
  }
]

List variable by name

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

Get cells having variable within a range (Not implemented)

Example request - "Get all bio1 variable cell values that are between 0 and 10 inclusive"

GET api/cells/values?within=5&pivot=5&variable=bio1&limit=10&offset=0

Parameter Description
within Look for values within this range
pivot Look for values within range of this pivot value
variable The cell variable
limit The max number of cells to return (for paging)
offset The starting point offset of cells to return (for paging)

Example JSON response

[
  {"cell-key": "1-2", "cell-value": 8},
  ...
]

Clone this wiki locally