API Reference

City

These endpoints allow users to list, view details of, search and retrieve the boundaries for the locations for which we have climate projections.

A City object is a point feature of the center-most geographic coordinate of an administrative boundary. Each City is associated to a map_cell, a 25 km^2 slice of the Earth’s surface. The API breaks up global climate projections by map_cell. Nearby cities, meaning being within the same map_cell, can be expected to experience the same climate.

At this time, only US cities and their climate projection data are available.

Note

Paginated city endpoints are GeoJson paginated.

List Cities

GET /api/city/

List all available cities as a GeoJson paginated GeoJson Feature Collection

Query Parameters:
 
  • page (integer) – Page of paginated results to return
  • page_size (integer) – The maximum number of returned cities per page
  • ordering (string) – Sort results by the requested field(s). Can be any combination of name|admin|population|region separated by commas. Prefix a field name with ‘-‘ to reverse sort. For example, ‘admin,-population’ would sort by admin, then by population descending.
  • admin (string) – Filter results to cities where admin contains the provided value
  • name (string) – Filter results to cities where name contains the provided value
  • search (string) – Filter results to cities matching the string search query
  • population_gte (integer) – Filter results to cities with population greater than or equal to the provided value
  • population_lte (integer) – Filter results to cities with population less than or equal to the provided value
  • region (integer) – Filter results to the provided region ID
  • in_bbox (string) – Filter results to the provided bounding box using the format ‘minlon,minlat,maxlon,maxlat’
Status Codes:
  • 200 OK – A GeoJson paginated GeoJson Feature Collection of City objects. See City model definition.

Example usage

GET /api/city/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "type": "FeatureCollection",
    "count": 1,
    "next": "http://example.org/api/city/?page=2",
    "previous": null,
    "features": [
        {
            "id": 1,
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -74.00597,
                    40.71427
                ]
            },
            "properties": {
                "datasets": ["NEX-GDDP", "LOCA"],
                "proximity": {
                    "ocean": true
                },
                "name": "New York City",
                "admin": "NY",
                "population": 8175133
            }
        }
    ]
}

Nearest city or cities

GET /api/city/nearest/

Return the nearest city or cities to the provided lat/lon as a GeoJSON Feature Collection. Default to nearest 1 city unless otherwise specified by the limit parameter.

Query Parameters:
 
  • lat (number) – Search latitude
  • lon (number) – Search longitude
  • limit (integer) – The maximum number of cities to be returned by the query
Status Codes:
  • 200 OK – A GeoJson paginated GeoJson Feature Collection of City objects

Example usage

GET /api/city/nearest/?lat=40&lon=285 HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "type": "FeatureCollection",
    "count": 1,
    "next": null,
    "previous": null,
    "features": [
        {
            "id": 2,
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -75.16379,
                    39.95233
                ]
            },
            "properties": {
                "datasets": ["NEX-GDDP", "LOCA"],
                "proximity": {
                    "coastal": false
                }
                "name": "Philadelphia",
                "admin": "PA",
                "population": 1526006
            }
        }
    ]
}

Request city

GET /api/city/{pk}/

Look up a particular city by primary key

Parameters:
  • pk (string) – Primary key of the city
Status Codes:

Example usage

GET /api/city/2/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "id": 2,
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            -75.16379,
            39.95233
        ]
    },
    "properties": {
        "datasets": ["NEX-GDDP", "LOCA"],
        "proximity": {
            "ocean": false
        },
        "name": "Philadelphia",
        "admin": "PA",
        "population": 1526006
    }
}

Get city boundary

GET /api/city/{pk}/boundary/

Return the boundary of the specified city as a MultiPolygon GeoJson Feature.

Parameters:
  • pk (string) – Primary key of the city
Status Codes:

Example usage

GET /api/city/2/boundary/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "type": "Feature",
    "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [
                        0,
                        0
                    ]
                ]
            ]
        ]
    }
}

Get city map cells

These endpoints expose the underlying grid point used for each city and dataset combination. A grid point maps to a grid cell from the source NetCDF dataset.

Retrieve all available map cells for a given city.

GET /api/city/{pk}/map-cell/

