Documentation

• 1: Overview
• 2: Getting Started
• 2.1: First time users
• 2.2: Apache Installation
• 2.3: Docker Installation
• 2.4: Customize Installation
• 3: API services
• 3.1: Quick reference
• 3.2: GET data
• 3.3: Post data
• 3.4: Put data
• 4: Concepts
• 4.1: Core Objects
• 4.2: Trait Objects
• 4.3: Data Access Objects
• 4.4: Auxiliary Objects
• 5: Contribution Guidelines
• 6: Tutorials
• 6.1: Getting data with OpenDataBio-R
• 6.2: Import data with R
• 6.2.1: Import Locations
• 6.2.2: Import BibReferences
• 6.2.3: Import Vernacular
• 6.2.4: Import Media
• 6.2.5: Import Taxons
• 6.2.6: Import Persons
• 6.2.7: Import Traits
• 6.2.8: Import Individuals & Vouchers
• 6.2.9: Import Measurements

1 - Overview

OpenDataBio is an opensource web-based platform designed to help researchers and organizations studying biodiversity in Tropical regions to collect, store, related and serve data. It is designed to accommodate many data types used in biological sciences and their relationships, particularly biodiversity and ecological studies, and serves as a data repository that allow users to download or request well-organized and documented research data.

Why?

Biodiversity studies frequently require the integration of a large amount of data, which require standardization for data use and sharing, and also continuous management and updates, particularly in Tropical regions where biodiversity is huge and poorly known.

OpenDataBio was designed based on the need to organize and integrate historical and current data collected in the Amazon region, taking into account field practices and data types used by ecologists and taxonomists.

OpenDataBio aim to facilitate the standardization and normalization of data, utilizing different API services available online, giving flexibility to user and user groups, and creating the necessary links among Locations, Taxons, Individuals, Vouchers and the Measurements and Media-files associated with them, while offering accessibility to the data through an API service, facilitating data distribution and analyses.

Main features

1. Custom variables - the ability to define custom Traits, i.e. user defined variables of different types, including some special cases like Spectral Data, Colors, TaxonLinks and GeneBank. Measurements for such traits can be recorded for Individuals, Vouchers, Taxons and/or Locations.
2. Taxons can be published or unpublished names (e.g. a morphotype), synonyms or valid names, and any node of the tree of life may be stored. Taxon insertion are checked against different nomenclature data sources (Tropicos, IPNI, MycoBank,ZOOBANK, GBIF), minimizing your search for correct spelling, authorship and synonyms.
3. Locations are stored with their spatial Geometries, allowing location parent detection and spatial queries. Special location types, such as Plots and Transects can be defined, facilitating commonly used methods in biodiversity studies
4. Data access control - data are organized in Datasets that permits to define an access policy (public, non-public) and a license for distribution of public datasets, becoming a self-contained dynamic data publication, versioned by the last edit date.
5. Different research groups may use a single OpenDataBio installation, having total control over their particular research data edition and access, while sharing common libraries such as Taxonomy, Locations, Bibliographic References and Trait definitions.
6. API to access data programatically - Tools for data exports and imports are provided through API services along with a API client in the R language, the OpenDataBio-R package.
7. Autiting - the Activity Model audits changes in any record and downloads of full datasets, which are logged for history tracking.
8. The BioCollection model allows administrators of Biological Collections to manage their Voucher records as well as user-requests, facilitating the interaction with users providing samples and data.
9. A mobile data collector is planned with ODK or ODK-X

Learn more

• Getting Started: install OpenDataBio!
• FAQs: Check out some example code!

2 - Getting Started

OpenDataBio is a web-based software supported in Debian, Ubuntu and Arch-Linux distributions of Linux and may be implemented in any Linux based machine. We have no plans for Windows support, but it may be easy to install in a windows machine using Docker.

Opendatabio is written in PHP and developed with the Laravel framework. It requires a web server (apache or nginx), PHP and a SQL database – tested only with MySQL and MariaDB.

You may install OpenDataBio easily using the Docker files included in the distribution, but these docker files provided are meant for development only and required tuning to deploy a production site.

If you just want to test OpenDataBio in your computer, follow the Docker Installation.

Prep for installation

1. You may want to request a Tropicos.org API key for OpenDataBio to be able to retrieve taxonomic data from the Tropicos.org database. If not provided, mainly the GBIF nomenclatural service will be used;
2. OpenDataBio sends emails to registered users, either to inform about a Job that has finished, to send data requests to dataset administrators or for password recovery. You may use a Google Email for this, but will need to change the account security options to allow OpenDataBio to use the account to send emails (you need to turn on the Less secure app access option in the Gmail My Account Page and will need to create a cron job to keep this option alive). Therefore, create a dedicated email address for your installation. Check the “config/mail.php” file for more options on how to send e-mails.

2.1 - First time users

OpenDataBio is software to be used online. Local installations are for testing or development, although it could be used for a single-user production localhost environment.

User roles

• If you are installing, the first login to an OpenDataBio installation must be done with the default super-admin user: admin@example.org and password1. These settings should be changed or the installation will be open to anyone reading the docs;
• Self-registrations only grant access to datasets with privacy set to registered users and allows user do download data of open-access, but do not allow the user to edit nor add data;
• Only full users can contribute with data.
• But only super admin can grant full-user role to registered users - different OpenDataBio installations may have different policies as to how you may gain full-user access. Here is not the place to find that info.

See also User Model.

Prep your full-user account

1. Register yourself as Person and assign it as your user default person, creating a link between your user and yourself as collector.
2. You need at least a dataset to enter your own data
3. When becoming a full-user, a restricted-access Dataset and Project will be automatically created for you (your Workspaces). You may modify these entities to fit your personal needs.
4. You may create as many Projects and Datasets as needed. So, understand how they work and which data they control access to.

Entering data

There three main ways to import data into OpenDataBio:

1. One by one through the web Interface
2. Using the OpenDataBio POST API services:
   1. importing from a spreadsheet file (CSV, XLXS or ODS) using the web Interface
   2. using the OpenDataBio R package client
3. When using the OpenDataBio API services you must prep your data or file to import according to the field options of the POST verb for the specific ’endpoint’ your are trying to import.

Tips for entering data

1. If first time entering data, you should use the web interface and create at least one record for each model needed to fit your needs. Then play with the privacy settings of your Workspace Dataset, and check whether you can access the data when logged in and when not logged in.
2. Use Dataset for a self-contained set of data that should be distributed as a group. Datasets are dynamic publications, have author, data, and title.
3. Although ODB attempt to minimize redundancy, giving users flexibility comes with a cost, and some definitions, like that of Traits or Persons may receive duplicated entries. So, care must be taken when creating such records. Administrators may create a ‘code of conduct’ for the users of an ODB installation to minimize such redundancy.
4. Follow an order for importation of new data, starting from the libraries of common use. For example, you should first register Locations, Taxons, Persons, Traits and any other common library before importing Individuals or Measurements
5. There is no need to import POINT locations before importing Individuals because ODB creates the location for you when you inform latitude and longitude, and will detect for you to which parent location your individual belongs to. However, if you want to validate your points (understand where such point location will placed), you may use the Location API with querytype parameter specified for this.
6. There are different ways to create PLOT and TRANSECT locations - see here Locations if that is your case
7. Creating Taxons require only the specification of a name - ODB will search nomenclature services for you, find the name, metadata and parents and import all of the them if needed. If you are importing published names, just inform this single attribute. Else, if the name is unpublished, you need to inform additional fields. So, separate the batch importation of published and unpublished names into two sets.
8. The notes field of any model is for both plain text or JSON object string formatted data. The Json option allows you to store custom structured data any model having the notes field. You may, for example, store as notes some secondary fields from original sources when importing data, but may store any additional data that is not provided by the ODB database structure. Such data will not be validate by ODB and standardization of both tags and values depends on you. Json notes will be imported and exported as a JSON string, and will be presented in the interface as a formatted table; URLs in your Json will be presented as links.

2.2 - Apache Installation

These instructions are for an apache-based installation, but can be easily tuned to work with nginx.

Server requirements

1. The supported PHP version >= 8.2 (8.3 recommended)
2. The web server may be apache or nginx. For nginx, check configuration in the docker files to tune these instructions, which are for apache.
3. It requires a SQL database, MySQL and MariaDB have been tested, but may also work with Postgres. Tested with MySQL 8.0 and MariaDB 10.6+.
4. PHP extensions required: openssl, pdo, pdo_mysql, mbstring, tokenizer, xml, dom, gd, exif, bcmath, zip, curl, redis.
5. Redis Server is required for queues and cache.
6. Tectonic is used for LaTeX/PDF label generation.
7. Pandoc is used to translate LaTeX code used in bibliographic references. It is not necessary for installation, but suggested for a better user experience.
8. Requires Supervisor, which is needed background jobs

Create Dedicated User

The recommended way to install OpenDataBio for production is using a dedicated system user. In this instructions this user is odbserver.

Download OpenDataBio

Login as your Dedicated User and download or clone this software to where you want to install it. Here we assume this is /home/odbserver/opendatabio so that the installation files will reside in this directory. If this is not your path, change below whenever it applies.

Prep the Server

First, install the prerequisite software: Apache, MySQL, PHP, Redis, Tectonic, Pandoc and Supervisor. On a Debian system, you need to install some PHP extensions as well and enable them:

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo add-apt-repository ppa:ondrej/php ppa:ondrej/apache2
sudo add-apt-repository ppa:ondrej/php
sudo add-apt-repository ppa:ondrej/apache2

sudo apt-get install mysql-server redis-server tectonic php8.3 libapache2-mod-php8.3 php8.3-intl \
 php8.3-mysql php8.3-sqlite3 php8.3-gd php8.3-cli pandoc \
 php8.3-mbstring php8.3-xml php8.3-bcmath php8.3-zip php8.3-curl php8.3-redis \
 supervisor

sudo a2enmod php8.3
sudo phpenmod mbstring
sudo phpenmod xml
sudo phpenmod dom
sudo phpenmod gd
sudo a2enmod rewrite
sudo a2ensite
sudo systemctl restart apache2.service



#To check if they are installed:
php -m | grep -E 'mbstring|cli|xml|gd|mysql|redis|bcmath|pcntl|zip'
tectonic --version
redis-server --version

Add the following to your Apache configuration.

• Change /home/odbserver/opendatabio to your path (the files must be accessible by apache)
• You may create a new file in the sites-available folder: /etc/apache2/sites-available/opendatabio.conf and place the following code in it.

touch /etc/apache2/sites-available/opendatabio.conf
echo '<IfModule alias_module>
        Alias /opendatabio      /home/odbserver/opendatabio/public/
        Alias /fonts /home/odbserver/opendatabio/public/fonts
        Alias /images /home/odbserver/opendatabio/public/images
        <Directory "/home/odbserver/opendatabio/public">
                Require all granted
                AllowOverride All
        </Directory>
</IfModule>' > /etc/apache2/sites-available/opendatabio.conf

This will cause Apache to redirect all requests for / to the correct folder, and also allow the provided .htaccess file to handle the rewrite rules, so that the URLs will be pretty. If you would like to access the file when pointing the browser to the server root, add the following directive as well:

RedirectMatch ^/$ /

Configure your php.ini file. The installer may complain about missing PHP extensions, so remember to activate them in both the cli (/etc/php/8.3/cli/php.ini) and the web ini (/etc/php/8.3/fpm/php.ini) files for PHP!

Update the values for the following variables:

Find files:
php -i | grep 'Configuration File'

Change in them:
	memory_limit should be at least 512M
	post_max_size should be at least 30M
	upload_max_filesize should be at least 30M

Something like:

[PHP]
allow_url_fopen=1
memory_limit = 512M

post_max_size = 100M
upload_max_filesize = 100M

Enable the Apache modules ‘mod_rewrite’ and ‘mod_alias’ and restart your Server:

sudo a2enmod rewrite
sudo a2ensite
sudo systemctl restart apache2.service

Mysql Charset and Collation

1. You should add the following to your configuration file (mariadb.cnf or my.cnf), i.e. the Charset and Collation you choose for your installation must match that in the ‘config/database.php’

[mysqld]
character-set-client-handshake = FALSE  #without this, there is no effect of the init_connect
collation-server      = utf8mb4_unicode_ci
init-connect          = "SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci"
character-set-server  = utf8mb4
log-bin-trust-function-creators = 1
sort_buffer_size = 256M  #large enough for geometry sort operations

[mariadb] or [mysql]
max_allowed_packet=100M
innodb_log_file_size=300M  #no use for mysql

2. If using MariaDB and you still have problems of type #1267 Illegal mix of collations, then check here on how to fix that,

Configure supervisord

Configure Supervisor, which is required for jobs. Create a file name opendatabio-worker.conf in the Supervisor configuration folder /etc/supervisor/conf.d/opendatabio-worker.conf with the following content:

