Getting Started¶

Authentication¶

Currently the Cal-Adapt API does not require authentication. You do not need to sign up for a key to start working with the API. We plan to maintain the current level of open access to support a wide range of users. However, authentication may be implemented in the future to support throttled access for selected applications.

Entry Point¶

The entry point or API root is a starting point that provides an overview of all available data in the API. The entry point for the Cal-Adapt API is at https://api.cal-adapt.org/api/.

curl https://api.cal-adapt.org/api/

Browsable API View¶

When you visit the above entry point in a browser, you will see an easy to read, browsable view of the Cal-Adapt API. The browsable API view provides a quick overview of available data resources in the API and the URLs to access these data resources. This makes it easier and convenient to test requests and their returns in a web browser.

Representations¶

The Cal-Adapt API supports the following representations or data formats listed with their content type followed by format identifier:

Raster and vector data

Browsable API view text/html api

JavaScript Object Notation application/json json

Raster data only

Comma Separated Values text/csv csv

Zipped GeoTIFF application/zip tif.zip

Vector data only

GeoJSON application/vnd.geo+json geojson

Keyhole Markup Language application/vnd.google-earth.kml+xml kml

Zipped KML files application/vnd.google-earth.kmz kmz

The HTTP Accept header is used in performing content negotiation. The server will return JSON when a client does not specify. The following command confirms the Contenty-Type: application/json header in the response.

curl -IH 'Accept: application/json' https://api.cal-adapt.org/api/

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

Or, HTML which returns the browsable API page.

curl -IH 'Accept: text/html' https://api.cal-adapt.org/api/

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8

If necessary, content negotiation can be overridden by adding the format query parameter to the URL like https://api.cal-adapt.org/api/?format=json.

Pagination¶

The API returns a paginated response for large datasets. Pagination links are provided as part of the content of the response so consumers can fetch additional pages as needed with the next property which links to https://api.cal-adapt.org/api/series/?page=2. The default number of records returned per page is 10. The number of records returned in each page can be controlled by using pagesize query parameter.

Example Request

GET /api/series/ HTTP/1.1
Host: api.cal-adapt.org
Accept: application/json

Response

{
  "count": 259,
  "next": "https://api.cal-adapt.org/api/series/?page=2",
  "previous": null,
  "results": [
      {
        "name": "U.C. Merced Wildfire high population scenario CNRM-CM5 rcp45",
        "slug": "fire_CNRM-CM5_rcp45_H_mu",
        "url": "https://api.cal-adapt.org/api/series/fire_CNRM-CM5_rcp45_H_mu/",
        "begin": "1954-01-01T00:00:00Z",
        "end": "2100-12-31T00:00:00Z",
        "rasters": [
            "https://api.cal-adapt.org/api/rstores/fire_CNRM-CM5_rcp45_H_mu_1954/",
            "https://api.cal-adapt.org/api/rstores/fire_CNRM-CM5_rcp45_H_mu_1955/",
            "https://api.cal-adapt.org/api/rstores/fire_CNRM-CM5_rcp45_H_mu_1956/"
            ,
        ],
        "tags": [
            "fire"
        ]
      },
      {
        "name": "U.C. Merced Wildfire low population scenario CNRM-CM5 rcp45",
        "slug": "fire_CNRM-CM5_rcp45_L_mu",
        "url": "https://api.cal-adapt.org/api/series/fire_CNRM-CM5_rcp45_L_mu/",
        "begin": "1954-01-01T00:00:00Z",
        "end": "2100-12-31T00:00:00Z",
        "rasters": [
            "https://api.cal-adapt.org/api/rstores/fire_CNRM-CM5_rcp45_L_mu_1954/",
            "https://api.cal-adapt.org/api/rstores/fire_CNRM-CM5_rcp45_L_mu_1955/",
            "https://api.cal-adapt.org/api/rstores/fire_CNRM-CM5_rcp45_L_mu_1956/"
            ,
        ],
        "tags": [
            "fire"
        ]
      }
      ,
    ]
  }