Using the API

Automatic swagger API documentation is not yet available (volunteers welcome!). Instead, an API client file is provided for easy experimentation:
The API client Insomnia is required to use this file. You can also export to other clients such as Postman, but Insomnia is recommended for its ability to store things like authentication parameters as variables.

Users may also inspect the code and console output from the above apps to see how the API is used in practice.


Most resources require a JWT token with every request; for more on this, see Authentication.

The included Insomnia collection makes use of Environments, which allow for the provision of arbitrary variables that can be used anywhere in the app. The prod environment, for example, defines api_url as In this way users can easily switch between testing in different environments (including local).

Before you can start using the Insomnia collection, you need to:

  1. Have or create a MERMAID user account appropriate to the targeted environment, easily obtainable by going to (production).

  2. Change the project environment variable to the id of a project in MERMAID to which you belong, by copying/pasting from the Collect url, like this:



All responses to GET requests for non-aggregated-view urls are returned as standard JSON, with content-type = application/json. In addition, Aggregated views offer two additional formats, accessible by appending the relevant string to resources:

  • .../csv/: returns comma-separated 2D matrix (some fields are JSON)

  • .../geojson/: returns GeoJSON

GET requests will return lists of objects. Appending an object id to most resources will return a single object.


The included Insomnia collection contains examples of filters available for each resource, accessible from the Query tab of each request. In general, the basic “core” resources such as fishspecies support filtering by fields available from that resource, e.g.
These resources also support ordering by field (or related field) names, e.g.
Many resources also allow limited searching via filters, e.g.:
Aggregated views offer searching by multiple comma-separated values, e.g.,Lhok%20Weng