Resources

We refer to the data assets of an API as resources. They are represented by so-called endpoints referred to by an unambiguous URL.

Note

All URLs should be followed by a trailing slash.

The API will re-route requests without trailing slashes automatically to the correct URL. However, the extra request will cost time and some consumers are not able to deal with re-routed requests.

Be aware that some consumers remove trailing slashes. (e.g. AngularJS’ resource directive). Use the developer tools of your browser to check the request issued by your application.

Basic Principles

  • The API returns data formats according to the Accept-field in the request header if possible. E.g. Accept: application/json if this particular format can be provided. Otherwise it will fall back to the HTML based browse-able API view.
  • Be aware of the fact that there might be different flavors of returns that are covered by one single accept type. In this case the flavor can be determined with the ?format= query parameter. E.g. ?format=geojson will return GeoJSON.
  • Accept: text/html will return a browse-able API view.
  • The endpoint URL will return a paginated list view (e.g. /api/observations/).
  • Adding a unique identifier will return a single item view (e.g. /api/observations/LACM:Birds:15913/) if applicable.

The Entry End Point

The entry point provides an overview over the available resources and actions. It is a starting point to navigate the API. It provides URLs for all endpoints including meta data, data, and specific operations that can be performed on the data (currently /api/search/).

GET /api/

The entry endpoint of the API.

Example Request

GET /api/ HTTP/1.1
Host: ecoengine.berkeley.edu
Accept: text/html

Response

HTTP 200 OK Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS

{
    "wieslander_vegetation_type_mapping": {
        "vtm_plot_data_tree_attributes": "https://ecoengine.berkeley.edu/api/vtmplots_trees/",
        "vtm_plot_data": "https://ecoengine.berkeley.edu/api/vtmplots/",
        "vtm_plot_data_brushes_attributes": "https://ecoengine.berkeley.edu/api/vtmplots_brushes/",
        "vtm_features": "https://ecoengine.berkeley.edu/api/vtmveg/"
    },
    "data": {
        "checklists": "https://ecoengine.berkeley.edu/api/checklists/",
        "sensors": "https://ecoengine.berkeley.edu/api/sensors/",
        "observations": "https://ecoengine.berkeley.edu/api/observations/",
        "photos": "https://ecoengine.berkeley.edu/api/photos/"
    },
    "actions": {
        "search": "https://ecoengine.berkeley.edu/api/search/"
    },
    "meta-data": {
        "footprints": "https://ecoengine.berkeley.edu/api/footprints/",
        "data_sources": "https://ecoengine.berkeley.edu/api/sources/"
    }
}

Explore the browsable API /api/. The browsable API provides a layer of additional documentation, a quick way to get an overview over the data, as well as the possibility to test URLs and requests and their returns conveniently in a web browser.

Query Parameters Working Across Resources

There are a few query parameters that work across most of the API (or at least all places where they might be applicable). They are dealing mostly with pagination, data formats, and return options.

There are two fundamental data views: List views that return the result of a selection process and detail views which tie a unique and (hopefully) persistent single URL to a record.

Warning

Invalid or non-applicable query parameters will be ignored. Carefully check the return whether the query had the desired effect.

All views

GET /api/{resource}/{record}?params
GET /api/{resource}/?params
Query Parameters:
 
  • format – one of json, api, csv (see resources documentation for additional formats available)
  • fields – list of field names to include in view, e.g. fields=genus,kingdom,geojson
  • exclude – list of fields to exclude from views
  • extra – list of fields to add to the already selected fields

List views only

GET /api/{resource}/?params
Query Parameters:
 
  • record – string – parse record identifier for partial match
  • record__exact – string – better use /api/observations/{record}/, returns list with single item if needed
  • page – integer
  • page_size – integer
  • q – send request to search engine – see extra documentation (only for searchable resources)
  • min_date – date, e.g. min_date=1940-01-01 (only resources with begin_date field)
  • max_date – date (only resources with begin_date)

Ordering

GET /api/{resource}/?params
Query Parameters:
 

Geographic query parameters (resources with geometries only)

GET /api/{resource}/?params
Query Parameters:
 
  • srs – integer – Geospatial reference system used, see http://spatialreference.org (not all codes are implemented – only for resources with geometry field)
  • bbox – x left lower corner,y left lower corner,x right upper corner,y right upper corner – e.g. bbox=-120,34,-140,39, (only for resources with geometry field)
  • g – select by geometry (GeoJSON or WKT)
  • georeferenced – returns only georeferenced records if True (only for resources with geometry field)

Geospatial query examples

Meta Data

Meta data are data that describe shared aspects across resources. Currently we provide meta data on the origins of our data.

Data Sources

GET /api/sources/

Explore the data sources and find links to its owners, creators, and providers.

Example request

GET /api/sources/ HTTP/1.1
Host: ecoengine.berkeley.edu
Accept: application/json, text/html

Data

Data resources stem from single collection events. They are generally imported from collections as documented in data sources. Some of the data sources e.g. photos and species lists generate also records in the observations table if there are species associated that can be stored with place and time variables.

Observations (searchable)

Formats: json, api, csv, geojson, map

Observations are the central event resource within the Berkeley Ecoinformatics Engine. Most of them are imported directly from GBIF, if not, you will found the source in the data sources view /api/sources. For the time being the selection is limited to collections that are relevant for California but all records (including the ones outside California) are available.

The majority of records are museums specimen and they carry a reference to an original record in the field remote_resource if available. However, some of the records are derived from other resources in the Ecoengine such us photos, species checklist, or the Wieslander VTM mapping project. The type of observation can be found in the field observation_type.

