Documentation

• 1: Overview
• 2: Getting Started
• 2.1: First time users
• 2.2: Apache Installation
• 2.3: Docker Installation
• 2.4: Nginx Installation
• 2.5: Customize Installation
• 2.6: Upgrade OpenDataBio
• 3: API services
• 3.1: Quick reference
• 3.2: GET data
• 3.3: Post data
• 3.4: Put data
• 4: User guides
• 4.1: Discover and map data
• 4.2: Data import workflow
• 4.3: Organize and publish datasets
• 4.4: Import phylogenies into the backbone
• 4.5: Curate shared libraries
• 4.6: Vouchers, labels, and requests
• 4.7: Tutorials
• 5: Concepts
• 5.1: Core Objects
• 5.2: Trait Objects
• 5.3: Data Access Objects
• 5.4: Auxiliary Objects
• 6: Contribution Guidelines
• 7: Tutorials
• 7.1: Getting data with OpenDataBio-R
• 7.2: Import data with R
• 7.2.1: Import Locations
• 7.2.2: Import BibReferences
• 7.2.3: Import Vernacular
• 7.2.4: Import Media
• 7.2.5: Import Taxons
• 7.2.6: Import Persons
• 7.2.7: Import Traits
• 7.2.8: Import Individuals & Vouchers
• 7.2.9: Import Measurements

1 - Overview

OpenDataBio is an open-source, web-based platform that helps researchers and organizations collect, relate, curate, publish and serve biodiversity data. It supports the connected data types used in ecological and taxonomic research and provides documented, versioned data for discovery, download and programmatic reuse.

What you can do

Discover, filter, and map data

Search connected biodiversity records in lists, Data Explorer, and Map Explorer; then export them through the interface, API, or R. Results always respect the current user’s permissions. See Discover and map data.

Register connected biodiversity data

Manage spatial Locations, published and unpublished Taxons, observed Individuals, deposited Vouchers, Media, custom Traits, and Measurements. Shared People, References, Locations, Taxons, and Traits reduce duplication across projects and require coordinated curation.

Organize access and collaboration

Datasets control record access and group administrators, collaborators, and viewers. Projects group Datasets and users. Managed Biocollections additionally control editing of deposited Vouchers and Individuals and process deposits and material loans.

Publish citable versions

Create fixed Dataset versions with UUID, authorship, license, citation, metadata, and persistent archives. A version is a snapshot; the managed Dataset may continue changing. See Datasets and publication.

Work with taxonomy and identifications

Validate Taxons against external nomenclatural sources, preserve Individual identification history, and review proposed changes. Experimental phylogeny imports are currently intended only as candidates for incorporation into the taxonomic backbone, subject to administrative review.

Automate imports and exports

The REST API and OpenDataBio-R support reproducible workflows. Long operations run as UserJobs with progress, logs, and per-row results. Follow the staged Data import workflow.

For installation administrators

Administrators install and upgrade the application, configure workers and services, promote users, maintain shared libraries, manage backups including published archives, and review global operations. Installation steps belong in Getting started; existing installations should follow the upgrade notes.

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 on 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. The repository now includes a docker/prod profile and docker-compose.prod.yml so Docker can also be used for production deployments (with server-specific tuning and secrets management).

If you just want to test OpenDataBio locally, follow the Docker Installation.

Next steps

1. Apache Installation
2. Nginx Installation
3. Docker Installation
4. Upgrade OpenDataBio

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.

Choose your starting point

• To browse public data, no account is required.
• A registered user can access content released to registered users but cannot contribute records.
• A full user can create and import data and participate in Datasets, Projects, and Biocollections.
• Installation super administrators manage global configuration and access.

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.
• A super administrator can promote registered users. A full user explicitly authorized to manage access may also promote registered users to full users and reverse that promotion. Delegated managers cannot alter super administrators, other access managers, or delegate their own permission.

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.

