Quickstart guide


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.

  • a more detailed single item view represented by a persistent URI, e.g.


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

Selection of Returned Fields

The API provides three query parameters controlling return fields will in order to limit the data that need to be downloaded.

Parameters for Formatting and Pagination

The 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:

For more information view the Django REST framework documentation.