List View

GET /api/observations/
Query Parameters:
 
  • kingdom – string *
  • kingdom__exact – string (one of plantae, animalia, fungi)
  • phylum – string *
  • class – string *
  • order – string *
  • family – string *
  • genus – string *
  • scientific_name – string *
  • country – string *
  • state_province – string *
  • county – string *
  • source – string – source of record, e.g. Museum *
  • source_id – integer – id of source as represented in /api/sources/
  • observation_type – one of specimen, observation, photo, checklist, vtm-vegetation-feature
  • institution_code – string
  • collection_code – string

* this parameter can be modified, e.g. phylum__exact, in order to get exact matches

Detail View

GET /api/observations/{record}/

This view shows one single record as requested. It also provides the persistence url for records in the API.

Example request

GET /api/observations/CAS:ICH:6119/
Host: ecoengine.berkeley.edu
Accept: application/json, text/html

Photos (searchable)

Formats: json, api, csv, geojson, map, photos

The Berkeley Ecoinformatics Engine currently provides photos from Calphoto. Until the terms of use for the Berkeley Ecoinformatics Engine will be finalized, the selection contains only records that can be shared freely.

The highlight of the collection are photos that were taken during a California-wide vegetation mapping effort between 1920-1940 by Alfred Everett Wieslander. This part of the collection can be requested by adding ?collection_code=vtm to the URL below.

The response of the photo resource contains a field observations which contains a list of derived records in /api/observations/. These records are included in the search operations on the photo resource. The related records in the observation resource is identified by the same record number extended by an index, e.g.

Record number CalPhotos:5555+5555+0000+1128 has five species associated which can be found as list in the observation field or by searching the observation resource with the URL /api/observations/?record=CalPhotos:5555+5555+0000+1128 (DOES NOT WORK: FIX!). The related records are: CalPhotos:5555+5555+0000+1128:1, CalPhotos:5555+5555+0000+1128:2, CalPhotos:5555+5555+0000+1128:3, CalPhotos:5555+5555+0000+1128:4, CalPhotos:5555+5555+0000+1128:5 (in the order of the experience in the original data imports).

Note

The query parameters in the photo resource are very similar to the observations resource BUT they are not identical. Furthermore, the response is quite different.

List View

GET /api/photos/
Query Parameters:
 
  • record – string – parse record identifier for partial match *
  • record__exact – string – better use /api/photos/{record}/, returns list with single item if needed
  • kingdom – string *
  • kingdom__exact – string (one of plantae, animalia, fungi)
  • phylum – string *
  • class – string *
  • order – string *
  • family – string *
  • genus – string *
  • scientific_name – string *
  • country – string *
  • state_province – string *
  • county – string *
  • source – string – source of record, e.g. Museum *
  • source_id – integer – id of source as represented in /api/sources/
  • institution_code – string
  • collection_code – string
  • authors – string
  • photog_notes – string – search the note field on the photos

* this parameter can be modified, e.g. phylum__exact, in order to get exact matches

Detail View

GET /api/photos/{record}/

Checklists

Checklists are a list of observations bound to a geographic area (or footprint). They often represent expert knowledge, i.e. the knowledge of scientists or managers who can vouch that a certain species occurs in the associated area, however this occurrence might or might not be documented otherwise. Checklists often indicate the need for more research in the area.

Within the API checklists are somewhat similar to the Photos. They are represented as a single event, the creation of a checklist (which can span several years or even decades) associated with a place. The items on the list are derived entries in the observation resource which are associated as a list in the observation field.

E.g., the species list /api/checklists/bigcb:specieslist:1/ has an observations field which contains a list of species records which are numbered bigcb:specieslist:1:1, bigcb:specieslist:1:2, ... , bigcb:specieslist:1:59.

A convenient way to get all these records back is to query by partial record id on the observations resource, e.g. /api/observations/?record=bigcb:specieslist:1:. Note the trailing colon, which is necessary. Otherwise the request would return also results from checklists 11 to 19.

List View

GET /api/checklists/

Detail View

GET /api/checklists/{record}/

Wieslander’s Data

Please refer to the next chapter: Wieslander Vegetation Type Mapping Project (VTM)


Actions

Search Feedback

The Ecoengine has a dedicated end point to give feedback on research results presented in a faceted manner. The strength of this interface lies in the fact that it can search across all resources that are indexed (i.e. searchable).

GET /api/search/

This will return by default the 10 most frequent results in any of the faceted variables concerning taxonomy or geography as well as a link for “drilling” further down. For the facets available see /api/search/. This result can be modified in different ways.

Queries provided with the ?q= parameter will limit the results according to the search provided. Unless modified, it will return the 10 most frequent facets with a count of items.

GET /api/search/
Query Parameters:
 
  • facets_limit – number – sets the number of returned items per facet (default 10)
  • selected_facets – string – select only records that fall into a particular facet

The selected facet parameter has the format selected_facet=(facet_name)_exact:(facet_value). E.g. /api/search/?q=lynx&selected_facets=state_province_exact:California or if several facets should be selected /api/search/?q=lynx&selected_facets=state_province_exact:California&selected_facets=scientific_name:californicus. Note, the first selected_facets parameter has the _exact extension the second does not.

The faceted search view provides results from different resources (unless limited by selected_facets=resource_exact:{resource}). However, the retrieval of the records returned by the search has to be done one the resource in question. This can be easily archived by applying the exact query parameters on the resource. Getting the /api/observations/ results for the example above: /api/observations/?q=lynx&selected_facets=state_province_exact:California&selected_facets=scientific_name:californicus

More details in the following chapter.