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.
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.?format=
query parameter. E.g. ?format=geojson
will return GeoJSON.Accept: text/html
will return a browse-able API view./api/observations/
)./api/observations/LACM:Birds:15913/
) if applicable.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.
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: | |
---|---|
|
List views only
GET
/api/{resource}/?params
¶Query Parameters: | |
---|---|
|
Ordering
GET
/api/{resource}/?params
¶Query Parameters: | |
---|---|
|
Geographic query parameters (resources with geometries only)
GET
/api/{resource}/?params
¶Query Parameters: | |
---|---|
|
Geospatial query examples
- Returns only georeferenced records using California Teale Albers projection (EPSG:3310): /api/observations/?georeferenced=True&srs=3310
- Returns records within a bounding box: /api/observations/?bbox=-125,38,-124,39
- Return records that intersect with geometry in GeoJSON (or WKT): /api/observations/?g={“type”:”Polygon”,”coordinates”:[[[-125,38],[-125,39],[-124,39],[-124,39],[-125,38]]]}
Meta data are data that describe shared aspects across resources. Currently we provide meta data on the origins of our 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.
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: | |
---|---|
|
* 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
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: | |
---|---|
|
* this parameter can be modified, e.g. phylum__exact, in order to get exact matches
Detail View
GET
/api/photos/{record}/
¶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}/
¶Please refer to the next chapter: Wieslander Vegetation Type Mapping Project (VTM)
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: | |
---|---|
|
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.