Post data
How to import data to OpenDataBio using the API
11 minute read
Importing data
- The [OpenDataBio-R package](https://gitlab.com/opendatabio/opendatabio-r) is a **client** for this API and lets you import, download and update data from R objects.
- [Examples of importing from R are here](/en/docs/tutorials/02-post-data-r-vignette);
- Data can be imported via the web interface using spreadsheets, where the column names are the POST parameters listed on this page
- An authentication token is required for all POST requests
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).
| Parameter | Required | Description | Example |
|---|---|---|---|
bibtex | No | BibTeX formatted reference string. (Provide doi or bibtex.) | @article{mykey,...} |
doi | No | DOI number or URL. (Provide doi or bibtex.) | 10.1234/abcd.2020.1 |
biocollections (POST)
Biocollections (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
acronym | Yes | Biocollection acronym. | INPA |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
individuals (POST)
Individuals (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
altitude | No | Elevation in meters. | 75 |
angle | No | Azimuth from reference point, in degrees. | 45 |
biocollection | No | Biocollection id, name or acronym. | INPA |
biocollection_number | No | Catalogue number/code inside the biocollection. | 12345 |
biocollection_type | No | Nomenclatural type code or name. | Holotype or 2 |
collector | Yes | Collector(s) id, abbreviation, name or email. Use | or ; to separate multiple people; first is main collector. | J.Silva|M.Costa |
dataset | Yes | Dataset id or acronym. | 3 or FOREST1 |
date | Yes | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. (At least the year must be provided.) | 2024-05-20 or {\"year\":1888,\"month\":5} |
distance | No | Distance from reference point in meters. | 12.5 |
identification_based_on_biocollection | No | Biocollection name/id used as reference for identification. | INPA |
identification_based_on_biocollection_number | No | CatalogNumber in the reference biocollection | 8765 |
identification_date | No | Identification date (full or incomplete). | 2023-06-NA |
identification_individual | No | ID/organismID of another individual that provides the taxonomic identification for the individual’s record | 3245 or REC-123 |
identification_notes | No | Notes for the identification. | Checked with microscope |
identifier | No | Person(s) responsible for identification; accept id, abbreviation, name or email; separate multiple with | or ;. | Costa, A.|Lima, B. or 1|2|3 or Adolpho Ducke|José Ramos|Paulo Apóstolo Costa Lima Assunção |
latitude | No | Latitude in decimal degrees (negative for south). (Required when location is not provided.) | -3.101 |
location | No | Location id or name. (Required when latitude/longitude are not provided.) | Parcela 25ha or 55 |
location_date_time | No | Date or date+time for the occurrence/location event. (Required when adding multiple locations or when different from individual date.) | 2023-08-14 12:30:00 |
location_notes | No | Notes for the occurrence/location entry. | Near trail marker 10 |
longitude | No | Longitude in decimal degrees (negative for west). (Required when location is not provided.) | -60.12 |
modifier | No | Identification modifier code/name (s.s.=1, s.l.=2, cf.=3, aff.=4, vel aff.=5). | 3 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
tag | Yes | Individual tag/number/code. | A-1234 |
taxon | No | Taxon id or canonical full name list. | Licaria cannela or 456,789 |
x | No | X coordinate for plots or individual position. | 12.3 |
y | No | Y coordinate for plots or individual position. | 8.7 |
individual-locations (POST)
Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts).
| Parameter | Required | Description | Example |
|---|---|---|---|
altitude | No | Elevation in meters. | 75 |
angle | No | Azimuth from reference point, in degrees. | 45 |
distance | No | Distance from reference point in meters. | 12.5 |
individual | Yes | Individual id, uuid or organismID (fullname). | 4521 or 2ff0e884-3d33 |
latitude | No | Latitude in decimal degrees (negative for south). (Required when location is not provided.) | -3.101 |
location | No | Location id or name. (Required when latitude/longitude are not provided.) | Parcela 25ha or 55 |
location_date_time | Yes | Date or date+time for the occurrence/location event. | 2023-08-14 12:30:00 |
location_notes | No | Notes for the occurrence/location entry. | Near trail marker 10 |
longitude | No | Longitude in decimal degrees (negative for west). (Required when location is not provided.) | -60.12 |
x | No | X coordinate for plots or individual position. | 12.3 |
y | No | Y coordinate for plots or individual position. | 8.7 |
locations (POST)
Locations (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
adm_level | Yes | Location administrative level code (e.g. 100=plot, 10=country). | 100 |
altitude | No | Elevation in meters. | 75 |
azimuth | No | Azimuth (degrees) used to build plot/transect geometry when location is a POINT. | 90 |
datum | No | Spatial datum/projection string. | EPSG:4326-WGS 84 |
geojson | No | Single GeoJSON Feature with geometry and at least name + adm_level properties. | {\"type\":\"Feature\",\"properties\":{\"name\":\"Plot A\",\"adm_level\":100},\"geometry\":{...}} |
geom | No | WKT geometry (POINT, LINESTRING, POLYGON, MULTIPOLYGON). (Provide geom or lat+long.) | POLYGON((-60 -3,-60.1 -3,-60.1 -3.1,-60 -3.1,-60 -3)) |
ismarine | No | Flag to allow marine/offshore locations outside country polygons. | 1 |
lat | No | Latitude in decimal degrees (negative for south). (Provide geom or lat+long.) | -3.101 |
long | No | Longitude in decimal degrees (negative for west). (Provide geom or lat+long.) | -60.12 |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
parent | No | Parent id/name; for traits this is another trait export_name/id to define hierarchy. | woodDensity |
startx | No | Start X coordinate for subplot relative to parent plot. | 5.5 |
starty | No | Start Y coordinate for subplot relative to parent plot. | 10.0 |
x | No | X coordinate for plots or individual position. | 12.3 |
y | No | Y coordinate for plots or individual position. | 8.7 |
locations-validation (POST)
Validates coordinates against registered locations (POST).
| Parameter | Required | Description | Example |
|---|---|---|---|
latitude | Yes | Latitude in decimal degrees (negative for south). | -3.101 |
longitude | Yes | Longitude in decimal degrees (negative for west). | -60.12 |
measurements (POST)
Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
bibreference | No | Bibreference id or bibkey. | 34 or ducke1953 |
dataset | Yes | Dataset id/name where the measurement will be stored; falls back to authenticated user default dataset if omitted. | 3 or FOREST1 |
date | Yes | Measurement date; accepts YYYY-MM-DD, YYYY-MM, YYYY, or array/year-month-day fields (date_year/date_month/date_day). | 2024-05-10 or {\"year\":2024,\"month\":5} |
duplicated | No | Integer allowing repeated measurements on the same date/object; must be higher than existing duplicates. | 2 |
link_id | No | Required for LINK trait types: id of the linked object (e.g., Taxon id). (Required when trait type is Link.) | 55 |
location | No | Location id or name. | Parcela 25ha or 55 |
notes | No | Optional free text or JSON notes stored with the measurement. | {\"method\":\"caliper\"} |
object_id | Yes | Required. Id of the measured object (Individual, Location, Taxon, Voucher, Media). Alias: measured_id. | 4521 |
object_type | Yes | Required when not provided in header. Class basename or FQCN of the measured object (Individual, Location, Taxon, Voucher, Media). Alias: measured_type. | Individual |
parent_measurement | No | When trait depends on another measurement, provide the parent measurement id for the same object and date. | 3001 |
person | Yes | Person id, abbreviation, full name or email (supports lists with | or ;). | J.Silva|M.Costa |
trait_id | Yes | Required. Trait id or export_name to be measured (also accepts trait key “trait”). | DBH or 12 |
value | No | Input varies by trait type: QUANT_INTEGER (0) = integer number; QUANT_REAL (1) = decimal number with dot separator; CATEGORICAL or ORDINAL (2/4) = single category id or translated name; CATEGORICAL_MULTIPLE (3) = list of category ids/names separated by | ; or , (or an array); TEXT (5) = free text string; COLOR (6) = hex color like #A1B2C3 or #ABC; LINK (7) = send link_id pointing to the linked object (value may be blank or a numeric qualifier); SPECTRAL (8) = semicolon-separated numeric series whose length equals trait value_length; GENEBANK (9) = GenBank accession string (validated against NCBI). (Required unless trait type is Link.) | QUANT_REAL: 23.4 | CATEGORICAL: 15 or Dead | CATEGORICAL_MULTIPLE: 12;14 or Alternate;Opposite | SPECTRAL: 0.12;0.11;0.10 |
media (POST)
Media metadata (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
collector | No | Collector(s) id, abbreviation, name or email. Use | or ; to separate multiple people; first is main collector. | J.Silva|M.Costa |
dataset | No | Dataset id or acronym. | 3 or FOREST1 |
date | No | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. | 2024-05-20 or {\"year\":1888,\"month\":5} |
filename | Yes | Exact media file name inside the ZIP when importing media. | IMG_0001.jpg |
latitude | No | Latitude in decimal degrees (negative for south). | -3.101 |
license | No | Public license code for media (CC0, CC-BY, CC-BY-SA, etc.). | CC-BY-SA |
location | No | Location id or name. | Parcela 25ha or 55 |
longitude | No | Longitude in decimal degrees (negative for west). | -60.12 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
object_id | Yes | Id of object the media belongs to (Individual, Location, Taxon, Voucher). | 4521 |
object_type | Yes | The object type the media belongs to, one of Individual, Location, Taxon, Voucher, or Media. | Individual |
project | No | Project id or acronym. | PDBFF or 2 |
tags | No | Tag ids or names list for media or filters (use | or ;). | flower|leaf |
title_en | No | Media title in English. | Leaf detail |
title_pt | No | Media title in Portuguese. | Detalhe da folha |
persons (POST)
People (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
abbreviation | No | Standard abbreviation for a person or biocollection. | Silva, J.B, Pilco, M.V. |
biocollection | No | Biocollection id, name or acronym. | INPA |
email | No | Email address. | user@example.org |
full_name | Yes | Person full name. | Joao Silva |
institution | No | Institution associated with a person. | INPA |
taxons (POST)
Taxonomic names (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
author | No | Taxon author string for unpublished names. | Smith & Jones |
author_id | No | Person id/name/email for the author of an unpublished taxon. (Required for unpublished names (or use person).) | 25 or Pilco, M.V. |
bibreference | No | Bibreference id or bibkey. | 34 or ducke1953 |
gbif | No | GBIF nubKey for a taxon. | 28792 |
ipni | No | IPNI id for a taxon. | 123456-1 |
level | No | Taxon rank code or string. | 210 or species |
mobot | No | Tropicos id for a taxon. | 12345678 |
mycobank | No | MycoBank id for a taxon. | MB123456 |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
parent | No | Parent id/name; for traits this is another trait export_name/id to define hierarchy. (Required for unpublished names.) | woodDensity |
person | No | Person id, abbreviation, full name or email (supports lists with | or ;). (Required for unpublished names (or use author_id).) | J.Silva|M.Costa |
valid | No | When 1, return only valid taxon names. | 1 |
zoobank | No | ZooBank id for a taxon. | urn:lsid:zoobank.org:act:12345678 |
traits (POST)
Trait definitions (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
bibreference | No | Bibreference id or bibkey. | 34 or ducke1953 |
categories | No | Trait categories JSON list with lang/rank/name/description. (Required for categorical and ordinal traits.) | [{\"lang\":\"en\",\"rank\":1,\"name\":\"small\"}] |
description | Yes | Translatable description text. Accepts a plain string or a JSON map of language codes to descriptions. | {"en":"Tree height at breast height","pt-br":"Altura da árvore à altura do peito"} |
export_name | Yes | Unique export name for trait. | treeDbh,plantHeight |
link_type | No | Class name for Link trait target (e.g. Taxon). (Required for Link traits.) | Taxon |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
objects | Yes | Trait target objects (comma separated). | Individual,Voucher |
parent | No | Parent trait id or export_name; when set, measurements of this trait must also include a measurement for the parent trait. | woodDensity |
range_max | No | Maximum allowed numeric value for quantitative traits. | 999.9 |
range_min | No | Minimum allowed numeric value for quantitative traits. | 0.01 |
tags | No | Tag ids or names list for media or filters (use | or ;). | flower|leaf |
type | Yes | Generic type parameter (trait type code or vernacular type such as use/generic/etimology). | use or 10 |
unit | No | (Required for quantitative traits.) | — |
value_length | No | Number of values for spectral trait types. (Required for spectral traits.) | 1024 |
wavenumber_max | No | Maximum wavenumber for spectral traits. (Required for spectral traits.) | 25000 |
wavenumber_min | No | Minimum wavenumber for spectral traits. (Required for spectral traits.) | 4000 |
vernaculars (POST)
Vernacular names (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
citations | No | List of citations (text + bibreference) for vernaculars. | [{\"citation\":\"Silva 2020\",\"bibreference\":12}] |
individuals | No | List of individual ids/fullnames for vernacular links. | 12|23|45 |
language | Yes | Language id/code/name | en or 1 or english or portuguese |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
parent | No | Parent id/name; for traits this is another trait export_name/id to define hierarchy. | woodDensity |
taxons | No | List of taxon ids/names (vernacular links). | Euterpe edulis|Euterpe precatoria |
type | No | Generic type parameter (trait type code or vernacular type such as use/generic/etimology). | use or 10 |
vouchers (POST)
Voucher specimens (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
biocollection | Yes | Biocollection id, name or acronym. | INPA |
biocollection_number | No | Catalogue number/code inside the biocollection. | 12345 |
biocollection_type | No | Nomenclatural type code or name. | Holotype or 2 |
collector | No | Collector(s) id, abbreviation, name or email. Use | or ; to separate multiple people; first is main collector. | J.Silva|M.Costa |
dataset | No | Dataset id or acronym. | 3 or FOREST1 |
date | No | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. | 2024-05-20 or {\"year\":1888,\"month\":5} |
individual | Yes | Individual id, uuid or organismID (fullname). | 4521 or 2ff0e884-3d33 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
number | No | Collector number/code (voucher/individual tag when different from individual). | 1234A |
datasets (POST)
Datasets and published dataset files (GET lists, POST creates via import job).
| Parameter | Required | Description | Example |
|---|---|---|---|
description | No | Translatable description text. Accepts a plain string or a JSON map of language codes to descriptions. (Required when privacy is 2 or 3.) | {"en":"Tree height at breast height","pt-br":"Altura da árvore à altura do peito"} |
license | No | Public license code for media (CC0, CC-BY, CC-BY-SA, etc.). (Required when privacy is 2 or 3.) | CC-BY-SA |
name | Yes | Short name or nickname for the dataset - make informative, shorter than title. | Morphometrics-Aniba |
privacy | Yes | (Accepted values: 0 (auth), 1 (project), 2 (registered), 3 (public).) | — |
project_id | No | (Required when privacy is 1 (project).) | — |
title | No | (Required when privacy is 2 or 3.) | — |