Follow the Data import workflow to prepare dependencies, validate coordinates, reconcile UserJob results, and preserve IDs.

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.

Before a large batch, import representative pilot rows, follow the UserJob, review row-level warnings and errors, retrieve affected IDs, GET the records, and only then proceed to dependent objects.

2.2 - Apache Installation

These instructions are for an apache-based installation. For nginx, use Nginx Installation.

Server requirements

1. The supported PHP version >= 8.2 (8.3 recommended)
2. Web server: apache for this guide. For nginx, use Nginx Installation.
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
        Alias /build /home/odbserver/opendatabio/public/build
        Alias /vendor/livewire /home/odbserver/opendatabio/public/vendor/livewire
        <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 ^/$ /

Content Security Policy (CSP) for Apache

Configure CSP at the web server layer (not in Laravel files). Apply it first in report-only mode, inspect logs, then switch to enforced mode.

For nginx standalone installs, use Nginx Installation.

Apache: where to put it

1. Enable required module:

sudo a2enmod headers
sudo systemctl restart apache2

2. Edit your active vhost file (example):

sudo nano /etc/apache2/sites-available/opendatabio.conf

3. Inside the correct <VirtualHost ...> block (HTTP and/or HTTPS), add:

Header always set Content-Security-Policy-Report-Only "
  default-src 'self';
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'self';
  object-src 'none';
  script-src 'self' 'unsafe-eval';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https://server.arcgisonline.com https://*.tile.openstreetmap.org;
  font-src 'self' data:;
  connect-src 'self';
"

4. Reload Apache:

sudo apachectl configtest
sudo systemctl reload apache2

Subpath installs (/opendatabio)