Return the list of valid map cells for this city along with the datasets they belong to.

Parameters:
  • pk (string) – Primary key of the city
Status Codes:
  • 200 OK – List of map cells valid for the city as a list of GeoJson Point features
  • 404 Not Found – No valid map cells

Example usage

GET /api/city/2/map-cell/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [0,0]
        },
        "properties": {
            "dataset": "NEX-GDDP"
        }
    }, {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [1,1]
        },
        "properties": {
            "dataset": "LOCA"
        }
    }
]

Retrieve the map cell for a particular city and dataset combination.

GET /api/city/{pk}/map-cell/{dataset}/

Return the map cell for the requested combination of city and dataset.

Parameters:
  • pk (string) – Primary key of the city
  • dataset (string) – A string dataset name as retrieved by the dataset endpoint
Status Codes:
  • 200 OK – The map cell valid for the requested city and dataset as a GeoJson Point feature
  • 404 Not Found – No valid map cell

Example usage

GET /api/city/2/map-cell/LOCA/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [1,1]
    },
    "properties": {
        "dataset": "LOCA"
    }
}

Dataset

The Climate Dataset endpoints describe the datasets available in the Climate API. Currently the API serves data from two datasets:

The “name” attribute of a dataset response can be used in other requests to specify which dataset to source results from.

Climate Dataset List

GET /api/dataset/

Lists all climate datasets available via the Climate API

Status Codes:
  • 200 OK – A list of ClimateDataset objects

Example usage

GET /api/dataset/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "name": "NEX-GDDP",
        "label": "Nasa Earth Exchange Global Daily Downscaled Projections",
        "description": "The NASA Earth Exchange (NEX) Global Daily Downscaled Projections (NEX-GDDP) dataset is comprised of downscaled climate scenarios that are derived from the General Circulation Model (GCM) runs...",
        "url": "https://nex.nasa.gov/nex/projects/1356/",
        "models": [
            "ACCESS1-0",
            "BNU-ESM",
            "CCSM4",
            "..."
        ]
    }, {
        "name": "LOCA",
        "label": "Localized Constructed Analogs Downscaled Projections",
        "description": "The LOCA (Localized Constructed Analogs) dataset includes downscaled projections from 32 global climate models calculated for two Representative Concentration Pathways (RCP 4.5 and RCP 8.5). Each of the climate projections includes daily maximum temperature, minimum temperature, and precipitation for every 6x6km (1/16th degree resolution) for the conterminous US from 1950 to 2100. LOCA attempts to better preserve extreme hot days, heavy rain events and regional patterns of precipitation. The total dataset size is approximately 10 TB.",
        "url": "http://loca.ucsd.edu/",
        "models": [
            "ACCESS1-0",
            "ACCESS1-3",
            "CCSM4",
            "..."
        ]
    }
]

Climate Dataset Detail

GET /api/dataset/{name}/

Get information about a single ClimateDataset

Parameters:
  • name (string) – Name of climate dataset
Status Codes:

Example usage

GET /api/dataset/LOCA/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "name": "NEX-GDDP",
    "label": "Nasa Earth Exchange Global Daily Downscaled Projections",
    "description": "The NASA Earth Exchange (NEX) Global Daily Downscaled Projections (NEX-GDDP) dataset is comprised of downscaled climate scenarios that are derived from the General Circulation Model (GCM) runs...",
    "url": "https://nex.nasa.gov/nex/projects/1356/",
    "models": [
        "ACCESS1-0",
        "BNU-ESM",
        "CCSM4",
        "CESM1-BGC"
    ]
}

Climate Model

The Climate Model endpoints describe the models used to generate the temperature and precipitation data provided by the Climate API.

These climate models are provided by a variety of research institutions around the globe, and all follow the CMIP5 model output specification.

Climate Model List

GET /api/climate-model/

Lists all climate models available via the Climate API

Status Codes:
  • 200 OK – A list of ClimateModel objects

Example usage

GET /api/climate-model/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "datasets": [
            "NEX-GDDP",
            "LOCA"
        ],
        "name": "ACCESS1-0",
        "label": "ACCESS1-0",
        "base_time": null,
    },
    {
        "datasets": [
            "NEX-GDDP"
        ],
        "name": "BNU-ESM",
        "label": "BNU-ESM",
        "base_time": null
    }
]

