Warning
This quick-start guide does not cover all resources of the API. Please consult the following sections of this documentation for further details.
The entry point of the API is /api/.
Following resources are currently available:
These resources are represented in two views:
a hyper-linked and paginated list view as starting point for filtering and searching.
The browse-able API provides two buttons that show the available Options and GET formats. We currently provide JSON, GeoJSON, a browse-able API format, and where applicable a map and a photo view for more convenient data exploration and discovery.
The request format application/json will always return JSON with a “geometry” in GeoJSON:
The field will be null for records that do not contain a valid geometry.
Records can be filtered by adding the parameter ?georeferenced=True.
This will come in handy if an older GeoJSON parser requiring valid geometries is used.
It can also cut back on the amount of returned data which can improve
performance due to the reduction of data transferred.
The Ecoengine API provides two principal methods for filtering and searching resources. First, most query parameters will trigger database queries. Second, using the ?q= query parameter a build in search engine (ElasticSearch) can be utilized for quicker and faceted (but sometimes less precise) returns (see next paragraph).Both methods can be applied (at a performance penalty) in combination.
The following filters work on the resources above:
| Resource: | observations | photos | checklists | VTM vegetation | sensors data | sensors aggregation |
|---|---|---|---|---|---|---|
| url | /api/observations/? | /api/photos/? | /api/checklists/? | /api/vtmveg/? | /api/sensors/{record}/data? | /api/sensors/{record}/aggregate? |
| country | x | |||||
| state_province | x | x | ||||
| county | x | x | ||||
| kingdom | x | x | ||||
| phylum | x | x | ||||
| order | x | x | ||||
| clss (!) | x | x | ||||
| family | x | x | ||||
| genus | x | x | x | x | ||
| scientific_name | x | x | x | x | ||
| authors | x | x | ||||
| remote_id | x | x | x | x | ||
| collection_code | x | x | x | x | ||
| source | x | x | x | x | ||
| min_date | x | x | x | x | x | |
| max_date | x | x | x | x | x | |
| related_type | x | |||||
| related | x | |||||
| interval | x (Pandas Intervals *) | |||||
| hours | x | |||||
| days | x | |||||
| weeks | x | |||||
| month | x | |||||
| years | x |
* see Pandas documentation
Example: /api/observations/?genus=Lynx&state_province=California
The standard search returns a match when any part of the field matches the input. For exact matches add __exact:
Example: /api/observations/?genus__exact=Lynx&state_province=California
The result can also be filtered geographically by specifying a bounding box (?bbox=): /api/observations/?genus=Lynx&bbox=-124,32,-114,42
The query parameter q= allows for searches using ElasticSearch.
This can be done across resources, e.g.:
To retrieve the records resulting from a search, the search query parameter q= can be used on specific resources (consult faceted result to determine whether there
are any hits within a particular resource):
There are also parameters to get the return for specific facets, e.g.:
/api/search/?q=pinus&selected_facet=state_province_exact:California
Additional filter parameters (from the table above) will be applied after the search is completed:
The API provides three query parameters controlling return fields will in order to limit the data that need to be downloaded.
?fields={}: request all fields available?fields={list of fields}: request specific fields?exclude={list of fields}: exclude fields from standard output?extra={list of fields}: add fields to standard outputThe API will render JSON whenever the media type “application/json” is requested which allows for an easy use with AJAX calls. Nevertheless, ?format=geojson can be provided to override the header information. This works for all formats present in the GET menu (which varies between resources).
Pagination parameters are:
?page_size=: sets the number of records in a list view?page=: sets page number?georeferenced=: returns only georeferenced records if True``?facets_limit=: sets the number of facets returned per category in searches, the facets with the most hits will be returnedFor more information view the Django REST framework documentation.