If your installation runs under a subpath (for example http://localhost/opendatabio), set in .env:

APP_URL=http://localhost/opendatabio
ASSET_URL=http://localhost/opendatabio

Then refresh generated assets and Livewire files:

php artisan livewire:publish --assets
php artisan optimize:clear
npm run build

Notes

1. https://server.arcgisonline.com and https://*.tile.openstreetmap.org are needed for map tiles.
2. unsafe-inline / unsafe-eval are temporary compatibility flags; remove after hardening templates/assets.
3. Keep Report-Only while tuning policy in production.

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.
• Make sure assets_url is correct for your deployment URL/subpath.

4. Run the installer:

cd /home/odbserver/opendatabio
php install

5. Build frontend assets after .env is configured (required when assets_url is added or changed):

npm run build

6. 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. Before running commands, review config diffs for the target version:

• Compare .env with .env.example (including assets_url)
• Check PHP settings (php.ini in CLI and FPM/Apache)
• Check Supervisor worker settings

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. Rebuild frontend assets after .env updates:

npm run build

5. Refresh caches and restart queue workers:

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

6. 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 asset/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 the required configuration to run OpenDataBio. It uses nginx, MySQL, and Supervisor for queues

Production profile

OpenDataBio now ships a production-oriented Docker profile:

• docker/prod/nginx.conf
• docker/prod/php.ini
• docker/prod/www.conf
• docker-compose.prod.yml

Run production compose with:

docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d

Key differences from dev:

1. Uses docker/prod/* nginx/php-fpm configs.
2. Removes source bind-mounts for app code.
3. Disables phpMyAdmin by default (dev-only profile).
4. Publishes nginx on port 80 (adjust if behind reverse proxy).

CSP in nginx (report-only) is included in docker/prod/nginx.conf. Keep report-only first, then enforce after validation.

Docker files

laravel-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

• After configuring .env (or whenever ASSET_URL changes), rebuild assets:

npm ci #may need this in production
npm run build

• 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. Before running commands, review config diffs for the target version:

• Compare .env with .env.example (including assets_url)
• Check PHP settings from the target profile (docker/prod/php.ini or your custom PHP config)
• Check Supervisor settings (docker/supervisord.conf or your deployment equivalent)

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. Rebuild frontend assets after .env updates:

npm run build

5. 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 asset/cache/worker refresh in production.

2.4 - Nginx Installation

These instructions are for an nginx-based installation. If you prefer Apache, use the Apache installation page.

Server requirements

1. Supported PHP version >= 8.2 (8.3 recommended).
2. Web server: nginx.
3. SQL database: MySQL or MariaDB (tested with MySQL 8.0 and MariaDB 10.6+).
4. Required PHP extensions: openssl, pdo, pdo_mysql, mbstring, tokenizer, xml, dom, gd, exif, bcmath, zip, curl, redis.
5. Redis for queues/cache.
6. Tectonic for label PDF generation.
7. Pandoc for bibliographic rendering (recommended).
8. Supervisor for background jobs.

Nginx site config

Create your site config file (example):

sudo nano /etc/nginx/sites-available/opendatabio

Use this base server block (adjust paths/domain):

server {
    listen 80;
    server_name your-domain.example;

    root /home/odbserver/opendatabio/public;
    index index.php index.html;

    charset utf-8;
    client_max_body_size 300M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_read_timeout 300;
    }

    location ~ /\. {
        deny all;
    }
}

Enable and reload:

sudo ln -s /etc/nginx/sites-available/opendatabio /etc/nginx/sites-enabled/opendatabio
sudo nginx -t
sudo systemctl reload nginx

Content Security Policy (CSP)

Edit the same nginx site file and add inside the server { ... } block:

add_header Content-Security-Policy-Report-Only "
  default-src 'self';
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'self';
  object-src 'none';
  script-src 'self' 'unsafe-eval';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https://server.arcgisonline.com https://*.tile.openstreetmap.org;
  font-src 'self' data:;
  connect-src 'self';
" always;

Then reload:

sudo nginx -t
sudo systemctl reload nginx

Notes:

1. Start with Report-Only, then move to enforced CSP after validating logs.
2. https://server.arcgisonline.com and https://*.tile.openstreetmap.org are required for map tiles.

Subpath installs (/opendatabio)

If your installation runs under a subpath (for example http://localhost/opendatabio), set in .env:

APP_URL=http://localhost/opendatabio
ASSET_URL=http://localhost/opendatabio

Then refresh generated assets and Livewire files:

php artisan livewire:publish --assets
php artisan optimize:clear
npm run build

Shared application setup

To avoid repeating the same instructions, use these sections from Apache installation (they also apply to nginx deployments):

1. PHP settings (php.ini) in Apache Installation
2. Configure supervisord in Apache Installation
3. Folder permissions in Apache Installation
4. Install OpenDataBio in Apache Installation
5. Post-install configs in Apache Installation

2.5 - 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.

2.6 - Upgrade OpenDataBio

Use this page for the common deployment sequence. Before upgrading, read UPGRADES_NOTES.md from the target version of OpenDataBio. It is the authoritative source for version-specific prerequisites, storage permissions, migrations, backfills and repair commands; those instructions are intentionally not duplicated here.

Before you start

1. Read the target version’s UPGRADES_NOTES.md and release notes. Record every required preflight check and post-migration command before starting.
2. Back up at least:
   • Database dump
   • .env
   • the complete storage/app tree, including media, generated exports and persisted dataset-version archives
3. Compare current config files against target-version templates/settings:
   • .env against .env.example (including assets_url)
   • Supervisor worker config (/etc/supervisor/conf.d/opendatabio-worker.conf or container equivalent)
   • PHP config (php.ini for CLI and FPM/Apache)
4. Plan a maintenance window for production.

Upgrade (Apache or nginx installation)

1. Put application in maintenance mode:

cd /home/odbserver/opendatabio
php artisan down

2. Update source code:

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

3. Install dependencies and run migrations:

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

4. Run the post-migration commands listed in the target version’s UPGRADES_NOTES.md, in the documented order. Some commands submit background UserJobs; keep the application in maintenance mode and monitor them until completion when the notes require it.
5. Rebuild frontend assets after .env changes (required when ASSET_URL changes):

npm run build

6. Refresh caches and restart workers:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart
systemctl restart supervisor.service
# Restart the web server and PHP-FPM as appropriate for your installation.

7. Verify the application, queue workers, logs and the operations named in the upgrade notes, then bring the application back online:

php artisan up

Upgrade (Docker installation)

1. Update source code:

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

2. Rebuild and restart containers:

make stop
make build
make start

3. Install dependencies and run migrations:

make composer-install
make migrate

4. Run the target version’s UPGRADES_NOTES.md post-migration commands inside the application container, in the documented order, and monitor any UserJobs they submit.
5. Rebuild frontend assets after .env changes (required when ASSET_URL changes):

npm run build

6. Refresh caches and restart workers:

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

Environment variables

Compare .env with the target version’s .env.example before building assets or caching configuration. Follow UPGRADES_NOTES.md for variables whose value or meaning changed; in production, verify APP_FORCE_HTTPS and ASSET_URL.

Rollback strategy

If something fails after migration:

1. Keep maintenance mode on.
2. Restore the database, .env, and the matching storage/app backup. Database rows and persisted dataset-version archives must be restored as one snapshot.
3. Checkout the previous known-good tag.
4. Rebuild dependencies/containers and validate logs before php artisan up.

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

Selecting response fields

The fields parameter controls the returned columns:

• simple is the default profile and contains the fields most useful for common workflows;
• all adds detailed, relational, technical, or compatibility fields;
• a comma-separated list, such as fields=id,uuid,scientificName, returns only the requested fields.

Each endpoint below includes a table showing membership in simple and all and the meaning of every field. Definitions come from the application schema. Endpoint-specific meanings take precedence over shared definitions—for example, x and y mean different things for Locations and Individuals. Fields marked as Darwin Core follow the exchange vocabulary; fields marked as local are OpenDataBio extensions.

GET endpoints

Quick links

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

/ (GET)

Tests your access/token.

No parameters for this endpoint.

bibreferences (GET)

Bibliographic references (GET lists, POST creates).

Fields returned

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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 versions (GET lists, POST creates via import job).

Fields returned

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 853443,
            "basisOfRecord": "MeasurementsOrFact",
            "measured_type": "App\\Models\\Voucher",
            "measured_id": 1519,
            "measurementType": "HasSilica",
            "measurementValue": "Sim",
            "measurementUnit": null,
            "measurementDeterminedDate": "2014-09-24",
            "measurementDeterminedBy": "Equipe FITO",
            "measurementRemarks": null,
            "resourceRelationship": null,
            "resourceRelationshipID": "3304.8846.Equipe-FITO.PDBFF.PDBFF005425",
            "relationshipOfResource": "measurement of",
            "scientificName": "Pouteria fimbriata",
            "family": "Sapotaceae",
            "datasetName": "SILICOTECA",
            "measurementMethod": "Name: Has sílica-gel sample for DNA extraction | Definition:Has a tissue preserved in sílica-gel for DNA extractions. | Categories: CategoryName: Yes | Definition:Has an associated sample in sílica-gel.",
            "sourceCitation": null,
            "measurementLocationId": 29639,
            "measurementParentId": null,
            "decimalLatitude": -2.36495453,
            "decimalLongitude": -59.97365135
        }
    ]
}

media (GET)

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

Fields returned

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

Response example

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": []
}

vouchers (GET)

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

Fields returned

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

Response example

{
    "message": "Unauthenticated",
    "0": 401
}

activities (GET)

Lists activity log entries.

Fields returned

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

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
            }
        }
    ]
}

brahms (GET)

BRAHMS/INPA formatted individual export (GET lists, queued export with save_job).

Fields returned

The simple profile is the default response; all adds detailed, technical, or compatibility fields. Use the fields parameter to request an explicit list.

identification-histories (GET)

Identification history records (GET lists, POST creates manual history rows).