Climate Model Detail

GET /api/climate-model/{name}/

Get information about a single Climate Model

Parameters:
  • name (string) – Name of climate model
Status Codes:
  • 200 OK – ClimateModel object

Example usage

GET /api/climate-model/ACCESS1-0/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "datasets": [
        "NEX-GDDP",
        "LOCA"
    ],
    "name": "ACCESS1-0",
    "label": "ACCESS1-0",
    "base_time": null
}

Scenario

The Scenario endpoints describe the Representative Concentration Pathways (RCPs) defined by the fifth IPCC Assessment Report that this API supports.

These RCPs define greenhouse gas concentrations over time based upon a few different future scenarios of anthropogenic (human-caused) greenhouse gas emissions.

Scenario List

GET /api/scenario/

Lists all scenarios available via the Climate API

Status Codes:
  • 200 OK – A list of Scenario objects

Example usage

GET /api/scenario/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json


[
    {
        "name": "RCP85",
        "label": "RCP 8.5",
        "description": "Rising radiative forcing pathway leading to 8.5 W/m2 in 2100. See https://www.skepticalscience.com/rcp.php",
        "alias": "High emissions"
    },
    {
        "name": "historical",
        "label": "Historical",
        "description": "A historical dataset from 1950 to 2005 that blends reanalysis data with observations",
        "alias": ""
    }
]

Scenario Detail

GET /api/scenario/{name}/

Get information about a single Scenario

Parameters:
  • name (string) – Name of scenario
Status Codes:

Example usage

GET /api/scenario/RCP85/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "name": "RCP85",
  "label": "RCP 8.5",
  "description": "Rising radiative forcing pathway leading to 8.5 W/m2 in 2100. See https://www.skepticalscience.com/rcp.php"
}

Climate Data

The Climate Data endpoint allows interaction with annual sets of raw projected temperature and precipitation data for any one city and scenario.

Note

Requests to this endpoint are rate-limited.

Climate data

GET /api/climate-data/{city}/{scenario}/

Daily data aggregated across all or specified models for a city and scenario. All query parameters are optional.

Parameters:
  • city (string) – Primary key of city
  • scenario (string) – Scenario name
Query Parameters:
 
  • models (string) – A list of comma separated model names. Defaults to all models.
  • variables (string) – A list of comma separated variables. Available values are “tasmax”, “tasmin” and “pr”. Defaults to all variables.
  • years (string) – A list of comma separated year ranges. A year range is of the form “start[:end]”, inclusive. Examples: “2010”, “2010:2020”, “2010:2020,2030”, “2010:2020,2030:2040”. Defaults to all years available.
  • agg (string) – Get the minimum, maximum, or average of projected data across the included models. Options as: min, max, avg.
  • dataset (string) – Choose which provider to use for climate projection data. Defaults to NEX-GDDP
Status Codes:

Example usage

GET /api/climate-data/1/RCP85/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

Note

The general format of the response data are objects where the keys are date strings in YYYY-MM-DD format, and the value is an array that always contains 366 values. The value at a given index in the array corresponds to the value for that day of the year. Nulls are days with no data. A null in the 366th position indicates a non-leap year. For simplicity, the data below has been truncated.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "city": {
        "id": 1,
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -74.00597,
                40.71427
            ]
        },
        "properties": {
            "datasets": [
                "NEX-GDDP"
            ],
            "proximity": {
                "ocean": true
            },
            "name": "New York City",
            "admin": "NY",
            "population": 8175133
        }
    },
    "dataset": "NEX-GDDP",
    "scenario": "RCP85",
    "climate_models": [
        "ACCESS1-0",
        "BNU-ESM"
    ],
    "variables": [
        "tasmax",
        "pr",
        "tasmin"
    ],
    "data": {
        "2050": {
            "tasmax": [
                279.064025878906,
                281.310546875,
            ],
            "tasmin": [
                271.326614379883,
                273.004791259766
            ],
            "pr": [
                0.0000122705498775133,
                0
            ]
        }
    }
}