touch /etc/supervisor/conf.d/opendatabio-worker.conf
echo ";--------------
[program:opendatabio-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/odbserver/opendatabio/artisan queue:work --sleep=3 --tries=1 --timeout=0 --memory=512
autostart=true
autorestart=true
user=odbserver
numprocs=8
redirect_stderr=true
stdout_logfile=/home/odbserver/opendatabio/storage/logs/supervisor.log
;--------------" > /etc/supervisor/conf.d/opendatabio-worker.conf

Folder permissions

• Folders storage and bootstrap/cache must be writable by the Server user (usually www-data). Set 0755 permission to these directories.
• Config .env file requires 0640 permission.
• This link has different ways to set up permissions for files and folders of a Laravel application. Below the preferred method:

cd /home/odbserver

#give write permissions to odbserver user and the apache user
sudo chown -R odbserver:www-data opendatabio
sudo find ./opendatabio -type f -exec chmod 644 {} \;
sudo find ./opendatabio -type d -exec chmod 755 {} \;  

#in these folders the server stores data and files.
#Make sure their permission is correct
cd /home/odbserver/opendatabio
sudo chgrp -R www-data storage bootstrap/cache
sudo chmod -R ug+rwx storage bootstrap/cache

#make sure media folder has the correct permissions
sudo find ./storage/app/public/media  -type f -exec chmod 664 {} \;
sudo find ./storage/app/public/media  -type d -exec chmod 775 {} \;

#make sure the .env file has 640 permission
sudo chmod 640 ./.env

Install OpenDataBio

1. Many Linux distributions (most notably Ubuntu and Debian) have different php.ini files for the command line interface and the Apache plugin. It is recommended to use the configuration file for Apache when running the install script, so it will be able to correctly point out missing extensions or configurations. To do so, find the correct path to the .ini file, and export it before using the php install command.

For example,

export PHPRC=/etc/php/8.3/apache2/php.ini

2. The installation script will download the Composer dependency manager and all required PHP libraries listed in the composer.json file. However, if your server is behind a proxy, you should install and configure Composer independently. We have implemented PROXY configuration, but we are not using it anymore and have not tested properly (if you require adjustments, place an issue on GitLab).

3. The script will prompt you configurations options, which are stored in the environment .env file in the application root folder.

You may, optionally, configure this file before running the installer:

• Create a .env file with the contents of the provided cp .env.example .env
• Read the comments in this file and adjust accordingly.

4. Run the installer:

cd /home/odbserver/opendatabio
php install

5. Seed data - the script above will ask if you want to install seed data for Locations and Taxons - seed data is version specific. Check the seed data repository version notes.

Installation issues

There are countless possible ways to install the application, but they may involve more steps and configurations.

• if you browser return 500|SERVER ERROR you should look to the last error in storage/logs/laravel.log. If you have ERROR: No application encryption key has been specified run:

php artisan key:generate
php artisan config:cache

• If you receive the error “failed to open stream: Connection timed out” while running the installer, this indicates a misconfiguration of your IPv6 routing. The easiest fix is to disable IPv6 routing on the server.
• If you receive errors during the random seeding of the database, you may attempt to remove the database entirely and rebuild it. Of course, do not run this on a production installation.

php artisan migrate:fresh

• You may also replace the Locations and Taxons tables with seed data after a fresh migration using:

php seedodb

Post-install configs

• If your import/export jobs are not being processed, make sure Supervisor is running systemctl start supervisord && systemctl enable supervisord, and check the log files at storage/logs/supervisor.log.
• You can change several configuration variables for the application. The most important of those are probably set by the installer, and include database configuration and proxy settings, but many more exist in the .env and config/app.php files. In particular, you may want to change the language, timezone and e-mail settings. Run php artisan config:cache after updating the config files.
• In order to stop search engine crawlers from indexing your database, add the following to your “robots.txt” in your server root folder (in Debian, /var/www/html):

User-agent: *
Disallow: /

Updating an existing Apache installation

Before updating, back up your database, .env, and storage/app/public/media.

1. Put the application in maintenance mode:

cd /home/odbserver/opendatabio
php artisan down

2. Update source code to the target version:

git fetch --tags
git checkout <target-tag-or-branch>

3. Update dependencies and apply database migrations:

composer install --no-dev --optimize-autoloader
php artisan migrate:status
php artisan migrate --force

4. Refresh caches and restart queue workers:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart
echo "" > storage/logs/laravel.log

5. Bring the application back online:

php artisan up

If the target version includes new environment variables (compare yours with the contents of .env.example), add them to .env before running cache commands.

Storage & Backups

You may change storage configurations in config/filesystem.php, where you may define cloud based storage, which may be needed if have many users submitting media files, requiring lots of drive space.

1. Data downloads are queue as jobs and a file is written in a temporary folder, and the file is deleted when the job is deleted by the user. This folder is defined as the download disk in filesystem.php config file, which point to storage/app/public/downloads. UserJobs web interface difficult navigation will force users to delete old jobs, but a cron cleaning job may be advisable to implement in your installation;
2. Media files are by default stored in the media disk, which place files in folder storage/app/public/media;
3. For regular configuration create both directories storage/app/public/downloads and storage/app/public/media with writable permissions by the Server user, see below topic;
4. Remember to include media folder in a backup plan;

2.3 - Docker Installation

The easiest way to install and run OpenDataBio is using Docker and the docker configuration files provided, which contain all the needed configurations to run ODB. Uses nginx and mysql, and supervisor for queues

Docker files

laraverl-app/
----docker/*
----./env.docker
----docker-compose.yml
----Dockerfile
----Makefile

These are adapted from this link, where you find a production setting as well.

Installation

Prerequisites

1. Docker with Compose plugin (docker compose v2).
2. Linux/mac: user in the docker group or run with sudo.
3. Windows: Docker Desktop (WSL2/Hyper-V enabled).

Quick start (Linux/mac, requires make)

cd opendatabio
make docker-init          # copies .env.docker, builds/starts, installs composer, key, migrates, storage:link
make docker-init SEED=1   # same as above + optional seed for Locations/Taxons

• Assets are already committed in public/build, so no npm step is needed inside Docker.
• App: http://localhost:8081 (user admin@example.org / password1)
• phpMyAdmin: http://localhost:8082

Windows (PowerShell)

cd opendatabio
powershell -ExecutionPolicy Bypass -File scripts/docker-init.ps1
# optional seed
powershell -ExecutionPolicy Bypass -File scripts/docker-init.ps1 -Seed

Manual commands (if you do not have make installed)

cp .env.docker .env
docker compose up -d
docker compose exec -T -u www-data laravel composer install --optimize-autoloader
docker compose exec -T -u www-data laravel php artisan key:generate --force
docker compose exec -T -u www-data laravel php artisan migrate --force
docker compose exec -T -u www-data laravel php artisan storage:link

Optional seed without make:

docker compose exec -T -u www-data laravel php getseeds
docker exec -i odb_mysql mysql -uroot -psecret odbdocker < storage/Location*.sql
docker exec -i odb_mysql mysql -uroot -psecret odbdocker < storage/Taxon*.sql
rm storage/Location*.sql storage/Taxon*.sql

Data persistence

The docker images may be deleted without loosing any data. The mysql tables are stored in a volume. You may change to a local path bind.

docker volume list

Using

The Makefile file contains the following commands to interact with the docker containers and odb.

Commands to build and create the app

1. make docker-init - copy .env.docker (if missing), build/start containers, install composer, key, migrate, storage:link
2. make build - build containers
3. make key-generate - generate the app key and adds to .env
4. make composer-install - install php dependencie
5. make composer-update - update php dependencies
6. make composer-dump-autoload - execute composer dump-autoload within container
7. make migrate - create or update the database
8. make drop-migrate - delete and recreate the database
9. make seed-odb - seed the database with locations and taxons

Commands to access the docker containers

1. make start - start all containers
2. make stop - stop all containers
3. make restart - restart all containers
4. make ssh - enter the main laravel app container
5. make ssh-mysql - enter the mysql container, so you may the log to the database using mysql -uUSER -pPWD
6. make mysql - enter the docker mysql console
7. make ssh-nginx - enter the nginx container
8. make ssh-supervisord - enter the supervisord container

Maintenance commands

1. make optimize - clean caches and log files
2. make info - show app info
3. make logs - show laravel logs
4. make logs-mysql - show mysql logs
5. make logs-nginx - show nginx logs
6. make logs-supervisord - show supervisor logs

Deleting & rebuilding

If you have issues and changed the docker files, you may need to rebuild:

#delete all images without loosing data
make stop  #first stop all
docker system prune -a  #and accepts Yes
make build
make start

Updating an existing Docker installation

Before updating, back up your database and storage/app/public/media.

1. Update source code to the target version:

cd opendatabio
git fetch --tags
git checkout <target-tag-or-branch>

2. Rebuild and restart containers:

make stop
make build
make start

3. Update PHP dependencies and run database migrations:

make composer-install
make migrate

4. Refresh Laravel caches and restart queue workers:

make optimize
docker compose exec -T -u www-data laravel php artisan queue:restart

If the new version introduces changes in .env, add the new keys before restarting workers in production.

2.4 - Customize Installation

Simple changes that can be implemented in the layout of a OpenDataBio web site

Logo and BackGround Image

To replace the Navigation bar logo and the image of the landing page, just put your image files replacing the files in /public/custom/ without changing their names.

Texts and Info

To change the welcome text of the landing page, change the values of the array keys in the following files:

• /resources/lang/en/customs.php
• /resources/lang/pt-br/customs.php
• Do not remove the entry keys. Set to null to suppress from appearing in the footer and landing page.

Local Documentation

You can add documentation in *.md format to the repository in files located in the following folders:

• /resources/docs/en/*
• /resources/docs/pt/*

This space is reserved for administrators to set documentation and custom directives for users of a specific OpenDataBio installation. For example, this is a place to include a code of conduct for users, information on who to contact to become a full user, specific tutorials, and so on.

NavBar and Footer

1. If you want to change the color of the top navigation bar and the footer, just replace css Boostrap 5 class in the corresponding tags and files in folder /resources/view/layout.
2. You may add additional html to the footer and navbar, change logo size, etc… as you wish.

3 - API services

Every OpenDataBio installation provide a API service, allowing users to GET data programmatically, and collaborators to POST new data into its database. The service is open access to public data, requires user authentication to POST data or GET data of restricted access.

The OpenDataBio API (Application Programming Interface -API) allows users to interact with an OpenDataBio database for exporting, importing and updating data without using the web-interface.

The OpenDataBio R package is a client for this API, allowing the interaction with the data repository directly from R and illustrating the API capabilities so that other clients can be easily built.

The OpenDataBio API allows querying of the database, data importation and data edition (update) through a REST inspired interface. All API requests and responses are formatted in JSON.

The API call

A simple call to the OpenDataBio API has four independent pieces:

1. HTTP-verb - either GET for exports or POST for imports.
2. base-URL - the URL used to access your OpenDataBio server + plus /api/v0. For, example, http://opendatabio.inpa.gov.br/api/v0
3. endpoint - represents the object or collection of objects that you want to access, for example, for querying taxonomic names, the endpoint is “taxons”
4. request-parameters - represent filtering and processing that should be done with the objects, and are represented in the API call after a question mark. For example, to retrieve only valid taxonomic names (non synonyms) end the request with ?valid=1.

The API call above can be entered in a browser to GET public access data. For example, to get the list of valid taxons from an OpenDataBio installation the API request could be:

https://opendb.inpa.gov.br/api/v0/taxons?valid=1&limit=10

When using the OpenDataBio R package this call would be odb_get_taxons(list(valid=1)).

A response would be something like:

{
  "meta":
  {
    "odb_version":"0.9.1-alpha1",
    "api_version":"v0",
    "server":"http://opendb.inpa.gov.br",
    "full_url":"https://opendb.inpa.gov.br/api/v0/taxons?valid=1&limit1&offset=100"},
    "data":
    [
      {
        "id":62,
        "parent_id":25,
        "author_id":null,
        "scientificName":"Laurales",
        "taxonRank":"Ordem",
        "scientificNameAuthorship":null,
        "namePublishedIn":"Juss. ex Bercht. & J. Presl. In: Prir. Rostlin: 235. (1820).",
        "parentName":"Magnoliidae",
        "family":null,
        "taxonRemarks":null,
        "taxonomicStatus":"accepted",
        "ScientificNameID":"http:\/\/tropicos.org\/Name\/43000015 | https:\/\/www.gbif.org\/species\/407",
        "basisOfRecord":"Taxon"
    }]}

API Authentication

1. Not required for getting any data with public access in the ODB database, which by default includes locations, taxons, bibliographic references, persons and traits.
2. Authentication Required to GET any data that is not of public access, and is required to POST and PUT data.

• Authentication is done using an API token, that can be found under your user profile on the web interface. The token is assigned to a single database user, and should not be shared, exposed, e-mailed or stored in version controls.
• To authenticate against the OpenDataBio API, use the token in the “Authorization” header of the API request. When using the R client, pass the token to the odb_config function cfg = odb_config(token="your-token-here").
• The token controls the data you can get and can edit

Users will only have access to the data for which the user has permission and to any data with public access in the database, which by default includes locations, taxons, bibliographic references, persons and traits. Measurements, individuals, and Vouchers access depends on permissions understood by the users token.

API versions

The OpenDataBio API follows its own version number. This means that the client can expect to use the same code and get the same answers regardless of which OpenDataBio version that the server is running. All changes done within the same API version (>= 1) should be backward compatible. Our API versioning is handled by the URL, so to ask for a specific API version, use the version number between the base URL and endpoint:

https://opendatabio.inpa.gov.br/opendatabio/api/v1/taxons

https://opendatabio.inpa.gov.br/opendatabio/api/v2/taxons

3.1 - Quick reference

GET DATA (downloads)

Shared get-parameters

Endpoint parameters

POST DATA (imports)

PUT DATA (updates)

Nomenclature types

Taxonomic ranks

3.2 - GET data

Shared GET parameters

GET endpoints

Quick links

• /
• bibreferences
• biocollections
• datasets
• individuals
• individual-locations
• languages
• locations
• measurements
• media
• persons
• projects
• taxons
• traits
• vernaculars
• vouchers
• userjobs
• activities
• tags

/ (GET)

Tests your access/token.

No parameters for this endpoint.

bibreferences (GET)

Bibliographic references (GET lists, POST creates).

Fields returned

Fields (simple): id, bibkey, year, author, title, doi, url, bibtex

Fields (all): id, bibkey, year, author, title, doi, url, bibtex

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 2,
            "bibkey": "Riberiroetal1999FloraDucke",
            "year": 1999,
            "author": "José Eduardo Lahoz Da Silva Ribeiro and Michael John Gilbert Hopkins and Alberto Vicentini and Cynthia Anne Sothers and Maria Auxiliadora Da Silva Costa and Joneide Mouzinho De Brito and Maria Anália Duarte De Souza and Lúcia Helena Pinheiro Martins and Lúcia Garcez Lohmann and Paulo Apóstolo Costa Lima Assunção and Everaldo Da Costa Pereira and Cosme Fernandes Da Silva and Mariana Rabello Mesquita and Lilian Costa Procópio",
            "title": "Flora Da Reserva Ducke: Guia De Identificação Das Plantas Vasculares De Uma Floresta De Terra Firme Na Amazônica Central",
            "doi": null,
            "url": null,
            "bibtex": "@Article{Riberiroetal1999FloraDucke,\r\n  title = {Flora da Reserva Ducke: Guia de Identifica{\\c{c}}{\\~a}o das Plantas Vasculares de uma Floresta de Terra Firme na Amaz{\\^o}nica Central},\r\n  author = {José Eduardo Lahoz da Silva Ribeiro and Michael John Gilbert Hopkins and Alberto Vicentini and Cynthia Anne Sothers and Maria Auxiliadora da Silva Costa and Joneide Mouzinho de Brito and Maria Anália Duarte de Souza and Lúcia Helena Pinheiro Martins and Lúcia Garcez Lohmann and Paulo Apóstolo Costa Lima Assunç{ã}o and Everaldo da Costa Pereira and Cosme Fernandes da Silva and Mariana Rabello Mesquita and Lilian Costa Procópio},\r\n  journal = {Flora da Reserva Ducke: Guia de Identifica{\\c{c}}{\\~a}o das Plantas Vasculares de uma Floresta de Terra Firme na Amaz{\\^o}nica Central},\r\n  year = {1999},\r\n  publisher = {INPA-DFID Manaus},\r\n  pages = {819p},\r\n}"
        },
        {
            "id": 3,
            "bibkey": "Sutter2006female",
            "year": 2006,
            "author": "D. Merino Sutter and P. I. Forster and P. K. Endress",
            "title": "Female Flowers And Systematic Position Of Picrodendraceae (Euphorbiaceae S.l., Malpighiales)",
            "doi": "10.1007/s00606-006-0414-0",
            "url": "http://dx.doi.org/10.1007/s00606-006-0414-0",
            "bibtex": "@article{Sutter2006female,\n     author = {D. Merino Sutter and P. I. Forster and P. K. Endress},\n     year = {2006},\n     title = {Female flowers and systematic position of Picrodendraceae (Euphorbiaceae s.l., Malpighiales)},\n     issn = {0378-2697 | 1615-6110},\n     issue = {1-4},\n     url = {http://dx.doi.org/10.1007/s00606-006-0414-0},\n     doi = {10.1007/s00606-006-0414-0},\n     volume = {261},\n     page = {187-215},\n     journal = {Plant Systematics and Evolution},\n     journal_short = {Plant Syst. Evol.},\n     published = {Springer Science and Business Media LLC}\n}"
        }
    ]
}

biocollections (GET)

Biocollections (GET lists, POST creates).

Fields returned

Fields (simple): id, acronym, name, irn

Fields (all): id, acronym, name, irn, country, city, address

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "acronym": "INPA",
            "name": "Instituto Nacional de Pesquisas da Amazônia",
            "irn": 124921,
            "country": null,
            "city": null,
            "address": null
        },
        {
            "id": 2,
            "acronym": "SPB",
            "name": "Universidade de São Paulo",
            "irn": 126324,
            "country": null,
            "city": null,
            "address": null
        }
    ]
}

datasets (GET)

Datasets and published dataset files (GET lists, POST creates via import job).

Fields returned

Fields (simple): id, name, title, projectName, description, notes, contactEmail, taggedWidth, uuid

Fields (all): id, name, title, projectName, notes, privacyLevel, policy, description, measurements_count, contactEmail, taggedWidth, uuid

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 4,
            "name": "PDBFF-FITO 1ha core plots 1-10cm dbh - TREELETS",
            "title": "Arvoretas (1cm>DAP",
            "projectName": "Projeto Dinâmica Biológica de Fragmentos Florestais (PDBFF-Data)",
            "notes": null,
            "privacyLevel": "Restrito a usuários autorizados",
            "policy": null,
            "description": "Contém o único censo de árvores de pequeno porte 1-10cm de diâmetro nas parcelas de 1ha do PDBFF, em 11 das 69 de parcelas permanentes de 1ha do Programa de Monitoramento de Plantas do PDBFF.",
            "measurements_count": null,
            "contactEmail": "example",
            "taggedWidth": "Parcelas florestais | PDBFF | Fitodemográfico",
            "uuid": "e1d8ce8d-4847-11f0-8e9f-9cb654b86224"
        }
    ]
}

individuals (GET)

Individuals (GET lists, POST creates, PUT updates).

Fields returned

Fields (simple): id, basisOfRecord, organismID, recordedByMain, recordNumber, recordedDate, family, scientificName, identificationQualifier, identifiedBy, dateIdentified, locationName, locationParentName, decimalLatitude, decimalLongitude, x, y, gx, gy, angle, distance, datasetName

Fields (all): id, basisOfRecord, organismID, recordedByMain, recordNumber, recordedDate, recordedBy, scientificName, scientificNameAuthorship, taxonPublishedStatus, genus, family, identificationQualifier, identifiedBy, dateIdentified, identificationRemarks, identificationBiocollection, identificationBiocollectionReference, locationName, higherGeography, decimalLatitude, decimalLongitude, georeferenceRemarks, locationParentName, x, y, gx, gy, angle, distance, organismRemarks, datasetName, uuid

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 306246,
            "basisOfRecord": "Organism",
            "organismID": "2639_Spruce_1852",
            "recordedByMain": "Spruce, R.",
            "recordNumber": "2639",
            "recordedDate": "1852-10",
            "recordedBy": "Spruce, R.",
            "scientificName": "Ecclinusa lanceolata",
            "scientificNameAuthorship": "(Mart. & Eichler) Pierre",
            "taxonPublishedStatus": "published",
            "genus": "Ecclinusa",
            "family": "Sapotaceae",
            "identificationQualifier": "",
            "identifiedBy": "Spruce, R.",
            "dateIdentified": "1852-10-00",
            "identificationRemarks": "",
            "identificationBiocollection": null,
            "identificationBiocollectionReference": null,
            "locationName": "São Gabriel da Cachoeira",
            "higherGeography": "São Gabriel da Cachoeira < Amazonas < Brasil",
            "decimalLatitude": 1.1841927,
            "decimalLongitude": -66.80167715,
            "georeferenceRemarks": "decimal coordinates are the CENTROID of the footprintWKT geometry",
            "locationParentName": "Amazonas",
            "x": null,
            "y": null,
            "gx": null,
            "gy": null,
            "angle": null,
            "distance": null,
            "organismRemarks": "prope Panure ad Rio Vaupes Amazonas, Brazil",
            "datasetName": "Exsicatas LABOTAM",
            "uuid": "c01000f0-f437-11ef-b90b-9cb654b86224"
        }
    ]
}

individual-locations (GET)

Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts).

Fields returned

Fields (simple): id, individual_id, basisOfRecord, occurrenceID, organismID, recordedDate, locationName, higherGeography, decimalLatitude, decimalLongitude, x, y, angle, distance, minimumElevation, occurrenceRemarks, scientificName, family, datasetName

Fields (all): id, individual_id, basisOfRecord, occurrenceID, organismID, scientificName, family, recordedDate, locationName, higherGeography, decimalLatitude, decimalLongitude, georeferenceRemarks, x, y, angle, distance, minimumElevation, occurrenceRemarks, organismRemarks, datasetName

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 306244,
            "individual_id": 306246,
            "basisOfRecord": "Occurrence",
            "occurrenceID": "2639_Spruce_1852.1852-10",
            "organismID": "2639_Spruce_1852",
            "scientificName": "Ecclinusa lanceolata",
            "family": "Sapotaceae",
            "recordedDate": "1852-10",
            "locationName": "São Gabriel da Cachoeira",
            "higherGeography": "Brasil > Amazonas > São Gabriel da Cachoeira",
            "decimalLatitude": 1.1841927,
            "decimalLongitude": -66.80167715,
            "georeferenceRemarks": "decimal coordinates are the CENTROID of the footprintWKT geometry",
            "x": null,
            "y": null,
            "angle": null,
            "distance": null,
            "minimumElevation": null,
            "occurrenceRemarks": null,
            "organismRemarks": "prope Panure ad Rio Vaupes Amazonas, Brazil",
            "datasetName": "Exsicatas LABOTAM"
        }
    ]
}

languages (GET)

Lists available interface/data languages.

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "code": "en",
            "name": "English",
            "is_locale": 1,
            "created_at": null,
            "updated_at": null
        }
    ]
}

locations (GET)

Locations (GET lists, POST creates, PUT updates).

Fields returned

Fields (simple): id, basisOfRecord, locationName, adm_level, country_adm_level, x, y, startx, starty, distance_to_search, parent_id, parentName, higherGeography, footprintWKT, locationRemarks, decimalLatitude, decimalLongitude, georeferenceRemarks, geodeticDatum

Fields (all): id, basisOfRecord, locationName, adm_level, country_adm_level, x, y, startx, starty, distance_to_search, parent_id, parentName, higherGeography, footprintWKT, locationRemarks, decimalLatitude, decimalLongitude, georeferenceRemarks, geodeticDatum

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 27297,
            "basisOfRecord": "Location",
            "locationName": "Parcela 1105",
            "adm_level": 100,
            "country_adm_level": "Parcela",
            "x": "100.00",
            "y": "100.00",
            "startx": null,
            "starty": null,
            "distance_to_search": null,
            "parent_id": 27277,
            "parentName": "Fazenda Esteio",
            "higherGeography": "Brasil > Amazonas > Rio Preto da Eva > Fazenda Esteio > Parcela 1105",
            "footprintWKT": "POLYGON((-59.81371985 -2.42215752,-59.81360263 -2.42126619,-59.81270751 -2.42136656,-59.81282469 -2.42225788,-59.81371985 -2.42215752))",
            "locationRemarks": "source: Polígono desenhado a partir das coordenadas de GPS dos vértices; georeferencedBy: Diogo Martins Rosa & Ana Andrade; fundedBy: Edital CNPq-Brasil/LBA 458027/2013-8; geometryBy: Alberto Vicentini; geometryDate: 2021-09-29; warning: Conflito com polígono da UC de 2021. Este polígono deveria ter a mesma geometria do polígono correspondente que faz parte da UC ARIE PDBFF, mas como ele foi gerado pelas coordenadas de campo, foi mantida essa geometria. A UC, portanto, não protege adequadamente essa parcela de monitoramento.",
            "decimalLatitude": -2.42215752,
            "decimalLongitude": -59.81371985,
            "georeferenceRemarks": "decimal coordinates are the START POINT in footprintWKT geometry",
            "geodeticDatum": null
        }
    ]
}

measurements (GET)

Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates).

Fields returned

Fields (simple): id, basisOfRecord, measured_type, measured_id, measurementType, measurementValue, measurementUnit, measurementDeterminedBy, measurementDeterminedDate, scientificName, datasetName, family, sourceCitation

Fields (all): id, basisOfRecord, measured_type, measured_id, measurementType, measurementValue, measurementUnit, measurementDeterminedDate, measurementDeterminedBy, measurementRemarks, resourceRelationship, resourceRelationshipID, relationshipOfResource, scientificName, family, datasetName, measurementMethod, sourceCitation, measurementLocationId, measurementParentId, decimalLatitude, decimalLongitude

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "basisOfRecord": "MeasurementsOrFact",
            "measured_type": "App\\Models\\Individual",
            "measured_id": 86947,
            "measurementType": "treeDbh",
            "measurementValue": 13,
            "measurementUnit": "cm",
            "measurementDeterminedDate": "1979-11-14",
            "measurementDeterminedBy": "Menezes, J.F. | Bahia, R.P. | Lima, J. | Santos, R.M. | Ferreira, A.J.C. | Cardoso, Romeu M.",
            "measurementRemarks": null,
            "resourceRelationship": null,
            "resourceRelationshipID": "1202-1371_Menezes_1979",
            "relationshipOfResource": "measurement of",
            "scientificName": "Paramachaerium ormosioides",
            "family": "Fabaceae",
            "datasetName": "Censos 01 - PDBFF-FITO ForestPlots - 1979-1980",
            "measurementMethod": "Name: Diameter at breast height - DBH | Definition:Diameter at breast height,, i.e. ca. 1.3 meters from the base of the trunk",
            "sourceCitation": null,
            "measurementLocationId": 28280,
            "measurementParentId": null,
            "decimalLatitude": -2.40371599,
            "decimalLongitude": -59.87090972
        }
    ]
}

media (GET)

Media metadata (GET lists, POST creates, PUT updates).

Fields returned

Fields (simple): id, model_type, model_id, basisOfRecord, recordedBy, recordedDate, dwcType, resourceRelationship, resourceRelationshipID, relationshipOfResource, scientificName, family, datasetName, projectName, taggedWith, accessRights, license, file_name, file_url, citation, uuid

Fields (all): id, model_type, model_id, basisOfRecord, recordedBy, recordedDate, dwcType, resourceRelationship, resourceRelationshipID, relationshipOfResource, scientificName, family, datasetName, projectName, taggedWith, accessRights, bibliographicCitation, license, file_name, file_url, citation, uuid, bibtex, userName, created_at

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 20211,
            "model_type": "App\\Models\\Individual",
            "model_id": 111785,
            "basisOfRecord": "MachineObservation",
            "recordedBy": "Francisco Javier Farroñay Pacaya",
            "recordedDate": "2025-03-09",
            "dwcType": "StillImage",
            "resourceRelationship": "Organism",
            "resourceRelationshipID": "3402-1134_Pereira_1986",
            "relationshipOfResource": "StillImage of ",
            "scientificName": "Sacoglottis guianensis",
            "family": "Humiriaceae",
            "datasetName": "Unknown dataset",
            "projectName": "Projeto Dinâmica Biológica de Fragmentos Florestais",
            "taggedWith": "Folha abaxial",
            "accessRights": "Open access.",
            "bibliographicCitation": "Sacoglottis guianensis (Humiriaceae). (2025). By Francisco Javier Farroñay Pacaya. Collection: Pereira, M.J.R. #3402-1134 on 1986-01-24, from Quadrante 52, Parcela 3402-3, Reserva 3402, Cabo Frio, Fazenda Porto Alegre, Amazonas, Brasil (PDBFF). Project: PDBFF-Data. Instituto Nacional de Pesquisas da Amazônia (INPA), Manaus, Amazonas, Brasil. Type: Image. License: CC-BY-NC-SA 4.0. uuid: inpa-odb-3f139ba4-f22b-42d8-9e74-c340309061c2, url: http://localhost/opendatabio",
            "license": "CC-BY-NC-SA 4.0",
            "file_name": "67ce28cd76f4a.jpg",
            "file_url": "http://localhost/opendatabio/storage/media/20211/67ce28cd76f4a.jpg",
            "citation": "Sacoglottis guianensis (Humiriaceae). (2025). By Francisco Javier Farroñay Pacaya. Collection: Pereira, M.J.R. #3402-1134 on 1986-01-24, from Quadrante 52, Parcela 3402-3, Reserva 3402, Cabo Frio, Fazenda Porto Alegre, Amazonas, Brasil (PDBFF). Project: PDBFF-Data. Instituto Nacional de Pesquisas da Amazônia (INPA), Manaus, Amazonas, Brasil. Type: Image. License: CC-BY-NC-SA 4.0. uuid: inpa-odb-3f139ba4-f22b-42d8-9e74-c340309061c2, url: http://localhost/opendatabio",
            "uuid": "3f139ba4-f22b-42d8-9e74-c340309061c2",
            "bibtex": "@misc{Farronay_2025_20211,\n{\n    \"title\": \" Sacoglottis guianensis (Humiriaceae)\",\n    \"year\": \"(2025)\",\n    \"author\": \"Francisco Javier Farroñay Pacaya\",\n    \"howpublished\": \"{http:\\/\\/localhost\\/opendatabio\\/media\\/uuid\\/3f139ba4-f22b-42d8-9e74-c340309061c2}\",\n    \"license\": \"CC-BY-NC-SA 4.0\",\n    \"note\": \"Type: Image; Collection: Pereira, M.J.R. #3402-1134 on 1986-01-24, from Quadrante 52, Parcela 3402-3, Reserva 3402, Cabo Frio, Fazenda Porto Alegre, Amazonas, Brasil (PDBFF); Coordinates: POINT(-59.91500315727877 -2.3929141688648765); License: CC-BY-NC-SA 4.0; Project: PDBFF-Data.; Accessed: 2026-02-04\",\n    \"publisher\": \"Instituto Nacional de Pesquisas da Amazônia (INPA), Manaus, Amazonas, Brasil\"\n}\n}",
            "userName": "example",
            "created_at": "2025-03-09T23:48:29.000000Z"
        }
    ]
}

persons (GET)

People (GET lists, POST creates, PUT updates).

Fields returned

Fields (simple): id, full_name, abbreviation, emailAddress, institution, notes

Fields (all): id, full_name, abbreviation, emailAddress, institution, notes

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 3127,
            "full_name": "Raimundo Afeganistão",
            "abbreviation": "AFEGANISTÃO, R.",
            "emailAddress": null,
            "institution": null,
            "notes": "PDBFF"
        },
        {
            "id": 14,
            "full_name": "Maria de Fátima  Agra",
            "abbreviation": "Agra, M.F.",
            "emailAddress": null,
            "institution": null,
            "notes": null
        },
        {
            "id": 15,
            "full_name": "J. L. A. Aguiar Jr",
            "abbreviation": "Aguiar Jr., J.L.A.",
            "emailAddress": null,
            "institution": null,
            "notes": null
        }
    ]
}

projects (GET)

Projects (GET lists).

Fields returned

Fields (simple): id, acronym, name, description

Fields (all): id, acronym, name, description, pages, urls, created_at, updated_at

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "acronym": "PDBFF-Data",
            "name": "Projeto Dinâmica Biológica de Fragmentos Florestais",
            "description": "Este espaço agrega conjuntos de dados de monitoramentos e pesquisas realizadas nas áreas amostrais do PDBFF,  localizadas na Área de Relevante Interesse Ecológico - ARIE PDBFF.",
            "pages": {
                "en": null,
                "pt-br": null
            },
            "urls": [
                {
                    "url": "https://alfa-pdbff.site/",
                    "label": null,
                    "icon": "fa-solid fa-globe"
                }
            ],
            "created_at": "2022-10-31T07:01:18.000000Z",
            "updated_at": "2023-11-17T21:08:55.000000Z"
        }
    ]
}

taxons (GET)

Taxonomic names (GET lists, POST creates).

Fields returned

Fields (simple): id, parent_id, author_id, scientificName, taxonRank, scientificNameAuthorship, namePublishedIn, parentName, family, taxonRemarks, taxonomicStatus, scientificNameID, basisOfRecord

Fields (all): id, senior_id, parent_id, author_id, scientificName, taxonRank, scientificNameAuthorship, namePublishedIn, parentName, family, higherClassification, taxonRemarks, taxonomicStatus, acceptedNameUsage, acceptedNameUsageID, parentNameUsage, scientificNameID, basisOfRecord

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 16332,
            "senior_id": null,
            "parent_id": 16331,
            "author_id": null,
            "scientificName": "Aiouea grandifolia",
            "taxonRank": "Species",
            "scientificNameAuthorship": "van der Werff",
            "namePublishedIn": null,
            "parentName": "Aiouea",
            "family": "Lauraceae",
            "higherClassification": "Eukaryota > Plantae > Viridiplantae > Embryophytes > Spermatopsida > Angiosperms > Magnoliidae > Laurales > Lauraceae > Aiouea",
            "taxonRemarks": null,
            "taxonomicStatus": "accepted",
            "acceptedNameUsage": null,
            "acceptedNameUsageID": null,
            "parentNameUsage": "Aiouea",
            "scientificNameID": "https://tropicos.org/Name/17806050 | https://www.gbif.org/species/4175896",
            "basisOfRecord": "Taxon"
        }
    ]
}

traits (GET)

Trait definitions (GET lists, POST creates).

Fields returned

Fields (simple): id, type, typename, export_name, unit, range_min, range_max, link_type, value_length, name, description, objects, measurementType, categories

Fields (all): id, type, typename, export_name, measurementType, measurementUnit, range_min, range_max, link_type, value_length, name, description, objects, measurementMethod, MeasurementTypeBibkeys, TaggedWith, categories

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 206,
            "type": 1,
            "typename": "QUANT_REAL",
            "export_name": "treeDbh",
            "measurementType": "treeDbh",
            "measurementUnit": "cm",
            "range_min": 0.1,
            "range_max": 700,
            "link_type": null,
            "value_length": null,
            "name": "Diâmetro à altura do peito – DAP",
            "description": "Diâmetro à altura do peito, i.e. medido a ca. 1.3m desde a base do caule",
            "objects": "App\\Models\\Individual | App\\Models\\Voucher | App\\Models\\Location | App\\Models\\Taxon | App\\Models\\Media",
            "measurementMethod": "Name: Diameter at breast height - DBH | Definition:Diameter at breast height,, i.e. ca. 1.3 meters from the base of the trunk",
            "MeasurementTypeBibkeys": "",
            "TaggedWith": "",
            "categories": null
        },
        {
            "id": 207,
            "type": 1,
            "typename": "QUANT_REAL",
            "export_name": "treeDbhPom",
            "measurementType": "treeDbhPom",
            "measurementUnit": "m",
            "range_min": 0,
            "range_max": 15,
            "link_type": null,
            "value_length": null,
            "name": "Ponto de medição do DAP",
            "description": "Ponto de medição do DAP, necessário quando impossível medir a 1.3 m",
            "objects": "App\\Models\\Individual",
            "measurementMethod": "Name: DBH Point of Measurement | Definition:DAP measuring height, necessary when impossible to measure at 1.3 m",
            "MeasurementTypeBibkeys": "",
            "TaggedWith": "",
            "categories": null
        },
        {
            "id": 524,
            "type": 2,
            "typename": "CATEGORICAL",
            "export_name": "stemType",
            "measurementType": "stemType",
            "measurementUnit": null,
            "range_min": null,
            "range_max": null,
            "link_type": null,
            "value_length": null,
            "name": "Tipo de fuste",
            "description": "Tipo de fuste",
            "objects": "App\\Models\\Voucher | App\\Models\\Individual | App\\Models\\Taxon",
            "measurementMethod": "Name: Type of stem | Definition:Type of stem | Categories: CategoryName: Main stem | Definition:The main trunk, usually the thickest. | CategoryName: Secondary stem | Definition:A secondary trunk, there is a thicker one, which defines the area better. A shoot below 1.3 m high is a secondary trunk.",
            "MeasurementTypeBibkeys": "",
            "TaggedWith": "",
            "categories": [
                {
                    "id": 12990,
                    "name": "Fuste principal",
                    "description": "O tronco principal, geralmente o mais grosso.",
                    "rank": 1,
                    "belongs_to_trait": "stemType"
                },
                {
                    "id": 12991,
                    "name": "Fuste secundário",
                    "description": "Um tronco secundário, há outro mais grosso, que define melhor a área. Um rebroto abaixo de 1.3 m de altura é um tronco secundário.",
                    "rank": 2,
                    "belongs_to_trait": "stemType"
                }
            ]
        }
    ]
}

vernaculars (GET)

Vernacular names (GET lists, POST creates).

Fields returned

Fields (simple): id, name, languageName, notes, locationsList, taxonsList, individualsList, citationsArray

Fields (all): id, name, languageName, languageCode, notes, taxonsList, taxonsListArray, individualsList, individualsListArray, locationsList, locationsListArray, variantsList, variantsListArray, citationsArray, createdBy, created_at, updated_at

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "name": "itaúba-preta",
            "languageName": "Portuguese",
            "languageCode": "pt-br",
            "notes": null,
            "taxonsList": "Mezilaurus duckei",
            "taxonsListArray": [
                {
                    "id": 19774,
                    "scientificName": "Mezilaurus duckei",
                    "family": "Lauraceae"
                }
            ],
            "individualsList": "7739_Macedo_2023",
            "individualsListArray": [
                {
                    "id": 510747,
                    "uuid": "c75d9233-f437-11ef-b90b-9cb654b86224",
                    "organismId": "7739_Macedo_2023",
                    "scientificName": "Mezilaurus duckei",
                    "family": "Lauraceae"
                }
            ],
            "locationsList": null,
            "locationsListArray": [],
            "variantsList": "itaúba",
            "variantsListArray": [
                {
                    "id": 2,
                    "name": "itaúba",
                    "languageName": "Tupi",
                    "languageCode": "tup"
                }
            ],
            "citationsArray": [
                {
                    "id": 2,
                    "citation": "ita = pedra; uba = árvore;  preta em referência a cor da madeira",
                    "bibreference_id": null,
                    "bibreference_name": null,
                    "notes": null,
                    "type": "etimology",
                    "createdBy": "example"
                }
            ],
            "createdBy": "example",
            "created_at": "2025-12-15T20:17:16.000000Z",
            "updated_at": "2025-12-15T21:04:53.000000Z"
        }
    ]
}

vouchers (GET)

Voucher specimens (GET lists, POST creates, PUT updates).

Fields returned

Fields (simple): id, individual_id, basisOfRecord, occurrenceID, organismID, collectionCode, catalogNumber, typeStatus, recordedByMain, recordNumber, recordedDate, recordedBy, scientificName, family, identificationQualifier, identifiedBy, dateIdentified, identificationRemarks, locationName, decimalLatitude, decimalLongitude, occurrenceRemarks, datasetName

Fields (all): id, individual_id, basisOfRecord, occurrenceID, organismID, collectionCode, catalogNumber, typeStatus, recordedByMain, recordNumber, recordedDate, recordedBy, scientificName, scientificNameAuthorship, taxonPublishedStatus, genus, family, identificationQualifier, identifiedBy, dateIdentified, identificationRemarks, locationName, higherGeography, decimalLatitude, decimalLongitude, georeferenceRemarks, occurrenceRemarks, datasetName, uuid

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 72209,
            "individual_id": 306246,
            "basisOfRecord": "PreservedSpecimens",
            "occurrenceID": "2639.Spruce.K.K000640463",
            "organismID": "2639_Spruce_1852",
            "collectionCode": "K",
            "catalogNumber": "K000640463",
            "typeStatus": "Tipo",
            "recordedByMain": "Spruce, R.",
            "recordNumber": "2639",
            "recordedDate": "1852-10",
            "recordedBy": "Spruce, R.",
            "scientificName": "Ecclinusa lanceolata",
            "scientificNameAuthorship": "(Mart. & Eichler) Pierre",
            "taxonPublishedStatus": "published",
            "genus": "Ecclinusa",
            "family": "Sapotaceae",
            "identificationQualifier": "",
            "identifiedBy": "Spruce, R.",
            "dateIdentified": "1852-10-00",
            "identificationRemarks": "",
            "locationName": "São Gabriel da Cachoeira",
            "higherGeography": "Brasil > Amazonas > São Gabriel da Cachoeira",
            "decimalLatitude": 1.1841927,
            "decimalLongitude": -66.80167715,
            "georeferenceRemarks": "decimal coordinates are the CENTROID of the footprintWKT geometry",
            "occurrenceRemarks": "OrganismRemarks = prope Panure ad Rio Vaupes Amazonas, Brazil",
            "datasetName": "Exsicatas LABOTAM",
            "uuid": "6302316f-2b48-43b5-816b-005df70d15c9"
        }
    ]
}

userjobs (GET)

Background jobs (imports/exports) (GET lists).

Fields returned

Fields (simple): id, dispatcher, status, percentage, created_at, affected_ids, affected_model

Fields (all): id, dispatcher, status, percentage, created_at, updated_at, affected_ids, affected_model, log

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 23652,
            "dispatcher": "App\\Jobs\\BatchUpdateIndividuals",
            "status": "Success",
            "percentage": "100%",
            "created_at": "2025-12-10T14:36:25.000000Z",
            "updated_at": "2025-12-10T14:36:28.000000Z",
            "affected_ids": [
                86136,
                57362,
                85053,
                72256,
                74543
            ],
            "affected_model": "App\\Models\\Individual",
            "log": "[]"
        }
    ]
}

activities (GET)

Lists activity log entries.

Fields returned

Fields (simple): id, log_name, description, subject_type, subject_name, subject_id, modified_by, properties, created_at, updated_at

Fields (all): id, log_name, description, subject_type, subject_id, subject_name, modified_by, properties, created_at, updated_at

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "field_key": "taxon_id",
            "field": "Taxon",
            "old_value": "Burseraceae",
            "new_value": "Protium hebetatum forma.b.fito",
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        },
        {
            "field_key": "person_id",
            "field": "Person",
            "old_value": "Macedo, M.T.S",
            "new_value": "Pilco, M.V.",
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        },
        {
            "field_key": "notes",
            "field": "Notes",
            "old_value": "Identificação feita em campo, anotada na planilha de dados.",
            "new_value": null,
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        },
        {
            "field_key": "date",
            "field": "Date",
            "old_value": "2022-06-17",
            "new_value": "2022-11-23",
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        }
    ]
}

tags (GET)

Tags/keywords (GET lists).

Fields returned

Fields (simple): id, name, description

Fields (all): id, name, description, counts

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 11,
            "name": "Folhas adaxial",
            "description": "Images of the adaxial surface of leaves",
            "counts": {
                "Media": 1852,
                "Project": 0,
                "Dataset": 0,
                "ODBTrait": 0
            }
        },
        {
            "id": 12,
            "name": "Folha forma",
            "description": "Imagem mostrando uma folha ou o formato da folha.",
            "counts": {
                "Media": 713,
                "Project": 0,
                "Dataset": 0,
                "ODBTrait": 0
            }
        },
        {
            "id": 13,
            "name": "Frutos",
            "description": "Imagens com frutos",
            "counts": {
                "Media": 2595,
                "Project": 0,
                "Dataset": 0,
                "ODBTrait": 0
            }
        }
    ]
}

3.3 - Post data

Importing data

Structured custom data in the notes field

The notes field of any model is for plain text or a text formatted as a JSON object containing structured data. Json allows you to store custom structured data in any model that has the notes field. For example, you may want to store secondary fields from source datasets during import, or any additional data not provided by the OpenDataBio database structure. This data is not validated by OpenDataBio and the standardization of tags and values is up to you. Json notes will be imported and exported as JSON text and will be presented in the interface as a formatted table; URLs in your Json will be presented as links in this table.

POST endpoints

Quick links

• bibreferences
• biocollections
• individuals
• individual-locations
• locations
• locations-validation
• measurements
• media
• persons
• taxons
• traits
• vernaculars
• vouchers
• datasets

bibreferences (POST)

Bibliographic references (GET lists, POST creates).

biocollections (POST)

Biocollections (GET lists, POST creates).

individuals (POST)

Individuals (GET lists, POST creates, PUT updates).

individual-locations (POST)

Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts).

locations (POST)

Locations (GET lists, POST creates, PUT updates).

locations-validation (POST)

Validates coordinates against registered locations (POST).

measurements (POST)

Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates).

media (POST)

Media metadata (GET lists, POST creates, PUT updates).

persons (POST)

People (GET lists, POST creates, PUT updates).

taxons (POST)

Taxonomic names (GET lists, POST creates).

traits (POST)

Trait definitions (GET lists, POST creates).

vernaculars (POST)

Vernacular names (GET lists, POST creates).

vouchers (POST)

Voucher specimens (GET lists, POST creates, PUT updates).

datasets (POST)

Datasets and published dataset files (GET lists, POST creates via import job).

3.4 - Put data

Quick links

• individuals
• individual-locations
• locations
• measurements
• media
• persons
• vouchers

individuals (PUT)

Individuals (GET lists, POST creates, PUT updates).

individual-locations (PUT)

Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts).

locations (PUT)

Locations (GET lists, POST creates, PUT updates).

measurements (PUT)

Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates).

media (PUT)

Media metadata (GET lists, POST creates, PUT updates).

persons (PUT)

People (GET lists, POST creates, PUT updates).

vouchers (PUT)

Voucher specimens (GET lists, POST creates, PUT updates).

4 - Concepts

4.1 - Core Objects

Core objects are: Location, Voucher, Individual and Taxon. These entities are considered “Core” because they may have Measurements, i.e. you may register values for any custom Trait.

• The Individual object refer to Individual organism that have been observed once (an occurrence) or has been tagged for monitoring, such as tree in a permanent plot, a banded bird, a radio-tracked bat. Individuals may have one or more Vouchersin a BioCollection, and one or multiple Locations, and will have a taxonomic Identification. Any attribute measured or taken for individual organism may be associated with this object through the Measurement Model model.

• The Voucherobject is for records of specimens from Individuals deposited in a Biological Collection. The taxonomic Identification and the Location of a Voucher is that of the Individual it belongs to. Measurements may be linked to a Voucher when you want to explicitly register the data to that particular sample (e.g. morphological measurements; a molecular marker from an extraction of a sample in a tissue collection). Otherwise you could just record the Measurement for the Individual the Voucher belongs to. The voucher model is also available as special type of Trait, the LinkType, making it possible to record counts for the voucher’s Taxon at a particular Location.

• The Location object contains spatial geometries, like points and polygons, and include plots and transects as special cases. An Individual may have one location (e.g. a plant) or more locations (e.g. a monitored animal). Plots and Transect locations may be registered as a spatial geometry or only point geometry, and may have Cartesian dimensions (meters) registered. Individuals may also have Cartesian positions (X and Y or Angle and Distance) relative to their Location, allowing to account for traditional mapping of individuals in sampling units. Ecological relevant measurements, such as soil or climate data are examples of measurements that may be linked to locations Measurement.

• The Taxon object in addition to its use for the Identification of Individuals, may receive Measurements, allowing the organization of secondary, published data, or any kind of information linked to a Taxonomic name. A BibReference may be included to indicate the data source. Moreover, the Taxon model is available as special type of Trait, the LinkType, making it possible to record counts for Taxons at a particular Location.
  
  

This figure show the relationships among the Core objects and with the Measurement Model. The Identification Model is also included for clarity. Solid links are direct relationships, while dashed links are indirect relationships (e.g. Taxons has many Vouchers through Individuals, and have many Individuals through identifications). The red solid lines link the Core objects with the Measurement model through polymorphic relationships. The dotted lines on the Measurement model just allow access to the measured core-object and to the models of link type traits.

Location Model

The Locations table stores data representing real world locations. They may be countries, cities, conservation units, or any spatial polygon, point or linestring on the surface of Earth. These objects are hierarchical and have a parent-child relationship implemented using the Nested Set Model for hierarchical data of the Laravel library Baum and facilite both validation and queries.

Special location types are plots and transects, which together with point locations allow different sampling methods used in biodiversity studies. These Location types may also be linked a parent location and in addition also to three additional types of location that may span different administrative boundaries, such as Conservation Units, Indigenous Territories and any Environmental layer representing vegetation classes, soil classes, etc…with defined spatial geometries.

This figure shows the relationships of the Location model throught the methods implemented in the shown classes. The pivot table linking Location to Individual allow an individual to have multiple locations and each location for the individual to have specific attributes like date_time, altitude, relative_position and notes.

The same tables related with the Location model with the direct and non-polymoprhic relationships indicated.

Location Table Columns

• Columns parent_id together with rgt, lft and deph are used to define the Nested Set Model to query ancestors and descendants in a fast way. Only parent_id is specified by the user, the other columns are calculated by the Baum library trait from the id+parent_id values that define the hierarchy. The same hierarchical model is used for the Taxon Model, but for Locations there is a spatial constraint, i.e. a children must fall within a parent geometry.
• The adm_level column indicate the administrative level, or type, of a location. By default, the following adm_level are configured in OpenDataBio:
  • 2 for country, 3 for first division within country (province, state), 4 for second division (e.g. municipality),… up to adm_level=10 as administrative areas (country code is 2 to allow standardization with OpenStreeMaps, which is recommended to follow if your installation will include data from different countries). The administrative levels may be configured in an OpenDataBio before importing any data to the database, see the installation guide for details on that.
  • 99 is the code for Conservation Units - a conservation unit is a location that may be linked to multiple other locations (any location may belong to a single UC). Thus, one Location may have as parent a city and as uc_id the conservation unit where it belongs.
  • 98 is the code for Indigenous Territories - same properties as Conservation Units, but treated separately only because some CUs and TIs may largely overlap as is the case the Amazon region
  • 97 ise the code for Environmental layers - same properties as Conservation Units and Indigenous Territories, i.e., may be linked as additional location to any Point, Plot or Transect, and thehence, their related individuals. Store polygons and multipolygon geometries representing environmental classes, such as vegetation units, biomes, soil classes, etc…
  • 100 is the code for plots and subplots - plot locations may be registered with Point or with a Polygon geometry, and must also have an associated Cartesian dimensions in meters. If it is a point location, the geometry is defined by ODB from the dimensions with NorthEast orientation from the point informed. Cartesian dimensions of a plot location can also be combined with cartesian positions of subplots (i.e. a plot location whose parent is also a plot location) and/or of individuals within such plots, allowing individuals and subplots to be mapped within a plot subplot location without geometry specifications. In other words, if the spatial geometry of the plot is unknown, it may have as geometry a single GPS point rather than a polygon, plus its x and y dimensions. A subplot is location plot inside a location plot and must consist of a point marking the start of the subplot plus its X and Y cartesian dimensions. If the geometry of the start of the subplot is unknown, it may be stored as a relative position to parent plot using the startx and starty.
  • 101 for transects - like plots, transects may be registered having a LineString geometry or simply a single Latitude and Longitude coordinates and a dimension. The x cartesian dimension for transects represent the length in meters and is used to create a linestring (North oriented) when only a point is informed. The y dimension is used to validate individuals as belonging to transect location, and represents the maximum distance from the line that and individual must fall to be detected in that location.
  • 999 for ‘POINT’ locations like GPS waypoints - this is for registration of any point in space
• Column datum may record the geometry datum property, if known. If left blank, the location is considered to be stored using WGS84 datum. However, there is no built-in conversor from other types of data, so the maps displayed may be incorrect if different datum’s are used. Strongly recommended to project data as WSG84 for standardization.
• Column geom stores the location geometry in the database, allowing spatial queries in SQL language, such as parent autodetection. The geometry of a location may be POINT, POLYGON, MULTIPOLYGON or LINESTRING and must be formatted using Well-Known-Text geometry representation of the location. When a POLYGON is informed, the first point within the geometry string is privileged, i.e. it may be used as a reference for relative markings. For example, such point will be the reference for the startx and starty columns of a subplot location. So for plot and transect geometries, it matters which point is listed first in the WKT geometry

Data access Full users may register new locations, edit locations details and remove locations records that have no associated data. Locations have open access!

Individual Model

The Individual object represents a record for an individual organism. It may be a single time-space occurrence of an animal, plant or fungi, or an individual monitored through time, such as a plant in a permanent forest plot, or an animal in capture-recapture or radio-tracking experiment.

An Individual may have one or more Vouchersrepresenting physical samples of the individual stored in one or more Biological Collection and it may have one or more Locations, representing the place or places where the individual has been recorded.

Individual objects may also have a self taxonomic Identification or its taxonomic identity may depend on that of another individual (non-self identification). The Individual identification is inherited by all the Vouchers registered for the Individual. Hence Vouchers do not have their separate identification.

This figure shows the Individual Model and the models it relates to, except the Measurement and Location models, as their relationships with Individuals is shown elsewhere in this page. Lines linking models indicate the methods or functions implemented in the classes to access the relationships. Dashed lines indicate indirect relationships and the colors the different types of Laravel Eloquent methods.

The Individual model direct and non-polymoprhic relationships.

Individual Table Columns

• A Individual record must specify at least one Location where it was registered, the date of registration, the local identifier tag, and the collectors of the record, and the dataset_id the individual belongs to.
• The Location may be any location registered, regardless of level, allowing to store historical records whose georeferencing is just an administrative location. Individual locations are stored in the individual_location pivot table, having columns date_time, altitude, notes and relative_position for the individual location records.
• The column relative_position stores the Cartesian coordinates of the Individual in relation to its Location. This is only for individuals located in locations of type plot, transect or point. For example, a Plot location with dimensions 100x100 meters (1ha) may have an Individual with relative position=POINT(50 50), which will place the individual in the center of the location (this is shown graphically in the web-interface), as is defined by the x and y coordinates of the individual. If the location is a subplot, then the position within the parent plot may also be calculated (this was designed with ForestGeo plots in mind and is a column in the Individual GET API. If the location is a POINT, the relative_position may be informed as angle (= azimuth) and distance, attributes frequently measured in sampling methods. If the location is a TRANSECT, the relative_position places the individual in relation to the linestring, the x being the distance along the transect from the first point, and the y the perpendicular distance where the individual is located, also accounting for some sampling methods;
• The date field in the Individual, Voucher, Measurement and Identification models may be an Incomplete Date, i.e., only the year or year+month may be recorded.
• The Collector table represents collectors for an Individual or Voucher, and is linked with the Person Model. The collector table has a polymorphic relationship with the Voucher and Individual objects, defined by columns object_id and object_type, allowing multiple collectors for each individual or voucher record. The main_collector indicated is just the first collector listed for these entities.
• The tag field is a user code or identifier for the Individual. It may be the number written on the aluminum tag of a tree in a forest plot, the number of a bird-band, or the collector number of a specimen. The combination of main_collector+tag+first_location is constrained to be unique in OpenDataBio.
• The taxonomic identification of an Individual may be defined in two ways:
  • for self identifications an Identification record is created in the identifications table, and the column identification_individual_id is filled with the Individual own id
  • for non-self identifications, the id of the Individual having the actual Identification is stored in column identification_individual_id.
  • Hence, the Individual class contain two methods to relate to the Identification model: one that sets self identifications and another that retrieves the actual taxonomic identifications by using column identification_individual_id.
• Individuals may have one or more Vouchersdeposited in a Biocollection.
  
  Data access Individuals belong to Datasets, so Dataset access policy apply to the individuals in it. Only project collaborators and administrators may insert or edit individuals in a dataset, even if dataset is of public access.

Taxon Model

The general idea behind the Taxon model is to present tools for easily incorporating valid taxonomic names from Online Taxonomic Repositories (currently Tropicos.org and GBIF are implemented), but allowing for the inclusion of names that are not considered valid, either because they are still unpublished (e.g. a morphotype), or the user disagrees with published synonymia, or the user wants to have all synonyms registered as invalid taxons in the system. Moreover, it allows one to define a custom clade level for taxons, allowing one to store, in addition to taxonomic rank categories, any node of the tree of life. Any registered Taxon can be used in Individual identifications and Measurements may be linked to taxonomic names.

Taxon model and its relationships. Lines linking tables indicate the methods implemented in the shown classes, with colors indicating different Eloquent relationships

Taxon table explained

• Like, Locations, the Taxon model has a parent-child relationship, implemented using the Nested Set Model for hierarchical data of the Laravel library Baum that allows to query ancestors and descendants. Hence, columns rgt, lft and deph of the taxon table are automatically filled by this library upon data insertion or update.
• For both, Taxon author and Taxon bibreference there are two options:
  • For published names, the string authorship retrieved by the external taxon APIs will be placed in the author=string column. For unpublished names, author is a Person and will be stored in the author_id column.
  • Only published names may have relation to BibReferences. The bibreference string field of the Taxon table stores the strings retrieved through the external APIs, while the bibreference_id links to a BibReference object. These are used to store the Publication where the Taxon Name is described and may be entered in both formats.
  • In addition, a Taxon record may also have many other BibReferences through a pivot table (taxons_bibreference), permitting to link any number of bibliographic references to a Taxon name.

• Column level represents the taxonomic rank (such as order, genera, etc). It is numerically coded and standardized following the IAPT general rules, but should accommodate also animal related taxon level categories. See the available codes in the Taxon API for the list of codes.
• Column parent_id indicates the parent of the taxon, which may be several levels above it. The parent level should be strictly higher than the taxon level, but you do not need to follow the full hierarchy. It is possible to register a taxon without parents, for example, an unpublished morphotype for which both genera and family are unknown may have an order as parent.
• Names for the taxonomic ranks are translated according to the system defined locale that also translates the web interface (currently only Portuguese and English implemented).
• The name field of the taxon table contain only the specific part of name (in case of species, the specific epithet), but the insertion and display of taxons through the API or webinterface should be done with the fullname combination.
• It is possible to include synonyms in the Taxon table. To do so, one must fill in the senior relationship, which is the id of the accepted (valid) name for an invalid Taxon. If senior_id is filled, then the taxon is a junior synonym and must be flagged as invalid.
• When inserting a new published taxon, only the name is required. The name will be validated and the author, reference and synonyms will be retrieved using the following API services:
  1. GBIF BackBone Taxonomy - this will be the first check, from which links to Tropicos and IPNI may also be retrieved if registering a plant name.
  2. Tropicos - if not found on GBIF, ODB will search the name on the Missouri Botanical Garden nomenclature database.
  3. IPNI - the International Individual Names Index is another database used to validate individual names (Temporarily disabled)
  4. MycoBank - used to validate a name if not found by the Tropicos nor IPNI apis, and used to validate names for Fungi. Temporarily disabled
  5. ZOOBANK - when GBIF, Tropicos, IPNI and MycoBank fails to find a name, then the name is tested against the ZOOBANK api, which validates animal names. Does not provide taxon publication, however.
• If a Taxon name is found in the Nomenclatural databases, the respective ID of the repository is stored in the taxon_external tables, creating a link between the OpenDataBio taxon record and the external nomenclatural database.
• A Person may be defined as one or more taxon specialist through a pivot table. So, a Taxon object may have many taxonomic specialist registered in OpenDataBio.

Data access: Full users are able to register a new taxon and edit existing records if they have not been used for Identification of Measurements. Currently it is impossible to remove a taxon from the database. Taxon list have public access.

Voucher Model

The Voucher model is used to store records of specimens or samples from Individuals deposited in Biological Collections. Therefore, the only mandatory information required to register a Voucher are individual, biocollection and whether the specimen is a nomenclature type (which defaults to non-type if not informed).

Voucher model and its relationships. Lines linking tables indicate the methods implemented in the shown models, with colors indicating different Eloquent relationships. Not that Identification nor Location are show because Vouchers do not have their own records for these two models, they are just inherited from the Individual the Voucher belongs to

Vouchers table explained

• A Voucher belongs to an Individual and a Biocollection, so the individual_id and the biocollection_id are mandatory in this table;
• biocollection_number is the alpha-numeric code of the Voucher in the BioCollection, it may be ’null’ for users that just want to indicate that a registered Individual have Vouchers in a particular Bicollection, or to registered Vouchers for biocollections that do not have an identifier code;
• biocollection_type - is a numeric code that specify whether the Voucher in the BioCollection is a nomenclatural type. Defaults to 0 (Not a Type); 1 for just ‘Type’, a generic form, and other numbers for other nomenclature type names (see the API Vouchers Endpoint for a full list of options).
• collectors, one or multiple, are optional for Vouchers, required only if they are different from the Individual collectors. Otherwise the Individual collectors are inherited by the Voucher. Like for Individuals, these are implemented through a polymorphic relationship with the collectors table and the first collector is the main_collector for the voucher, i.e. the one that relates to number.
• number, this is the collector number, but like collectors, should only be filled if different from the Individual’s tag value. Hence, collectors, number and date are useful for registering Vouchers for Individuals that have Vouchers collected at different times by different people.
• date field in the Individual and Voucher models may be an incomplete date. Only required if different from that of the Individual the Voucher belongs to.
• dataset_id the Voucher belongs to a Dataset, which controls the access policy;
• notes any text annotation for the Voucher.
• The Voucher model interacts with the BibReference model, permitting to link multiple citations to Vouchers. This is done with a pivot voucher_bibreference table.

Data access Vouchers belong to Datasets, so Dataset access policy apply to the Vouchers in it. Vouchers may have a different Project than their Individuals. If the Voucher dataset policy is open access and that of the Individual project is not, then access to voucher data will be incomplete, so Voucher’s dataset should have the same or less restricted access policy than the Individual dataset. Only Dataset collaborators and administrators may insert or edit vouchers in a dataset, even if the dataset is of public access.

4.2 - Trait Objects

Measurement Model

The Measurements table stores the values for traits measured for core objects. Its relationship with the core objects is defined by a polymorphic relationship using columns measured_id and measured_type. These MorphTo relations are illustrated and explained in the core objects page.

• Measurements must belong to a Dataset - column dataset_id, which controls measurement access policy
• A Person must be indicated as a measurer (person_id);
• The bibreference_id column may be used to link measurements extracted from publications to its Bibreference source;
• The value for the measured trait (trait_id) will be stored in different columns, depending on trait type:
  • value - this float column will store values for Quantitative Real traits;
  • value_i - this integer column will store values for Quantitative Integer traits; and is an optional field for Link type traits, allowing for example to store counts for a species (a Taxon Link trait) in a location.
  • value_a - this text column will store values for Text, Color and Spectral trait types.
• Values for Categorical and Ordinal traits are stored in the measurement_category table, which links measurements to trait categories.
• date - measurement date is mandatory in all cases

Data access Measurements belong to Datasets, so Dataset access policy apply to the measurements in it. Only dataset collaborators and administrators may insert or edit measurements in a dataset, even if the dataset is of public access.

Trait Model

The ODBTrait table represents user defined variables to collect Measurements for one of the core object, either Individual, Voucher, Location or Taxon.

These custom traits give enormous flexibility to users to register their variables of interest. Clearly, such flexibility has a cost in data standardization, as the same variable may be registered as different Traits in any OpenDataBio installation. To minimize redundancy in trait ontology, users creating traits are warned about this issue and a list of similar traits is presented in case found by trait name comparison.

Traits have editing restrictions to avoid data loss or unintended data meaning change. So, although the Trait list is available to all users, trait definitions may not be changed if somebody else also used the trait for storing measurements.

Traits are translatable entities, so their name and description values can be stored in multiple languages (see User Translations. This is placed in the user_translations table through a polymorphic relationship.

The Trait definition should be as specific as needed. The measurement of tree heights using direct measurement or a clinometer, for example, may not be easily converted from each other, and should be stored in different Traits. Thus, it is strongly recommended that the Trait definition field include information such as measurement instrument and other metadata that allows other users to understand whether they can use your trait or create a new one.

• The Trait definition must include an export_name for the trait, which will be used during data exports and are more easily used in trait selection inputs in the web-interface. Export names must be unique and have no translation. Short and camelCase or PascalCase export names are recommended.
• The following trait types are available:
  • Quantitative real - for real numbers;
  • Quantitative integer - for counts;
  • Categorical - for one selectable categories;
  • Categorical multiple - for many selectable categories;
  • Categorical ordinal - for one selectable ordered categories (semi-quantitative data);
  • Text - for any text value;
  • Color - for any color value, specified by the hexadecimal color code, allowing renderizations of the actual color.
  • Link - this is a special trait type in OpenDataBio to link to database object. Currently, only link to Taxons and Voucher are allowed as a link type traits. Use ex: if you want to store species counts conducted in a location, you may create a Taxon link type Trait or a Voucher link type Trait if the taxon has vouchers. A measurement for such trait will have an optional value field to store the counts. This trait type may also be used to specify the host of a parasite, or the number of predator insects.
  • Spectral - this is designed to accommodate Spectral data, composed of multiple absorbance or reflectance values for different wavenumbers.
  • GenBank - this stores GenBank accessions numbers allowing to retrieve molecular data linked to individuals or vouchers stored in the database through the GenBank API Service.
• The Traits table contains fields that allow measurement value validation, depending on trait type:
  • range_max and range_min - if defined for Quantitative traits, measurements will have to fit the specified range;
  • value_length - mandatory for Spectral Traits only, validate the length (number of values) of a spectral measurement;
  • link_type - if trait is Link type, the measurement value_i must be an id of the link type object;
  • Color traits are validated in the measurement creation process and must conform to a color hexadecimal code. A color picker is presented in the web interface for measurement insertion and edition;
  • Categorical and ordinal traits will be validated for the registered categories when importing measurements through the API;
• Column unit defines the measurement unit for the Trait. There is no way to prevent measurements values imported with a distinct unit. Quantitative traits required unit definition.
• Column bibreference_id is the key of a single BibReference that may be linked to trait definition.
• The trait_objects table stores the type of core object (Taxon, Location, Voucher) that the trait can have a measurement for;

Data access A Trait name, definition, unit and categories may not be updated or removed if there is any measurement of this trait registered in the database. The only exceptions are: (a) it is allowed to add new categories to categorical (not ordinal) traits; (b) the user updating the trait is the only Person that has measurements for the trait; (c) the user updating the trait is an Admin of all the datasets having measurements using trait.

Forms

A Form is an organized group of Traits, defined by a User in order to create a custom form that can be filled in for entering measurements through the web interface. A Form consists of a group of ordered Traits, which can be marked as “mandatory”. Related entities are the Report and the Filter.

This is still experimental and needs deeper testing

4.3 - Data Access Objects

Datasets control data access and represents a dynamic data publication, with a version defined by last edition date. Datasets may contain Measurements, Individuals, Vouchers and/or Media Files.

Projects are just groups of Datasets and Users, representing coohorts of users with common accessibility to datasets whose privacy are set to be controlled by a Project.

BioCollections - This model serves to create a reusable list of acronyms of Biological Collections to record Vouchers. However, you can optionally manage a collection of Vouchers and their Individuals, in parallel to the access control provided by Datasets. Control is only for editing and entering Voucher records. In this case, the BioCollection is managed by the system.

Projects and BioCollections must have at least one User defined as administrator, who has total control over the dataset or project, including granting the following roles to other users: administrator, collaborator or viewer:

• Collaborators are able to insert and edit objects, but are not able to delete records nor change the dataset or project configuration.
• Viewers have read-only access to the data that are not of open access.
• Only Full Users and SuperAdmins may be assigned as administrators or collaborators. Thus, if a user who was administrator or collaborator of a dataset is demoted to “Registered User”, she or he will become a viewer.
• Only Super-admins can enable a BioCollection to be administered by the system.

Biocollections

The Biocollection model has two functions: (1) to provide a list of acronyms for registering Vouchers of any Biological Collection; (2) to manage the data of Biological Collections, facilitating the registration of new data (any user enters their data using the validations carried out by the software and requests the collection’s curators through the interface to register the data, which is done by authorized users for the BioCollection. Upon data registration, the BioCollection controls the editing of the data of the Vouchers and the related Individuals. Option (2) needs to be implemented by a Super-Administrator user, who can enable a BioCollection to be administered by the system, implementing the ODBRequest request model so that users can request data, samples, or records and changes to the data.

The Biocollection object may be a formal Biocollection, such as those registered in the Index Herbariorum (http://sweetgum.nybg.org/science/ih/), or any other Biological Collection, formal or informal.

The Biocollection object also interacts with the Person model. When a Person is linked to an Biocollection it will be listed as a taxonomic specialist.

Data access - Full users can register BioCollections, but only super administrator can make a BioCollection manageable by the system. Removing BioCollections can be done if there are no Vouchers attached and if it is not administered by the system. If manageable, the model interacts with Users, which can be administrators (curators, anything can) or collaborators (can enter and edit data, but cannot delete records). Data from other Datasets can be part of the BioCollection, allowing users to have their complete data, but editing control of records is by the BioCollection authorized users.

Datasets

DataSets are groups of Measurements, Individuals, Vouchers and/or Media Files, and may have one or more Users administrators, collaborators or viewers. Administrators may set the privacy level to public access, restricted to registered users or restricted to authorized users or restricted to project users. This control access to the data within a dataset as exemplified in diagram below:

Datasets may also have many Bibliographic References, which together with fields policy, metadata permits to annotate the dataset with relevant information for data sharing: * Link any publication that have used the dataset and optionally indicate that they are of mandatory citation when using the data; * Define a specific data policy when using the data in addition to the a CreativeCommons.org public license; * Detail any relevant metadata in addition to those that are automatically retrieved from the database like the definitions of the Traits measured.

Projects

Projects are just groups of Datasets and interacts with Users, having administrators, collaborators or viewers. These users may control all datasets within the Project having a restricted to project users access policy.

Users

The Users table stores information about the database users and administrators. Each User may be associated with a default Person. When this user enters new data, this person is used as the default person in forms. The person can only be associated to a single user.

There are three possible access levels for a user: * Registered User (the lowest level) - have very few permissions * Full User - may be assigned as administrators or collaborators to Projects and Datasets; * SuperAdmin (the highest level). - superadmins have have access to all objects, regardless of project or dataset configuration and is the system administrator.

Each user is assigned to the registered user level when she or he registers in an OpenDataBio system. After that, a SuperAdmin may promote her/him to Full User or SuperAdmin. SuperAdmins also have the ability to edit other users and remove them from the database.

Every registered user is created along with a restricted Project and Dataset, which are referred to as her user Workspace. This allows users to import individual and voucher data before incorporating them into a larger project. [TO IMPLEMENT: export batches of objects from one project to another].

Data Access:users are created upon registration. Only administrators can update and delete user records.

User Jobs

The UserJob table is used to store temporarily background tasks, such as importing and exporting data. Any user is allowed to create a job; cancel their own jobs; list jobs that have not been deleted. The Job table contains the data used by the Laravel framework to interact with the Queue. The data from this table is deleted when the job runs successfully. The UserJob entity is used to keep this information, along with allowing for job logs, retrying failed jobs and canceling jobs that have not yet finished.

Data Access: Each registered user can see, edit and remove their own UserJobs.

4.4 - Auxiliary Objects

BibReference Model

The BibReference table contains basically BibTex formatted references stored in the bibtex column. You may easily import references into OpenDataBio by just specifying the doi, or simply uploading a bibtex record. These bibliographic references may be used to:

• Store references for Datasets - with the option of defining references for which citation is mandatory when using the dataset in publications; but all references that have used the dataset may be linked to the dataset; links are done with a Pivot table named dataset_bibreference;
• Store the references for Taxons:
  • to specify the reference in which the Taxon name was described, currently mandatory in some Taxonomic journals like PhytoTaxa. This description reference is stored in the bibreference_id of the Taxons table.
  • to register any reference to a Taxon name, which are then linked through a pivot table named taxons_bibreference.
• Link a Measurement to a published source;
• Indicate the source of a Trait definition.
• Indicate mandatory citations for a Dataset, or link references using the data to a Dataset

BibReference model and its relationships. Lines linking tables indicate the methods implemented, with colors indicating different Eloquent relationships.

Bibreferences table

• The BibtexKey, authors and other relevant fields are extracted from the bibtex column.
• The Bibtexkey must be unique in the database, and a helper function is be provided to standardize it with format <von? last name> <year> <first word of title>. The “von part” of the name is the “von”, “di”, “de la”, which are part of the last name for some authors. The first word of the title ignores common stop-words such as “a”, “the”, or “in”.
• DOIs for a BibReference may be specified either in the relevant BibTex field or in a separate text input, and are stored in the doi field when present. An external API finds the bibliographic record when a user informs the doi.

Identification Model

The Identification table represents the taxonomic identification of Individuals.

Identification model and its relationships. Lines linking tables indicate the methods implemented, with colors indicating different Laravel Eloquent relationships

Identifications table

• The Identification model includes several optional fields, but in addition to taxon_id, person_id, the Person responsible for the identification, and the identification date are mandatory.

• The date value may be an Incomplete Date, e.g. only the year or year+month may be recorded.

• The following fields are optional:
  • modifier - is a numeric code appending a taxonomic modifier to the name. Possible values ’s.s.’=1, ’s.l.’=2, ‘cf.’=3, ‘aff.’=4, ‘vel aff.’=5, defaults to 0 (none).
  • notes - a text of choice, useful for adding comments to the identification.
  • biocollection_id and biocollection_reference - these fields are to be used to indicate that the identification is based upon comparison to a voucher deposited in a Biological Collection and creates a link between the Individual identified and the BioCollection specimen from which the identification is based upon. biocollection_id stores the Biocollection id, and biocollection_reference the unique identifier of the specimen compared, i.e. would be the equivalent of the biocollection_number of the Voucher model, but this reference does not need to be from a voucher registered in the database.
• The relationship with the Individual model is defined by a polymorphic relationship using fields object_type and object_id [This could be replaced by an ‘individual_id’ in the identification table. The polymorphic relation inherited from a previous development version, kept because the Identification model may be used in the future to link Identifications to Measurements].
• Changes in identifications are audited for tracking change history

Data access: identifications are attributes of Individuals and do not have independent access!

Person Model

The Person object stores persons names, which may or may not be a User directly involved with the database. It is used to store information about people that are: * collectors of Vouchers, Individuals and MediaFiles * taxonomic determinators or identifiers of individuals; * measurer of Measurements; * authors for unpublished Taxon names; * taxonomic specialists - linked with Taxon model by a pivot table named person_taxon; * dataset authors - defining authors for the dynamic publication of datasets;

Person model and its relationships. Lines linking tables indicate the methods implemented, with colors indicating different types of Laravel Eloquent methods, solid lines the direct and dashed the indirect relationships

Persons table

• mandatory columns are the person full_name and abbreviation;
• when registering a new person, the system suggests the name abbreviation, but the user is free to change it to better adapt it to the usual abbreviation used by each person. The abbreviation must be unique in the database, duplicates are not allowed in the Persons table. Therefore, two persons with the exact same name must be differentiated somehow in the abbreviation column.
• The biocollection_id column of the Persons table is used to list to which Biocollection a person is associated, which may be used when the Person is also a taxonomic specialist.
• Additionally, the email and institution the person belongs to may also be informed.
• Each user can be linked to a Person by the person_id in the User table. This person is then used the ‘default’ person when the user is logged into the system.

Media Model

Media files are similar to measurements in that they might be associated with any core object. Media files may be images (jpeg, png, gif, tif), video or audio files and can be made freely accessible or placed in a Dataset with a defined access policy. A CreativeCommons.org license must be assigned to them. Media files may be tagged, i.e. you may define keywords to them, allowing to query them by Tags. For example, an individual image may be tagged with ‘flowers’ or ‘fruits’ to indicate what is in the image, or a tag that informs about image quality.

• Media files (image, video, audio) are linked to the Core-Objects through a polymorphic relationship defined by columns model_id and model_type.
• Multiple Persons may be associated with the Media for credits, these are linked with the Collectors table and its polymorphic relationship structure.
• A Media may have a description in each language configured in the Language table, which will be stored in the user_translations table, which relates to the Tag model through a polymorphic relationship. Inputs for each language are shown in the web-interface forms.
• Media files are not stored in the database, but in the server storage folder.
• It is possible to batch upload media files through the web interface, requiring also a file informing the objects to link the media with.

Data access full users may register media files and delete the ones they have inserted. If Media is in a Dataset, dataset admins may delete the media in addition to the user. Media files have public access, except when linked to a Dataset with access restrictions.

Tag Model

The Tag model allows users to define translatable keywords that may be used to flag Datasets, Projects or MediaFiles. The Tag model is linked with these objects through a pivot table for each, named dataset_tag, project_tag and media_tag, respectively.

A Tag may have name and description in each language configured in the Language table, which will be stored in the user_translations table, which relates to the Tag model through a polymorphic relationship. Inputs for each language are shown in the web-interface forms.

Data access full users may register tags, edit those they have inserted and delete those that have not been used. Tags have public access as they are just keywords to facilitate navigation.

User Translation Model

The UserTranslation model translates user data: Trait and Trait Categories names and descriptions, MediaFiles descriptions and Tags. The relations between these models are established by polymorphic relations using fields translatable_type and translatable_id. This model permits translations to any language listed in the Language table, which is currently only accessible for insertion and edition directly in the SQL database. Input forms in the web interface will be listed for registered Languages.

Vernacular - Popular Name

The Vernacular and VernacularCitation templates allow you to record popular names of organisms by relating them to Taxons and/or Individuals. Names must be unique in the Vernacular table, and each record can be linked to multiple Taxa and/or Individuals, depending on the information sources. Each record can also have one or more citations (citation text + BibReference + note).

Incomplete Dates

Dates for Vouchers, Individuals, Measurements and Identifications may be Incomplete, but at least year is mandatory in all cases. The date columns in the tables are of ‘date’ type, and incomplete dates are stored having 00 in the missing part: ‘2005-00-00’ when only year is known; ‘1988-08-00’ when only month is known.

Auditing

Modifications in database records are logged to the activity_log table. This table is generated by the package ActivityLog. The activities are shown in a ‘History’ link provided in the Show.view of the models.

1. The package stores changes as json in the properties field, which contains two elements: attributes and old, which are basically the new vs old values that have been changed. This structure must be respected.
2. Class ActivityFunctions contain custom functions to read the the properties Json record stored in the activity_log table and finds the values to show in the History datatable;
3. Most changes are logged by the package as a ’trait’ called within the Class. These allow to automatically log most updates and are all configured to log only the fields that have changed, not entire records (option dirty). Also record creation are not logged as activity, only changes.
4. Some changes, like Individual and Vouchers collectors and identifications are manually logged, as they involve related tables and logging is specified in the Controller files;
5. Logging contain a log_name field that groups log types, and is used to distinguish types of activity and useful to search the History Datatable;
6. Two special logging are also done:
7. Any Dataset download is logged, so administrators may track who and when the dataset was downloaded;
8. Any Dataset request is also logged for the same reason

The clean-command of the package SHOULD NOT be used during production, otherwise will just erase all logged changes. If run, will erase the logs older than the time specified in the /config/activitylog.php file.

• causer_type and causer_id will be the User that made the change
• subject_type and subject_id will the model and record changed
• log_name - to group logs together and permits queries
• description - somewhat redundant with log_name in a OpenDataBio context.
• properties - stores the changes, for example, and identification change will have a log like:

{
    "attributes":
    {
        "person_id":"2",
        "taxon_id":"1424",
        "modifier":"2",
        "biocollection_id":"1",
        "biocollection_reference":"1234",
        "notes":"A new fake note has been inserted",
        "date":"2020-02-08"},
    "old":{
        "person_id":674,
        "taxon_id":1413,
        "date":"1995-00-00",
        "modifier":0,
        "biocollection_id":null,
        "notes":null,
        "biocollection_reference":null
    }
}

5 - Contribution Guidelines

Report bugs & suggest improvements

Post an issue on one of the GitLab repositories below, depending on the issue.

Before posting, check if an open issue does already contains what you want to report, ask or propose.

Tag your issue with one or more appropriate labels.

Collaborate with development, language translations and docs

We expect this project to grow collaboratively, required for its development and use in the long term. Therefore, developer collaborators are welcome to help fixing and improving OpenDataBio. The issues list is a place to start to know what is needed.

The following guidelines are recommend if you want to collaborate:

1. Communicate with the OpenDataBio repository maintainer indicating which issues you want to work on and join the development team.
2. Fork the repository
3. Create a branch to commit your modifications or additions
4. When happy with results, make a pull request to ask the project maintainer to review your contribution and merge it to the repository. Consult GitLab Help for more information on using pull requests.

Programming directives

1. Use the docker installation for development, which shared among all developers facilitates debug. The Laravel-Datatables library is incompatible with php artisan serve, so this command should not be used.
2. This software should adhere to Semantic Versioning, starting from version 0.1.0-alpha1. The companion R package and the Documentation (this site) should follow a similar versioning scheme. When changing version, a release tag must be created with the old version.
3. All variables and functions should be named in English, with entities and fields related to the database being named in the singular form. All tables (where appropriate) should have an “id” column, and foreign keys should reference the base table with “_id” suffix, except in cases of self-joins (such as “taxon.parent_id”) or polymorphic foreign keys. The id of each table has type INT and should be autoincrementing.
4. Use laravel migration class to add any modification to the database structure. Migration should include, if apply, management of existing data.
5. Use camelCase for methods (i.e. relationships) and snake_case for functions.
6. Document the code with comments and create documentation pages if necessary.
7. There should be a structure to store which Plugins are installed on a given database and which are the compatible system versions.
8. This system uses Laravel Mix to compile the SASS and JavaScript code used. If you add or modify these npm run prod after making any change to these files.

Collaborate with the docs

We welcome Tutorials for dealing with specific tasks.

To create a tutorial:

1. Fork the documentation repository. When cloning this repository or a fork, include the submodule option to also get the included Docsy theme repository. You will need Hugo to run this site in your localhost.
2. Create a branch to commit your modifications or additions
3. Add your tutorial:

• Create a folder within the contents/{lang}/docs/Tutorials using kebab-case for the folder name. Ex. first-tutorial
• You may create a tutorial in single language, or on multiple languages. Just place it in the correct folder
• Within the created folder, create a file named _index.md and create the markdown content with your tutorial.
• You may start copying the content of an existing tutorial.

1. When happy with results, make a pull request to ask the project maintainer to review your contribution and merge it to the repository. Consult GitLab Help for more information on using pull requests.

Collaborate with translations

You may help with translations for the web-interface or the documentation site. If want to have a new language for your installation, share your translation, creating a pull request with the new files.

New language for the web-interface:

1. fork and create a branch for the main repository
2. create a folder for the new language using the ISO 639-1 Code within the resources/lang folder

   cd opendatabio
   cd resources/lang
   cp en es
   

3. translate all the values for all the variables within all the files in the new folder (may use google translation to start, just make sure variable names are not translated, otherwise, it will not work)
4. add language to array in config/languages.php
5. add language to database language table creating a laravel migration
6. make a pull request

New language for the documentation site

1. fork and create a branch for the documentation repository
2. create a folder for the new language using the ISO 639-1 Code within the content folder

   cd opendatabio.gitlab.io
   cd contents
   cp pt es
   

3. check all files within the folder and translate where needed (may use google translation to start, just make sure to translate only what can be translated)
4. push to your branch and make a pull request to the main repository

Polymorphic relations

Some of the foreign relations within OpenDataBio are mapped using Polymorphic relations. These are indicated in a model by having a field ending in _id and a field ending in _type. For instance, all Core-Objects may have Measurements, and these relationships are established in the Measurements table by the measured_id and the measured_type columns, the first storing the related model unique id, the second the measured model class in strings like ‘App\Models\Individual’, ‘App\Models\Voucher’, ‘App\Models\Taxon’, ‘App\Models\Location’.

Data model images

Most figures for explaining the data model were generated using Laravel ER Diagram Generator, which allows to show all the methods implemented in each Class or Model and not only the table direct links:

To generate these figures a custom php artisan command was generated. These command is defined in file app/Console/Commands/GenerateOdbErds.php.

To update the figures follow the following steps:

• Figures are configure in the config/erd-generator-odb.php file. There are many additional options for customizing the figures by changing or adding graphviz variables to the config/erd-generator-base.php file.
• The custom command is php artisan odb:erd {$model}, where model is the key of the arrays in config/erd-generator-odb.php, or the word “all”, to regenerate all doc figures.

cd opendatabio
make ssh
php artisan odb:erd all

• Figures will be saved in storage/app/public/dev-imgs
• Copy the new images to the documentation site. They need to be placed within contents/{lang}/concepts/{subfolder} for all languages and in the respective sub-folders.

6 - Tutorials

6.1 - Getting data with OpenDataBio-R

Set up the connection

1. Set up the connection to the OpenDataBio server using the odb_config() function. The most important parameters for this function are base_url, which should point to the API url for your OpenDataBio server, and token, which is the access token used to authenticate your user.
2. The token is only need to get data from datasets that have one of the restricted access policies. Data from datasets of public access can be extracted without the token specification.
3. Your token is avaliable in your profile in the web interface

library(opendatabio)
base_url="https://opendb.inpa.gov.br/api"
token ="GZ1iXcmRvIFQ"
cfg = odb_config(base_url=base_url, token = token)

More advanced configuration involves setting a specific API version, a custom User Agent, or other HTTP headers, but this is not covered here.

Test your connection

The function odb_test() may be used to check if the connection was successful, and whether your user was correctly identified:

odb_test(cfg)
#will output
Host: https://opendb.inpa.gov.br/api/v0
Versions: server 0.9.1-alpha1 api v0
$message
[1] "Success!"

$user
[1] "admin@example.org"

As an alternative, you can specify these parameters as systems variables. Before starting R, set this up on your shell (or add this to the end of your .bashrc file):

export ODB_TOKEN="YourToken"
export ODB_BASE_URL="https://opendb.inpa.gov.br/api"
export ODB_API_VERSION="v0"

GET Data

See the GET API Quick Reference for a complete list of endpoints and request parameters. Also see the generic parameters, especially save_job which is important for downloading large datasets.

For publicly accessible data the token is optional. Below are some examples. Follow a similar reasoning to use the other endpoints. See the R package help for all available odb_get_{endpoint} functions.

Getting Taxon names

See GET API Taxon Endpoint request parameters and a list of response fields.

base_url="https://opendb.inpa.gov.br/api"
cfg = odb_config(base_url=base_url)
#get id for a taxon
mag.id = odb_get_taxons(params=list(name='Magnoliidae',fields='id,name'),odb_cfg = cfg)
#use this id to get all descendants of this taxon
odb_taxons = odb_get_taxons(params=list(root=mag.id$id,fields='id,scientificName,taxonRank,parent_id,parentName'),odb_cfg = cfg)
head(odb_taxons)

If the server used the seed data provided and the default language is portuguese, the result will be:

  id scientificName taxonRank parent_id  parentName
1 25    Magnoliidae     Clado        20 Angiosperms
2 43     Canellales     Ordem        25 Magnoliidae
3 62       Laurales     Ordem        25 Magnoliidae
4 65    Magnoliales     Ordem        25 Magnoliidae
5 74      Piperales     Ordem        25 Magnoliidae
6 93  Chloranthales     Ordem        25 Magnoliidae

Getting Locations

See GET API Location Endpoint request parameters and a list of response fields. See also the POST Locations-Validation Endpoint if you have latitude and longitude and wants to validade the geometries and find where the point falls.

Get some fields listing all Conservation Units (adm_level==99) registered in the server:

base_url="https://opendb.inpa.gov.br/api"
cfg = odb_config(base_url=base_url)
odblocais = odb_get_locations(params = list(fields='id,name,parent_id,parentName',adm_level=99),odb_cfg = cfg)
head(odblocais)

If the server used the seed data provided and the default language is portuguese, the result will be:

id                                                           name
1 5628                              Estação Ecológica Mico-Leão-Preto
2 5698          Área de Relevante Interesse Ecológico Ilha do Ameixal
3 5700 Área de Relevante Interesse Ecológico da Mata de Santa Genebra
4 5703     Área de Relevante Interesse Ecológico Buriti de Vassununga
5 5707                                Reserva Extrativista do Mandira
6 5728                                   Floresta Nacional de Ipanema
parent_id parentName
1         6  São Paulo
2         6  São Paulo
3         6  São Paulo
4         6  São Paulo
5         6  São Paulo
6         6  São Paulo

Locations as spatial objects in R

To obtain a spatial object in R, use the sf package. The example below plots a plot and its subplots and also exports the locations as both, kml and shapefile.

library(sf)
library(opendatabio)

#download all plot locations
cfg <- odb_config(base_url = "https://opendb.inpa.gov.br/api")

#get a  large main plot
parcela = odb_get_locations(params = list(fields='all',name='Parcela 25ha'), odb_cfg = cfg)
parcela$type = 'main plot'

#get subplots
subplots = odb_get_locations(params = list(fields='all',location_root=parcela$id), odb_cfg = cfg)
subplots = subplots[subplots$adm_level==100 & subplots$id!=parcela$id,]
subplots$type = 'sub plot'

#convert footprintWKT to sf geometries
geoms <- st_as_sfc(parcela$footprintWKT, crs = 4326)
parcela_sf <- st_sf(parcela, geometry = geoms)

geoms <- st_as_sfc(subplots$footprintWKT, crs = 4326)
subplots_sf <- st_sf(subplots, geometry = geoms)

#print a figure
png("plots_with_subplots.png", width = 15, height = 15,units='cm',res=300)
  par(mar=c(2,2,3,2))
  plot(st_geometry(subplots_sf),border='green',main = parcela$locationName)
  plot(st_geometry(parcela_sf),border='red',add=T)
  labs = gsub("Quadrat ","",subplots_sf$locationName)
  text(
   st_coordinates(st_centroid(subplots_sf)),
   labels = labs,
   cex = 0.2, col = "blue"
  )
dev.off()


#save as kml
locais = rbind(parcela_sf,subplots_sf)
locais$name <- locais$locationName
cols_to_include <- setdiff(names(locais), c("footprintWKT",'locationName'))
locais_kml <- locais[, c("name", cols_to_include[cols_to_include != "name"])]
st_write(locais_kml, "plots_and_subplots.kml", layer=parcela$locationName, driver = "KML", delete_dsn = TRUE)
#save as shapefile
st_write(locais_kml, "plots_and_subplots.shp", layer=parcela$locationName, delete_layer = TRUE)

Figure generated:

Validating point geometries

See the POST Locations-Validation Endpoint.

#conect to database
library(opendatabio)
base_url="http://localhost/opendatabio/api"
token ="your token is mandatory in this case"
cfg = odb_config(base_url=base_url, token = token)
odb_test(cfg)

#fake data
dados = data.frame(
  latitude = sample(seq(-2,2,by=0.00001),10),
  longitude = sample(seq(-60,-59,by=0.00001),10)
)

#submit job for validation
jb = odb_validate_locations(dados,odb_cfg = cfg)

#monitor job execution
odb_get_jobs(params=list(id=jb$id),odb_cfg = cfg)

#get results
dadosValidados = odb_get_jobs(params=list(id=jb$id,get_file=T),odb_cfg = cfg)

head(dados)
  latitude longitude
1  0.12975 -59.65745
2  1.77469 -59.77757
3 -0.89154 -59.80179
4 -1.25632 -59.87084
5  0.77085 -59.22740
6 -0.74237 -59.64591

head(dadosValidados)
  latitude longitude withinLocationName withinLocationParent withinLocationCountry withinLocationHigherGeography  withinLocationType
1  0.12975 -59.65745  Trombetas/Mapuera               Brasil                Brazil    Brasil > Trombetas/Mapuera Território Indígena
2  0.12975 -59.65745     Bioma Amazônia               Brasil                Brazil       Brasil > Bioma Amazônia           Ambiental
3  0.12975 -59.65745           Amazonia                World                                            Amazonia           Ambiental
4  0.12975 -59.65745            Urucará             Amazonas                Brazil   Brasil > Amazonas > Urucará           Município
5  1.77469 -59.77757            Jacamim              Roraima                Brazil    Brasil > Roraima > Jacamim Território Indígena
6  1.77469 -59.77757     Bioma Amazônia               Brasil                Brazil       Brasil > Bioma Amazônia           Ambiental
  withinLocationID withinLocationTypeAdmLevel searchObs
1             6393                         98        NA
2             6583                         97        NA
3            16597                         97        NA
4             1570                          8        NA
5             6121                         98        NA
6             6583                         97        NA

Getting Individual Data

See GET API Individual Endpoint for the full list of search parameters and response fields.