Web API

The following document outlines an overall design of the RESTful Web Service implemented and provided by this system for access to various underlying vector, raster and meta data.

Features of the API include:

  • Versioned Access
  • RESTful Architecture
  • Multiple Output Formats
  • Self Documenting and Traversing

Global Parameters

All endpoints accept the following optional parameter(s):

  • format representation format. – Default: json

Global Help

All endpoints accept and implement a help resource that returns a document that describes the API endpoint being requested, what it does and what data is provided. Example:

/api/v1/help

Responses

There are two types of responses. Normal responses are responses to any API endpoint that results in a valid response with data, a Help response is a response to an API endpoint’s help document describing what the API endpoint does and what data is provided by it.

Normal Responses

{
    data: [ ... ]
}

Where:

  • data is a list (possibly empty) of data returned

Help Response

A response describing the API endpoint being requested, what it does and the data provided.

Note

This can be requested in any supported format. e.g: text, html, json

Summaries

This data can be used to explore region similarities and differences in tabular or graph form.

A single “resource” is a table of data for a given intersection of region type, year, future model, and emission scenario. The resource includes summary data for every region of the given region type.

Endpoint: /summaries

Structure:

/summaries
/summaries/projections
/summaries/projections/scenario
/summaries/projections/scenario/model
/summaries/projections/scenario/model/year
/summaries/projections/scenario/model/year/region
/summaries/projections/scenario/model/year/var
/summaries/projections/scenario/model/year/var/region

Where:

  • model a climate model
  • scenario an emissions scenario
  • year a future year
  • var a specific bio-climatic variable
  • region a collection of regions to intersect against

Examples(s):

GET /api/v1/summaries/projections/scenario/model/year/region
GET /api/v1/summaries/projections/scenario/model/year/var/region

Variables

This data describes various aspects of the bio-climatic variables that are given values in the region summaries, and/or displayed as WMS layers. The data includes the variable’s description, measurement units, and maximum and minimum (across all available summaries).

A single “resource” is a set of metadata for a particular variable.

Endpoint: /variables

Structure:

/variables
/variables/var

Where:

  • var the name of a specific bio-climatic variable

Example 1:

GET /api/v1/variables

will return a list of all variables, similar to:

{
    data: [
        {
            id: "bio1",
            shortname: "Annual Precip",
            longname: "Mean Annual Precipitation",
            units: "mm",
            min: 3,
            max: 2456
        },
        {
            id: "bio2",
            shortname: "Annual Max Temp",
            longname: "Mean Annual Maximum Temperature",
            units: "C",
            min: 15,
            max: 48
        },
        ...
        { ... }
    ]
}

Example 2:

GET /api/v1/variables/bio2

Will return a similar list but containing just the specified variable:

{
    data: [
        {
            id: "bio2",
            shortname: "Annual Max Temp",
            longname: "Mean Annual Maximum Temperature",
            units: "mm",
            min: 15,
            max: 48
        }
    ]
}

Regions

This data could be used by a client to describe a particular region in detail, including a geographic rendering of the borders of the region. A single “resource” is a list of data for a given region.

Endpoint: /regions

Structure:

/regions/
/regions/collection/
/regions/collection/sub-collection
/regions/collection/sub-collection/id

Where:

  • collection is a collection.
  • subcollection is a sub-collection of regions belonging to a parent collection.
  • id is a unique region belonging to a collection/sub-collection.

Note

  • Region hierarchy can be arbitrarily nested.

Examples:

GET /api/v1/regions/
GET /api/v1/regions/collection/
GET /api/v1/regions/collection/subcollection/
GET /api/v1/regions/collection/subcollection/id

Features

Used to request and filter GeoJSON features from a vector data source such as a Shapefile <http://en.wikipedia.org/wiki/Shapefile>).

Endpoint: /features

Geometry

Used for server-side geometric operations (//buffer, intersection, union, etc//).

Endpoint: /geometry

WMS

Standard WMS service for tile rendering of Raster and Vector layers.

Endpoint: /wms

Table Of Contents

Previous topic

Data

Next topic

API Documentation

This Page