Indicator

The Indicator endpoints detail all of the derived data “indicators” that are available. The indicators provided by the Climate API are derived quantities generated using the same raw data provided by Climate Data. For a full list and high-level explanation of indicators, see the indicators dictionary.

To get indicator data, query for the Indicator list, get specific Indicator params through Indicator detail, and finally customize your Indicator data request.

If you have ideas for Indicators that aren’t provided by the Climate API, but might like to add, please contact us.

Indicator List

Get the full list of indicators from the API.

GET /api/indicator/

Lists all available indicators

Status Codes:
  • 200 OK – A list of Indicator objects

Example usage

GET /api/indicator/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "name": "example_temperature_indicator",
        "label": "Example Temperature Indicator",
        "description": "Simplified indicator to demonstrate the response format",
        "valid_aggregations": [
            "yearly",
            "monthly"
        ],
        "variables": [
            "tasmax",
            "tasmin"
        ],
        "available_units": [
            "C",
            "K",
            "F"
        ],
        "default_units": "F",
        "parameters": [
            {
                "name": "example",
                "description": "Example parameter",
                "required": false,
                "default": false
            }
        ]
    }
]

Indicator Detail

Get the description and parameters of a specified indicator.

GET /api/indicator/{indicator_name}/

Returns requested indicator

Parameters:
  • indicator_name (string) – Indicator name
Status Codes:
  • 200 OK – An Indicator object
  • 404 Not Found – Returned when requested indicator name cannot be found

Example usage

GET /api/indicator/example_temperature_indicator/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "name": "example_temperature_indicator",
    "label": "Example Temperature Indicator",
    "description": "Simplified indicator to demonstrate the response format",
    "valid_aggregations": [
        "yearly",
        "monthly"
    ],
    "variables": [
        "tasmax",
        "tasmin"
    ],
    "available_units": [
        "C",
        "K",
        "F"
    ],
    "default_units": "F",
    "parameters": [
        {
            "name": "example",
            "description": "Example parameter",
            "required": false,
            "default": false
        }
    ]
}

Indicator Parameters

Indicator object(s) are returned by Indicator list and Indicator detail. The Indicator object describes all query parameters available for that indicator. Each parameter in the Indicator.parameters array is an object with the form:

IndicatorParam

Definition object for Indicator query parameters

Object Properties:
 
  • name (string) – The name of the query parameter
  • description (string) – A detailed description of how to use the query parameter for indicator data requests, along with its available values if appropriate
  • required (boolean) – If true, this query parameter is required
  • default (string) – If the query parameter is not required, the default value used when none is provided

These parameters can be used to tweak the Indicator data request for any indicator.

To see this in action, step through how to make an indicator request.

Special Parameters Explained

The Climate API allows for various pre-defined and custom types of time_aggregation when requesting indicator data. Most are familiar, i.e. yearly. A unique format available is offset_yearly, which counts a year starting from the summer solstice (180 days into the Gregorian year). This captures seasons in their entirety, making seasonal analysis easy.

Indicator Data

Returns data for a specified indicator and its unique required and optional query parameters. See Indicator detail for more information about how to get these parameters.

Note

Requests to this endpoint are rate-limited.

GET /api/climate-data/{city}/{scenario}/indicator/{indicator_name}/

Retrieves derived climate indicator data for the requested indicator

Parameters:
  • city (string) – City ID
  • scenario (string) – Scenario name
  • indicator_name (string) – Indicator name
Status Codes:
  • 200 OK – Indicator data
  • 400 Bad Request – Returned when at least one of the query parameters is misconfigured or missing. The response will contain a detailed message.
  • 429 Too Many Requests – Returned when the request is rate-limited. The response will detail when the request can be retried.

Example usage

GET /api/climate-data/1/RCP85/indicator/example_temperature_indicator/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "city": {
        "id": 2,
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -74.00597,
                40.71427
            ]
        },
        "properties": {
            "datasets": [
                "NEX-GDDP"
            ],
            "proximity": {
                "ocean": true
            },
            "name": "New York City",
            "admin": "NY",
            "population": 8175133
        }
    },
    "dataset": "NEX-GDDP",
    "scenario": "RCP85",
    "indicator": {
        "name": "example_temperature_indicator",
        "label": "Example Temperature Indicator",
        "description": "Simplified indicator to demonstrate the response format",
        "valid_aggregations": [
            "yearly",
            "monthly"
        ],
        "variables": [
            "tasmax",
            "tasmin"
        ],
        "available_units": [
            "C",
            "K",
            "F"
        ],
        "default_units": "F",
        "parameters": [
            {
                "name": "example",
                "description": "Example parameter",
                "required": false,
                "default": false
            }
        ]
    },
    "climate_models": [
        "ACCESS1-0",
        "BNU-ESM",
    ],
    "time_aggregation": "yearly",
    "units": "F",
    "data": {
        "2050": {
            "max": 102.70332763671914,
            "avg": 97.22591587611635,
            "min": 92.67451293945382
        }
    }
}

Region

These endpoints allow users to list, view details of, search, and retrieve the boundaries for the locations for which we have climate projections.

A Region object is a multipolygon feature of an ecoregion.

List Regions

GET /api/region/

List all available regions as a paginated collection

Query Parameters:
 
  • limit (integer) – The maximum number of regions to return
  • offset (integer) – Number of regions to skip when paginating
  • search (string) – String to search level1 and level2 descriptions with
  • level1 (integer) – Filter by level1 values
  • level2 (integer) – Filter by level2 values
Status Codes:
  • 200 OK – A paginated collection of Region objects. See Region model definition.

Example usage

GET /api/region/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "count": 51,
    "next": "http://example.org/api/region/?offset=1",
    "previous": null,
    "results": [
        {
            "id": 1,
            "level1": 12,
            "level1_description": "SOUTHERN SEMIARID HIGHLANDS",
            "level2": 1,
            "level2_description": "WESTERN SIERRA MADRE PIEDMONT"
        }
    ]
}

Request region

GET /api/region/{pk}/

Look up a particular region by primary key

Parameters:
  • pk (string) – Primary key of the region
Query Parameters:
 
  • format (string) – Output format. Either json or pbf. Can also be used as file suffix, such as example.org/api/region/30.pbf. The api format is used to show the DRF UI.
Status Codes:

Example usage

GET /api/region/30/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "geometry": {
        "coordinates": [
            [
                [
                    [
                        -109.78794642794765,
                        24.150443522643897
                    ],
                    [
                        -109.79081866386304,
                        24.139997712991548
                    ],
                ]
            ],
            [
                [
                    [
                        -110.13559035042405,
                        24.241837359104423
                    ],
                    [
                        -110.08459913211541,
                        24.2138681608711
                    ],
                ]
            ]
        ],
        "type": "MultiPolygon"
    },
    "id": 30,
    "properties": {
        "level1": 14,
        "level1_description": "TROPICAL DRY FORESTS",
        "level2": 6,
        "level2_description": "SIERRA AND PLAINS OF EL CABO"
    },
    "type": "Feature"
}

Historic Range

The Historic Range endpoint lists all date ranges whose data is considered to calculate the baseline measure of historic climate. This feature is a reflection of the climatalogical practice to only consider 30 consecutive years of historical data to compare against.

List historic ranges

GET /api/historic-range/

List all available historic date ranges

Status Codes:
  • 200 OK – A list of the HistoricDateRange objects

Example usage

GET /api/historic-range/ HTTP/1.1
Host: example.org
Authorization: Token 46806a08bf54136e9597e879ed3a0876113fdee6

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "start_year": 1951,
        "end_year": 1980
    },
    {
        "start_year": 1961,
        "end_year": 1990
    }
]

Auth

The Auth endpoint allows a user to retreive their API token.

Retrieve auth token

POST /api-token-auth/

Retrieves an API authorizaton token when a registered email and password are sent in the request data via form data or JSON.

Status Codes:

Example usage

POST /api-token-auth/ HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Content-Length: 40

email=user%40example.org&password=foobar

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json


{
    "token": "46806a08bf54136e9597e879ed3a0876113fdee6"
}