API services

• 1: Quick reference
• 2: GET data
• 3: POST data
• 4: Update Data - PUT

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

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

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

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

1 - Quick reference

GET DATA (downloads)

Shared get-parameters

All endpoints share these GET parameters:

• id return only the specified resource. May be number or a comma delimited list, such as api/v0/locations?id=1,50,124
• limit: the number of items that should be returned (must be greater than 0). Example: api/v0/taxons?limit=10
• offset: the initial record to extract, to be used with limit when trying to download a large amount of data. Example: api/v0/taxons?offset=10000&limit=10000 returns 10K records starting from the 10K position of the current query.
• fields: the field or fields that should be returned. Each endpoint has its own fields but there are two special words, simple (default) and all, which return different collection of fields. fields=all may return sub-objects for each object. fields ='raw' will return the raw table, speeding up the search, although values may be more difficult to understand. Example: api/v0/taxons?fields=id,scientificName,valid
• save_job: for large data retrieval, if you add save_job=1 to the params list a job will be created for your search, and the data can then be obtained using the userjobs api.

Endpoint parameters

POST DATA (imports)

PUT DATA (updates)

Nomenclature types

Taxon Level (Rank)

2 - GET data

Shared GET parameters

All endpoints share these GET parameters:

• id return only the specified resource. May be number or a comma delimited list, such as api/v0/locations?id=1,50,124
• limit: the number of items that should be returned (must be greater than 0). Example: api/v0/taxons?limit=10
• offset: the initial record to extract, to be used with limit when trying to download a large amount of data. Example: api/v0/taxons?offset=10000&limit=10000 returns 10K records starting from the 10K position of the current query.
• fields: the field or fields that should be returned. Each endpoint has its own fields but there are two special words, simple (default) and all, which return different collection of fields. fields=all may return sub-objects for each object. fields ='raw' will return the raw table, speeding up the search, although values may be more difficult to understand. Example: api/v0/taxons?fields=id,scientificName,valid
• save_job: for large data retrieval, if you add save_job=1 to the params list a job will be created for your search, and the data can then be obtained using the userjobs api.

BibReferences Endpoint

The bibreferences endpoint interact with the bibreference table. Their basic usage is getting the registered Bibliographic References.

GET request-parameters

• id=list return only references having the id or ids provided (ex id=1,2,3,10)
• bibkey=list return only references having the bibkey or bibkeys (ex bibkey=ducke1953,mayr1992)
• taxon=list of ids return only references linked to the taxon informed.
• limit and offset limit query. see Common parameters.

Response fields

• id- the id of the BibReference in the bibreferences table (a local database id)
• bibkey - the bibkey used to search and use of the reference in the web system
• year - the publication year
• author - the publication authors
• title - the publication title
• doi - the publication DOI if present
• url - an external url for the publication if present
• bibtex - the reference citation record in BibTex format

Biocollections Endpoint

The biocollections endpoint interact with the biocollections table. Their basic usage is getting the list of the Biological Collections registered in the database. Using for getting biocollection_id or validating your codes for importing data with the Vouchers or Individuals endpoints.

GET request-parameters

• id=list return only ‘biocollections’ having the id or ids provided (ex id=1,2,3,10)
• acronym return only ‘biocollections’ having the acronym or acronym provided (ex acronym=INPA,SP,NY)

Response fields

• id - the id of the repository or museum in the biocollections table (a local database id)
• name - the name of the repository or museum
• acronym - the repository or museum acronym
• irn - only for Herbaria, the number of the herbarium in the Index Herbariorum

Datasets Endpoint

The datasets endpoint interacts with the Datasets table and with static versions of Datasets. Useful for getting dataset_ids to import measurements, individuals, vouchers and media. You can also download files of static versions of the data, if any were generated by dataset administrators. This allows access to data from datasets in a faster way. Access to the data will depend on whether the version has a public license, or whether the user is a contributor, administrator or viewer of the dataset.

GET request-parameters

• id=list return only datasets having the id or ids provided (ex id=1,2,3,10)
• list_versions = boolean returns the list of files and versions for one or more id datasets (eg id='1,2,3,4',list_versions=1)
• file_name = string returns the data of a single file indicated by this parameter, as indicated in the list of versions returned (eg id='1',file_name='2_Organisms.csv')

Response fields

With list_versions=1

• dataset_id - the id of the dataset in the dataset table (a local database id)
• dataset - the name of the dataset
• version - the name of the static version of the dataset
• license - the CreativeCommons license of the data version
• access - indicating if it is OpenAccess or if the user has access
• get_params - how to inform the params argument in the odb_get_datasets() function of the R package to get the data in files

With file_name

• Returns data from the given file

Just id or nothing

• id - the id of the Dataset in the datasets table (a local database id)
• name - the name of the dataset
• privacyLevel - the access level for the dataset
• contactEmail - the dataset administrator email
• description - a description of the dataset
• policy - the data policy if specified
• measurements_count - the number of measurements in the dataset
• taggedWidth - the list of tags applied to the dataset

Individuals Endpoint

The individuals endpoints interact with the Individual table. Their basic usage is getting a list of individuals.

GET request-parameters

• id=number or list - return individuals that have id or ids ex: id=2345,345
• location=mixed - return by location id or name or ids or names ex: location=24,25,26 location=Parcela 25ha of the locations where the individuals
• location_root - same as location but return also from the descendants of the locations informed
• taxon=mixed - the id or ids, or canonicalName taxon names (fullnames) ex: taxon=Aniba,Ocotea guianensis,Licaria cannela tenuicarpa or taxon=456,789,3,4
• taxon_root - same as taxon but return also all the individuals identified as any of the descendants of the taxons informed
• project=mixed - the id or ids or names of the project, ex: project=3 or project=OpenDataBio
• tag=list - one or more individual tag number/code, ex: tag=individuala1,2345,2345A
• dataset=mixed - the id or ids or names of the datasets, return individuals having measurements in the datasets informed
• limit and offset are SQL statements to limit the amount of data when trying to download a large number of individuals, as the request may fail due to memory constraints. See Common parameters.

Response fields

• id - the ODB id of the Individual in the individuals table (a local database id)
• basisOfRecord DWC - will be always ‘organism’ [dwc organism](DWC
• organismID DWC - a local unique combination of record info, composed of recordNumber,recordedByMain,locationName
• recordedBy DWC - pipe “|” separated list of registered Persons abbreviations
• recordedByMain - the first person in recordedBy, the main collectors
• recordNumber DWC - an identifier for the individual, may be the code in a tree aluminum tag, a bird band code, a collector number
• recordedDate DWC - the record date
• scientificName DWC - the current taxonomic identification of the individual (no authors) or “unidentified”
• scientificNameAuthorship DWC - the taxon authorship. For taxonomicStatus unpublished: will be a ODB registered Person name
• family DWC
• genus DWC
• identificationQualifier DWC - identification name modifiers cf. aff. s.l., etc.
• identifiedBy DWC - the Person identifying the scientificName of this record
• dateIdentified DWC - when the identification was made (may be incomplete, with 00 in the month and or day position)
• identificationRemarks DWC - any notes associated with the identification
• locationName - the location name (if plot the plot name, if point the point name, …)
• locationParentName - the immediate parent locationName, to facilitate use when location is subplot
• higherGeography DWC - the parent LocationName ‘|’ separated (e.g. Brasil | Amazonas | Rio Preto da Eva | Fazenda Esteio | Reserva km37 | Manaus ForestGeo-PDBFF Plot | Quadrat 100x100 );
• decimalLatitude DWC - depends on the location adm_level and the individual X and Y, or Angle and Distance attributes, which are used to calculate these global coordinates for the record; if individual has multiple locations (a monitored bird), the last location is obtained with this get API
• decimalLongitude DWC - same as for decimalLatitude
• x - the individual X position in a Plot location
• y - the individual Y position in a Plot location
• gx - the individual global X position in a Parent Plot location, when location is subplot (ForestGeo standards)
• gy - the individual global Y position in a Parent Plot location, when location is subplot (ForestGeo standards)
• angle - the individual azimuth direction in relation to a POINT reference, either when adm_level is POINT or when X and Y are also provided for a Plot location this is calculated from X and Y positions
• distance - the individual distance direction in relation to a POINT reference, either when adm_level is POINT or when X and Y are also provided for a Plot location this is calculated from X and Y positions
• organismRemarks DWC - any note associated with the Individual record
• associatedMedia DWC - urls to ODB media files associated with the record
• datasetName - the name of the ODB Dataset to which the record belongs to DWC
• accessRights - the ODB Dataset access privacy setting - DWC
• bibliographicCitation - the ODB Dataset citation - DWC
• license - the ODB Dataset license - DWC

Individual-locations Endpoint

The individual-locations endpoint interact with the individual_location table. Their basic usage is getting location data for individuals, i.e. occurrence data for organisms. Designed for occurrences of organisms that move and have multiple locations, else the same info is retrieved with the Individuals endpoint.

GET request-parameters

• individual_id=number or list - return locations for individuals that have id or ids ex: id=2345,345
• location=mixed - return by location id or name or ids or names ex: location=24,25,26 location=Parcela 25ha of the locations where the individuals
• location_root - same as location but return also from the descendants of the locations informed
• taxon=mixed - the id or ids, or canonicalName taxon names (fullnames) ex: taxon=Aniba,Ocotea guianensis,Licaria cannela tenuicarpa or taxon=456,789,3,4
• taxon_root - same as taxon but return also all the the locations for individuals identified as any of the descendants of the taxons informed
• dataset=mixed - the id or ids or names of the datasets, return individuals belonging to the datasets informed
• limit and offset are SQL statements to limit the amount of data when trying to download a large number of individuals, as the request may fail due to memory constraints. See Common parameters.

Response fields

• individual_id - the ODB id of the Individual in the individuals table (a local database id)
• location_id - the ODB id of the Location in the locations table (a local database id)
• basisOfRecord - will be always ‘occurrence’ - DWC and [dwc occurrence](DWC;
• occurrenceID - the unique identifier for this record, the individual+location+date_time - DWC
• organismID - the unique identifier for the Individual DWC
• recordedDate - the occurrence date+time observation - DWC
• locationName - the location name (if plot the plot name, if point the point name, …)
• higherGeography - the parent LocationName ‘|’ separated (e.g. Brasil | Amazonas | Rio Preto da Eva | Fazenda Esteio | Reserva km37 | Manaus ForestGeo-PDBFF Plot | Quadrat 100x100 ) - DWC
• decimalLatitude - depends on the location adm_level and the individual X and Y, or Angle and Distance attributes, which are used to calculate these global coordinates for the record - DWC
• decimalLongitude - same as for decimalLatitude - DWC
• georeferenceRemarks - will contain the explanation of the type of decimalLatitude - DWC
• x - the individual X position in a Plot location
• y - the individual Y position in a Plot location
• angle - the individual azimuth direction in relation to a POINT reference, either when adm_level is POINT or when X and Y are also provided for a Plot location this is calculated from X and Y positions
• distance - the individual distance direction in relation to a POINT reference, either when adm_level is POINT or when X and Y are also provided for a Plot location this is calculated from X and Y positions
• minimumElevation - the altitude for this occurrence record if any - DWC
• occurrenceRemarks - any note associated with this record - DWC
• scientificName - the current taxonomic identification of the individual (no authors) or “unidentified” - DWC
• family - the current taxonomic family name, if apply - DWC
• datasetName - the name of the ODB Dataset to which the record belongs to - DWC
• accessRights - the ODB Dataset access privacy setting - DWC
• bibliographicCitation - the ODB Dataset citation - DWC
• license - the ODB Dataset license DWC

Measurements Endpoint

The measurements endpoint interact with the measurements table. Their basic usage is getting Data linked to Individuals, Taxons, Locations or Vouchers, regardless of datasets, so it is useful when you want particular measurements from different datasets that you have access for. If you want a full dataset, you may just use the web interface, as it prepares a complete set of the dataset measurements and their associated data tables for you.

GET request-parameters

• id=list of ids return only the measurement or measurements having the id or ids provided (ex id=1,2,3,10)
• taxon=list of ids or names return only the measurements related to the Taxons, both direct taxon measurements and indirect taxon measurements from their individuals and vouchers (ex taxon=Aniba,Licaria). Does not consider descendants taxons for this use taxon_root instead. In the example only measurements directly linked to the genus and genus level identified vouchers and individuals will be retrieved.
• taxon_root=list of ids or names similar to taxon, but get also measurements for descendants taxons of the informed query (ex taxon=Lauraceae will get measurements linked to Lauraceae and any taxon that belongs to it;
• dataset=list of ids return only the measurements belonging to the datasets informed (ex dataset=1,2) - allows to get all data from a dataset.
• trait=list of ids or export_names return only the measurements for the traits informed (ex trait=DBH,DBHpom or dataset=2?trait=DBH) - allows to get data for a particular trait
• individual=list of individual ids return only the measurements for the individual ids informed (ex individual=1000,1200)
• voucher=list of voucher ids return only the measurements for the voucher ids informed (ex voucher=345,321)
• location=list of location ids return only measurements for the locations ids informed (ex location=4,321)- does not retrieve measurements for individuals and vouchers in those locations, only measured locations, like plot soil surveys data.
• limit and offset are SQL statements to limit the amount of data when trying to download a large number of measurements, as the request may fail due to memory constraints. See Common parameters.

Response fields

• id - the Measurement ODB id in the measurements table (local database id)
• basisOfRecord DWC - will be always ‘MeasurementsOrFact’ [dwc measurementorfact](DWC
• measured_type - the measured object, one of ‘Individual’, ‘Location’, ‘Taxon’ or ‘Voucher’
• measured_id - the id of the measured object in the respective object table (individuals.id, locations.id, taxons.id, vouchers.id)
• measurementID DWC - a unique identifier for the Measurement record - combine measured resourceRelationshipID, measurementType and date
• measurementType DWC - the export_name for the ODBTrait measured
• measurementValue DWC - the value for the measurement - will depend on kind of the measurementType (i.e. ODBTrait)
• measurementUnit DWC - the unit of measurement for quantitative traits
• measurementDeterminedDate DWC - the Measurement measured date
• measurementDeterminedBy DWC - Person responsible for the measurement
• measurementRemarks DWC - text note associated with this Measurement record
• resourceRelationship DWC - the measured object (resource) - one of ’location’,’taxon’,‘organism’,‘preservedSpecimen’
• resourceRelationshipID DWC - the id of the resourceRelationship
• relationshipOfResource DWC - will always be ‘measurement of’
• scientificName DWC - the current taxonomic identification (no authors) or ‘unidentified’ if the resourceRelationship object is not ’location’
• family DWC - taxonomic family name if applies
• datasetName - the name of the ODB Dataset to which the record belongs to - DWC
• accessRights - the ODB Dataset access privacy setting - DWC
• bibliographicCitation - the ODB Dataset citation - DWC
• license - the ODB Dataset license - DWC
• measurementLocationId - the ODB id of the location associated with the measurement
• measurementParentId - the ODB id of another related measurement (the parent measurement to which the current depends upon)
• decimalLatitude DWC - a latitude em graus decimais da medição ou do objeto medido.
• decimalLongitude DWC - a longitude em graus decimais da medição ou do objeto medido.

Media Endpoint

The media endpoint interact with the media table. Their basic usage is getting the metadata associated with MediaFiles and the files URL, which can be used to download them.

GET request-parameters

• individual=number or list - return media associated with the individuals having id or ids ex: id=2345,345
• voucher=number or list - return media associated with the vouchers having id or ids ex: id=2345,345
• location=mixed - return media associated with the locations having id or name or ids or names ex: location=24,25,26 location=Parcela 25ha
• location_root - same as location but return also media associated with the descendants of the locations informed
• taxon=mixed - the id or ids, or canonicalName taxon names (fullnames) ex: taxon=Aniba,Ocotea guianensis,Licaria cannela tenuicarpa or taxon=456,789,3,4
• taxon_root - same as taxon but return also all the locations for media related to any of the descendants of the taxons informed
• dataset=mixed - the id or ids or names of the datasets, return belonging to the datasets informed
• limit and offset are SQL statements to limit the amount of data when trying to download a large number of individuals, as the request may fail due to memory constraints. See Common parameters.

Response fields

• id - the Measurement ODB id in the measurements table (local database id)
• basisOfRecord DWC - will be always ‘MachineObservation’ DWC
• model_type - the related object, one of ‘Individual’, ‘Location’, ‘Taxon’ or ‘Voucher’
• model_id - the id of the related object in the respective object table (individuals.id, locations.id, taxons.id, vouchers.id)
• resourceRelationship DWC - the related object (resource) - one of ’location’,’taxon’,‘organism’,‘preservedSpecimen’
• resourceRelationshipID DWC - the id of the resourceRelationship
• relationshipOfResource DWC - will be the dwcType
• recordedBy DWC - pipe “|” separated list of registered Persons abbreviations
• recordedDate DWC - the media file date
• scientificName DWC - the current taxonomic identification of the individual (no authors) or “unidentified”
• family DWC
• dwcType DWC - one of StillImage, MovingImage, Sound
• datasetName - the name of the ODB Dataset to which the record belongs to DWC
• accessRights - the ODB Dataset access privacy setting - DWC
• bibliographicCitation - the ODB Dataset citation - DWC
• license - the ODB Dataset license - DWC
• file_name - the file name
• file_url - the url to the file
• citation - how to cite the image.
• bibtex - the bibtex citation for the image
• uuid - a unique identifier for the image

Languages EndPoint

The languages endpoint interact with the Language table. Their basic usage is getting a list of registered Languages to import User Translations like Trait and TraitCategories names and descriptions.

Response fields

• id - the id of the language in the languages table (a local database id)
• code - the language string code;
• name - the language name;

Locations Endpoint

The locations endpoints interact with the locations table. Their basic usage is getting a list of registered countries, cities, plots, etc, or importing new locations.

GET request-parameters

• id=list return only locations having the id or ids provided (ex id=1,2,3,10)
• adm_level=number return only locations for the specified level or type:
  • 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 (Geometry: polygon, MultiPolygon);
  • 97 is the code for Environmental Layers (Geometry: polygon, multipolygon);
  • 98 is the code for Indigenous Areas (Geometry: polygon, multipolygon);
  • 99 is the code for Conservation Units (Geometry: polygon, multipolygon);
  • 100 is the code for plots and subplots (Geometry: polygon or point);
  • 101 for transects (Geometry: point or linestring)
  • 999 for any ‘POINT’ locations like GPS waypoints (Geometry: point);
• name=string return only locations whose name matches the search string. You may use asterisk as a wildcard. Example: name=Manaus or name=*Ducke* to find name that has the word Ducke;
• parent_id=list return the locations for which the direct parent is in the list (ex: parent_id=2,3)
• root=number number is the location id to search, returns the location for the specified id along with all of its descendants locations; example: find the id for Brazil and use its id as root to get all the locations belonging to Brazil;
• querytype one of “exact”, “parent” or “closest” and must be provided with lat and long:
  • when querytype=exact will find a point location that has the exact match of the lat and long;
  • when querytype=parent will find the most inclusive parent location within which the coordinates given by lat and long fall;
  • when querytype=closest will find the closest location to the coordinates given by lat and long; It will only search for closest locations having adm_level > 99, see above.
  • lat and long must be valid coordinates in decimal degrees (negative for South and West);
• fields=list specify which fields you want to get with your query (see below for field names), or use options ‘all’ or ‘simple’, to get full set and the most important columns, respectively
• project=mixed - id or name of project (may be a list) return the locations belonging to one or more Projects
• dataset=mixed - id or name of a dataset (may be a list) return the locations belonging to one or more Datasets

Notice that id, search, parent and root should probably not be combined in the same query.

Response fields

• id - the ODB id of the Location in the locations table (a local database id)
• basisOfRecord DWC - will always contain ’location’ [dwc location](DWC
• locationName - the location name (if country the country name, if state the state name, etc…)
• adm_level - the numeric value for the ODB administrative level (2 for countries, etc)
• levelName - the name of the ODB administrative level
• parent_id - the ODB id of the parent location
• parentName - the immediate parent locationName
• higherGeography DWC - the parent LocationName ‘|’ separated (e.g. Brasil | São Paulo | Cananéia);
• footprintWKT DWC - the WKT representation of the location; if adm_level==100 (plots) or adm_level==101 (transects) and they have been informed as a POINT location, the respective polygon or linestring geometries, the footprintWKT will be that generated using the location’s x and y dimensions.
• x and y - (meters) when location is a plot (100 == adm_level) its X and Y dimensions, if a transect (101 == adm_level), x may be the length and y may be a buffer dimension around the linestring.
• startx and starty - (meters) when location is a subplot (100 == adm_level with parent also adm_level==100), the X and Y start position in relation to the 0,0 coordinate of the parent plot location, which is either a Point, or the first coordinate of a Polygon geometry type;
• distance - only when querytype==closest, this value will be present, and indicates the distance, in meters, the locations is from your queried coordinates;
• locationRemarks DWC - any notes associated with this Location record
• decimalLatitude DWC - depends on the adm_level: if adm_level<=99, the latitude of the centroid; if adm_level == 999 (point), its latitude; if adm_level==100 (plot) or 101 (transect), but is a POINT geometry, the POINT latitude, else if POLYGON geometry, then the first point of the POLYGON or the LINESTRING geometry.
• decimalLongitude DWC - same as for decimalLatitude
• georeferenceRemarks DWC - will contain the explanation about decimalLatitude
• geodeticDatum -DWC the geodeticDatum informed for the geometry (ODB does not treat map projections, assumes data is always is WSG84)

Persons Endpoint

The persons endpoint interact*** with the Person table. The basic usage is getting a list of registered people (individuals and vouchers collectors, taxonomic specialists or database users).

GET request-parameters

• id=list return only persons having the id or ids provided (ex id=1,2,3,10)
• name=string - return people whose name matches the specified string. You may use asterisk as a wildcard. Ex: name=*ducke*
• abbrev = string, return people whose abbreviation matches the specified string. You may use asterisk as a wildcard.
• email=string, return people whose e-mail matches the specified string. You may use asterisk as a wildcard.
• search=string, return people whose name, abbreviation or e-mail matches the specified string. You may use asterisk as a wildcard.
• limit and offset are SQL statements to limit the amount of data when trying to download a large number of measurements, as the request may fail due to memory constraints. See Common parameters.

Response fields

• id - the id of the person in the persons table (a local database id)
• full_name - the person name;
• abbreviation - the person name (this are UNIQUE values in a OpenDataBio database)
• email - the email, if registered or person is user
• institution - the persons institution, if registered
• notes - any registered notes;
• biocollection - the name of the Biological Collection (Biocollections, etc) that the person is associated with; not included in simple)

Projects EndPoint

The projects endpoint interact with the projects table. The basic usage is getting the registered Projects.

GET request-parameters

• id=list return only projects having the id or ids provided (ex id=1,2,3,10)

Response fields

• id - the id of the Project in the projects table (a local database id)
• fullname - project name
• privacyLevel - the access level for individuals and vouchers in Project
• contactEmail - the project administrator email
• individuals_count - the number of individuals in the project
• vouchers_count - the number of vouchers in the project

Taxons Endpoint

The taxons endpoint interact with the taxons table. The basic usage is getting a list of registered taxonomic names.

GET request-parameters

• id=list return only taxons having the id or ids provided (ex id=1,2,3,10)
• name=search returns only taxons with fullname (no authors) matching the search string. You may use asterisk as a wildcard.
• root=number returns the taxon for the specified id along with all of its descendants
• level=number return only taxons for the specified taxon level.
• valid=1 return only valid names
• external=1 return the Tropicos, IPNI, MycoBank, ZOOBANK or GBIF reference numbers. You need to specify externalrefs in the field list to return them!
• project=mixed - id or name of project (may be a list) return the taxons belonging to one or more Projects
• dataset=mixed - id or name of a dataset (may be a list) return the taxons belonging to one or more Datasets
• limit and offset are SQL statements to limit the amount. See Common parameters.

Notice that id, name and root should not be combined.

Response fields

• id - this ODB id for this Taxon record in the taxons table
• senior_id - if invalid this ODB identifier of the valid synonym for this taxon (acceptedNameUsage) - only when taxonomicStatus == ‘invalid’
• parent_id - the id of the parent taxon
• author_id - the id of the person that defined the taxon for unpublished names (having an author_id means the taxon is unpublished)
• scientificName DWC - the full taxonomic name without authors (i.e. including genus name and epithet for species name)
• scientificNameID DWC - nomenclatural databases ids, if any external reference is stored for this Taxon record
• taxonRank DWC - the string value of the taxon rank
• level - the ODB numeric value of the taxon rank
• scientificNameAuthorship DWC - the taxon authorship. For taxonomicStatus unpublished: will be a ODB registered Person name
• namePublishedIn - unified bibliographic reference (i.e. either the short format or an extract of the bibtext reference assigned). This will be mostly retrieved from nomenclatural databases; Taxon linked references can be extracted with the BibReference endpoint.
• taxonomicStatus DWC - one of ‘accepted’, ‘invalid’ or ‘unpublished’; if invalid, fields senior_id and acceptedNameUsage* will be filled
• parentNameUsage DWC - the name of the parent taxon, if species, the genus, if genus, family, and so on
• family DWC - the family name if taxonRank family or below
• higherClassification DWC - the full taxonomic hierarchical classification, pipe separated (will include only Taxons registered in this database)
• acceptedNameUsage DWC - if taxonomicStatus invalid the valid scientificName for this Taxon
• acceptedNameUsageID DWC - if taxonomicStatus invalid the scientificNameID ids of the valid Taxon
• taxonRemarks DWC - any note the taxon record may have
• basisOfRecord DWC - will always be ’taxon’
• externalrefs - the Tropicos, IPNI, MycoBank, ZOOBANK or GBIF reference numbers

Traits Endpoint

The traits endpoint interact with the Trait table. The basic usage is getting a list of variables and variables categories for importing Measurements.

GET request-parameters

• id=list return only traits having the id or ids provided (ex id=1,2,3,10);
• name=string return only traits having the export_name as indicated (ex name=DBH)
• categories - if true return the categories for categorical traits
• language=mixed return name and descriptions of both trait and categories in the specified language. Values may be ’language_id’, ’language_code’ or ’language_name’;
• bibreference=boolean - if true, include the BibReference associated with the trait in the results;
• limit and offset are SQL statements to limit the amount. See Common parameters.

Response fields

• id - the id of the Trait in the odbtraits table (a local database id)
• type - the numeric code defining the Trait type
• typename - the name of the Trait type
• export_name - the export name value
• measurementType DWC - same as export_name for DWC compatibility
• measurementMethod DWC - combine name, description and categories if apply (included in the Measurement GET API, for DWC compatibility)
• measurementUnit - the unit of measurement for Quantitative traits
• measurementTypeBibkeys - the bibkeys of the bibliographic references associated with the trait definition, separated by pipe ‘|’
• taggedWith - the name of the tags or keywords associated with the trait definition, separated by pipe ‘|’
• range_min - the minimum allowed value for Quantitative traits
• range_max - the maximum allowed value for Quantitative traits
• link_type - if Link type trait, the class of the object the trait links to (currently only Taxon)
• name - the trait name in the language requested or in the default language
• description - the trait description in the language requested or in the default language
• value_length - the length of values allowed for Spectral trait types
• objects - the types of object the trait may be used for, separated by pipe ‘|’
• categories - each category is given for Categorical and Ordinal traits, with the following fields (the category id, name, description and rank). Ranks are meaningfull only for ORDINAL traits, but reported for all categorical traits.

Vernaculars Endpoint

The vernaculars endpoints interact with the Vernacular table. Their basic usage is getting vernaculars or popular names for taxons.

GET parameters

• id=list return only vernaculars having the id or ids provided (ex id=1,2,3,10)
• individual=mixed either a individual_id or a list of ids, or fullnames or uuids;
• taxon=mixed one of ids or scientificNames (ex id=1,2,3,10)
• taxon_root=mixed - same as taxon, but will include the descendants of the taxons informed. e.g taxon_root=Lauraceae to get any Lauraceae vernacular;

Vouchers Endpoint

The vouchers endpoints interact with the Voucher table. Their basic usage is getting data from Voucher specimens

GET parameters

• id=list return only vouchers having the id or ids provided (ex id=1,2,3,10)
• number=string returns only vouchers for the informed collector number (but is a string and may contain non-numeric codes)
• collector=mixed one of id or ids or abbreviations, returns only vouchers for the informed main collector
• dataset=list - one of id or ids list, name or names list, return all vouchers directly or indirectly related to the datasets informed.
• project=mixed one of ids or names, returns only the vouchers for datasets belonging to the Project informed.
• location=mixed one of ids or names; (1) if individual_tag is also requested returns only vouchers for those individuals (or use “individual=*” to get all vouchers for any individual collected at the location); (2) if individual and individual_tag are not informed, then returns vouchers linked to locations and to the individuals at the locations.
• location_root=mixed - same as location, but include also the vouchers for the descendants of the locations informed. e.g. “location_root=Manaus” to get any voucher collected within the Manaus administrative area;
• individual=mixed either a individual_id or a list of ids, or * - returns only vouchers for the informed individuals; when “individual=*” then location must be informed, see above;
• taxon=mixed one of ids or names, returns only vouchers for the informed taxons. This could be either vouchers referred as parent of the requested taxon or vouchers of individuals of the requested taxons.
• taxon_root=mixed - same as taxon, but will include in the return also the vouchers for the descendants of the taxons informed. e.g. “taxon_root=Lauraceae” to get any Lauraceae voucher;

Notice that some search fields (taxon, location, project and collector) may be specified as names - abbreviation, fullnames and emails in the case of collector - (eg, “taxon=Euterpe edulis”) or as database ids. If a list is specified for one of these fields, all items of the list must be of the same type.

Response fields

• id - the Voucher ODB id in the vouchers table (local database id)
• basisOfRecord DWC - will be always ‘preservedSpecimen’ [dwc location](DWC
• occurrenceID DWC - a unique identifier for the Voucher record - combine organismID with biocollection info
• organismID DWC - a unique identifier for the Individual the Voucher belongs to
• individual_id - the ODB id for the Individual the Voucher belongs to
• collectionCode DWC - the Biocollection acronym where the Voucher is deposited
• catalogNumber DWC - the Biocollection number or code for the Voucher
• typeStatus DWC - if the Voucher represent a nomenclatural type
• recordedBy DWC - collectors pipe “|” separated list of registered Persons abbreviations that collected the vouchers
• recordedByMain - the first person in recordedBy, the main collector
• recordNumber DWC - an identifier for the Voucher, generaly the Collector Number value
• recordedDate DWC - the record date, collection date
• scientificName DWC - the current taxonomic identification of the individual (no authors) or “unidentified”
• scientificNameAuthorship DWC - the taxon authorship. For taxonomicStatus unpublished: will be a ODB registered Person name
• family DWC
• genus DWC
• identificationQualifier DWC - identification name modifiers cf. aff. s.l., etc.
• identifiedBy DWC - the Person identifying the scientificName of this record
• dateIdentified DWC - when the identification was made (may be incomplete, with 00 in the month and or day position)
• identificationRemarks DWC - any notes associated with the identification
• locationName - the location name for the organismID the voucher belongs to (if plot the plot name, if point the point name, …)
• higherGeography DWC - the parent LocationName ‘|’ separated (e.g. Brasil | Amazonas | Rio Preto da Eva | Fazenda Esteio | Reserva km37);
• decimalLatitude DWC - depends on the location adm_level and the individual X and Y, or Angle and Distance attributes, which are used to calculate these global coordinates for the record; if individual has multiple locations (a monitored bird), the location closest to the voucher date is obtained
• decimalLongitude DWC - same as for decimalLatitude
• occurrenceRemarks DWC - text note associated with this record
• associatedMedia DWC - urls to ODB media files associated with the record
• datasetName - the name of the ODB Dataset to which the record belongs to DWC
• accessRights - the ODB Dataset access privacy setting - DWC
• bibliographicCitation - the ODB Dataset citation - DWC
• license - the ODB Dataset license - DWC

Jobs Endpoint

The jobs endpoints interact with the UserJobs table. The basic usage is getting a list of submitted data import jobs, along with a status message and logs. You can also get data from jobs produced using the save_job=1 parameter, or export jobs created using the web interface (with the csv option only)

GET parameters

• status=string return only jobs for the specified status: “Submitted”, “Processing”, “Success”, “Failed” or “Cancelled”;
• id=list - the job id or ids ;
• get_file - if get_file=1, then you can get the data file saved by the job. This needs also a single id parameter. Useful, when getting data with the save_job=1 option.

Response fields

• id - the job id
• status - the status of the job
• dispatcher - the type of the job, e.g, ImportTaxons;
• log - the job log messages, usually indicating whether the resources were successfully imported, or whether errors occurred; others.

Possible errors

This should be an extensive list of error codes that you can receive while using the API. If you receive any other error code, please file a bug report!

• Most of the time will be related to memory, if you are trying to get a large dataset, for example. See the get common parameters
• Error 401 - Unauthenticated. Currently not implemented. You may receive this error if you attempt to access some protected resources but didn’t provide an API token.
• Error 403 - Unauthorized. You may receive this error if you attempt to import or edit some protected resources, and either didn’t provide an API token or your user does not have enough privileges.
• Error 404 - The resource you attempted to see is not available. Note that you can receive this code if your user is not allowed to see a given resource.
• Error 413 - Request Entity Too Large. You may be attempting to send a very large import, in which case you might want to break it down in smaller pieces.
• Error 429 - Too many attempts. Wait one minute and try again.
• Error 500 - Internal server error. This indicates a problem with the server code. Please file a bug report with details of your request.

3 - POST data

POST BibReferences

To import bibliographic references, two options with precedence over DOI:

• doi - the DOI number or URL of the reference to be registered
• bibtex - alternatively, a bibliographic record in the format bibtex

POST Biocollections

To import biocollection names:

• name - the full name of the biological collection
• acronym - the acronym or acronym of the biological collection

POST Individuals

Request fields allowed when importing individuals:

• collector=mixed - required - persons ‘id’, ‘abbreviation’, ‘full_name’, ’email’; if multiple persons, separate values in your list with pipe | or ; because commas may be present within names. Main collector is the first on the list;
• tag=string - required - the individual number or code (if the individual identifier is as MainCollector+Number, this is the field for Number);
• dataset=mixed - required - name or id of the Dataset;
• date=YYYY-MM-DD or array - the date the individual was recorded/tagged, for historical records you may inform an incomplete string in the form “1888-05-NA” or “1888-NA-NA” when day and/or month are unknown. You may also inform as an array in the form “date={ ‘year’ : 1888, ‘month’: 5}”. OpenDataBio deals with incomplete dates, see the IncompleteDate Model. At least year is required.
• notes - any annotation for the Individual, plain text or data in JSON;

Location fields (one or multiple locations may be informed for the individual). Possible fields are:

• location - the Individual’s location name or id required if longitude and latitude are not informed
• latitude and longitude- geographical coordinates in decimal degrees; required if location is not informed
• altitude - the Individual location elevation (altitude) in meters above see level. Must be a integer value;
• location_notes - any note for the individual location, plain text or data in JSON;
• location_date_time - if different than the individual’s date, a complete date or a date+time value for the individual first location. Mandatory for multiple locations;
• x - if location is of Plot type, the x coordinate of the individual in the location;
• y - if location is of Plot type, the y coordinate of the individual in the location;
• distance - if location is of POINT type, the individual distance in meters from the location;
• angle - if location is of POINT type, the individual azimuth (angle) from the location;

Identification fields. Identification is not mandatory, and may be informed in two different ways: (1) self identification - the individual may have its own identification; or (2), other identification - the identification is the same as that of another individual (for example, from an individual having a voucher in some biocollection).

1. For (self) identification at least taxon and identifier must be informed. The list of possible fields are:
   • taxon=mixed - name or id of the identified taxon, e.g. ‘Ocotea delicata’ or its id
   • identifier=mixed - persons responsible for the taxonomic identification. persons ‘id’, ‘abbreviation’, ‘full_name’, ’email’; if multiple persons, separate values in your list with pipe | or ; because commas may be present within names.
   • identification_date or identification_date_year, identification_date_month, and/or identification_date_day - complete or incomplete. If empty, the individual’s date is used;
   • modifier - name or number for the identification modifier. Possible values ’s.s.’=1, ’s.l.’=2, ‘cf.’=3, ‘aff.’=4, ‘vel aff.’=5, defaults to 0 (none).
   • identification_notes - any identification notes, plain text or data in JSON;
   • identification_based_on_biocollection - the biocollection name or id if the identification is based on a reference specimen deposited in an biocollection
   • identification_based_on_biocollection_id - only fill if identification_based_on_biocollection is present;
2. If the identification is other:
   • identification_individual - id or fullname (organimsID) of the Individual having the identification.

If the Individual has Vouchers with the same Collectors, Date and CollectorNumber (Tag) as those of the Individual, the following fields and options allow to store the vouchers while importing the Individual record (alternatively, you may import voucher after importing individuals using the Voucher EndPoint. Vouchers for the individual may be informed in two ways:

1. As separate string fields:

• biocollection - A string with a single value or a comma separated list of values. Values may be the id or acronym values of the Biocollection Model. Ex: “{ ‘biocollection’ : ‘INPA;MO;NY’}” or “{ ‘biocollection’ : ‘1,10,20’}”;
• biocollection_number - A string with a single value or a comma separated list of values with the BiocollectionNumber for the Individual Voucher. If a list, then must have the same number of values as biocollection;
• biocollection_type - A string with a single numeric code value or a comma separated list of values for Nomenclatural Type for the Individual Vouchers. The default value is 0 (Not a Type). See nomenclatural types list.

2. AS a single field biocollection containing an array with each element having the fields above for a single Biocollection: “{ { ‘biocollection_code’ : ‘INPA’, ‘biocollection_number’ : 59786, ‘biocollection_type’ : 0}, { ‘biocollection_code’ : ‘MG’, ‘biocollection_number’ : 34567, ‘biocollection_type’ : 0} }”

POST Individual-locations

The individual-locations endpoint allows importing multiple locations for registered individuals. Designed for occurrences of organisms that move and have multiple locations.

Possible fields are:

• individual - the Individual’s id required
• location - the Individual’s location name or id required OR longitude+latitude
• latitude and longitude- geographical coordinates in decimal degrees; required if location is not informed
• altitude - the Individual location elevation (altitude) in meters above see level;
• location_notes - any note for the individual location, plain text or data in JSON;
• location_date_time - if different than the individual’s date, a complete date or a date+time (hh:mm:ss) value for the individual location. required
• x - if location is of Plot type, the x coordinate of the individual in the location;
• y - if location is of Plot type, the y coordinate of the individual in the location;
• distance - if location is of POINT type (or latitude and longitude are informed), the individual distance in meters from the location;
• angle - if location is of POINT type, the individual azimuth (angle) from the location

POST Locations

The locations endpoints interact with the locations table. Use to import new locations.

Make sure your geometry projection is EPSG:4326 WGS84. Use this standard!

Available POST fields:

• name - the location name - required (parent+name must be unique in the database)
• adm_level - must be numeric, see location get api - required
• geometry use either: required
  • geom for a WKT representation of the geometry, POLYGON, MULTIPOLYGON, POINT OR LINESTRING allowed;
  • lat and long for latitude and longitude in decimal degrees (use negative numbers for south/west).
• altitude - in meters
• datum - defaults to ‘EPSG:4326-WGS 84’ and your are strongly encourage of importing only data in this projection. You may inform a different projection here;
• parent - either the id or name of the parent location. The API will detect the parent based on the informed geometry and the detected parent has priority if informed is different. However, only when parent is informed, validation will also test whether your location falls within a buffered version of the informed parent, allowing to import locations that have a parent-child relationship but their borders overlap somehow (either shared borders or differences in georeferencing);
• when location is plot (adm_level=100), optional fields are:
  • x and y for the plot dimensions in meters(defines the Cartesian coordinates)
  • startx and starty for start position of a subplot in relation to its parent plot location;
• notes - any note you wish to add to your location, plain text or data in JSON;
• azimuth - apply only for Plots and Transects when registered with a POINT geometry - azimuth will be used to build the geometry. For plots the point coordinate refer to the 0,0 vertice of the plot polygon that will be build clockwise starting from the informed point, the azimuth and the y dimension. For transects, the informed point coordinates are the start point and a linestring will be build using this azimuth and x dimension.
• ismarine - to permit the importation of location records that not fall within any register parent location you may add ismarine=1. Note, however, that this allows you to import misplaced locations. Only use if your location is really a marine location that fall outside any Country border;

alternatively: you may just submit a single column named geojson containing a Feature record, with its geometry and having as ‘properties’ at least tags name and adm_level (or admin_level). See geojson.org. This is usefull, for example, to import country political boundaries (https://osm-boundaries.com/).

POST Measurements

The measurements endpoint allows to import measurements.

The following fields are allowed in a post API:

• dataset=number - the id of the dataset where the measurement should be placed required
• date=YYYY-MM-DD - the observation date for the measurement, must be passed as YYYY-MM-DD required
• object_type=string - either ‘Individual’,‘Location’,‘Taxon’ or ‘Voucher’, i.e. the object from where the measurement was taken required
• object_id=number - the id of the measured object, either (individuals.id, locations.id, taxons.id, vouchers.id) required
• person=mixed persons responsible for the measurements. You may inform ‘id’, ‘abbreviation’, ‘full_name’ or ’email’. If multiple persons, separate values in your list with pipe | or ; because commas may be present within names. required
• trait_id=number or string - either the id or export_name for the measurement. required
• value=number, string list - this will depend on the trait type, see tutorial required, optional for trait type LINK
• link_id=number - the id of the linked object for a Trait of type Link required if trait type is Link DEPRECATED REPLACED BY location
• location or location_id - the id or name of the Location of a measurement related to a Taxon. Only Taxons can also have a location associated with them. This replaces the Link-type Trait logic.
• bibreference=number - the id of the BibReference for the measurement. Should be use when the measurement was taken from a publication
• notes - any note you whish. In same cases this is a usefull place to store measurement related information. For example, when measuring 3 leaves of a voucher, you may indicate here to which leaf the measurement belongs, leaf1, leaf2, etc. allowing to link measurements from different traits by this field. Plain text or data in JSON;
• duplicated - by default, the import API will prevent duplicated measurements for the same trait, object and date; specifying duplicated=#, where # is the stored number of records+1. For example, there is already one record, you must inform duplicated=2 if there are two, a third can be stored using duplicated=3.
• parent_measurement = number only - the ‘id’ of another measurement which is the parent of the measurement being imported. This creates a relationship between these measurements. The ‘id’ will be validated and must be from a measurement belonging to the same object, same date and different variable. E.g. leaf width may be linked to a measurement of leaf length.

POST Media

The media endpoint interacts with the Media table, and the import process works the same way as batch uploading via the web interface.

The API should receive a ZIP file containing the images to be imported, along with one CSV file, which may include the following attributes for each image:

• filename – required: the exact name of the image file
• object_type – required: must be one of the following values: ['Individual', 'Voucher', 'Location', 'Taxon']
• object_id – required: the numeric ID of the object_type related to the image
• collector – a list of registered collector numbers or names who will be considered the authors of the image; can be persons.id, abbreviation, full_name, or email. If multiple people are listed, separate values with a vertical bar | or semicolon ; (since names may contain commas).
• tags – a list of numeric IDs or names of Tags, i.e., keywords describing the image content; separated by ; or |
• date – the date of the image in YYYY-MM-DD format; if not provided, the import date will be used
• title_en and/or title_pt – one or more columns with the title of the image in the registered languages
• license – one of the following public licenses from CreativeCommons.org:
  ['CC0', 'CC-BY', 'CC-BY-SA', 'CC-BY-ND', 'CC-BY-NC', 'CC-BY-NC-SA', 'CC-BY-NC-ND']
  If not specified, the default will be CC-BY-SA
• dataset – the name (acronym) or ID of the dataset to which the media will be linked — the media access permissions will match those of the dataset
• project – the name (acronym) or ID of the project to associate with the media
• notes – any general note about the file content
• location – the ID or name of the Location to link the media to — for media linked to Taxon, you can alternatively use latitude and longitude
• longitude – longitude in decimal degrees (negative for West) — for media linked to Taxon
• latitude – latitude in decimal degrees (negative for South) — for media linked to Taxon

POST Persons

The persons endpoint interact with the Person table. The following fields are allowed when importing persons using the post API:

• full_name - person full name, required
• abbreviation - abbreviated name, as used by the person in publications, as collector, etc. (if left blank, a standard abbreviation will be generated using the full_name attribute – abbreviation must be unique within a ODB installation);
• email - an email address,
• institution - to which institution this person is associated;
• biocollection - name or acronym of the Biocollection to which this person is associated.

POST Taxons

Use to import new taxon names.

The POST API requires ONLY the full name of the taxon to be imported, i.e. for species or below species taxons the complete name must be informed (e.g. Ocotea guianensis or Licaria cannela aremeniaca). The script will validate the name retrieving the remaining required info from the nomenclatural databases using their API services. It will search GBIF and Tropicos if the case and retrieve taxon info, their ids in these repositories and also the full classification path and senior synonyms (if the case) up to when it finds a valid record name in this ODB database. So, unless you are trying to import unpublished names, just submit the name parameter of the list below.

Possible fields:

• name - taxon full name required, e.g. “Ocotea floribunda” or “Pagamea plicata glabrescens”
• level - may be the numeric id or a string describing the taxonRank recommended for unpublished names
• parent - the taxon’s parent full name or id - note - if you inform a valid parent and the system detects a different parent through the API to the nomenclatural databases, preference will be given to the informed parent; required for unpublished names
• bibreference - a textual reference in which the taxon was published;
• bibkey - a registered BibReference - either the numeric id or the bibkey
• author - the taxon author’s name;
• author_id or person - the registered Person name, abbreviation, email or id, representing the author of unpublished names - required for unpublished names
• valid - boolean, true if this taxon name is valid; 0 or 1
• mobot - Tropicos.org id for this taxon
• ipni - IPNI id for this taxon
• mycobank - MycoBank id for this taxon
• zoobank - ZOOBANK id for this taxon
• gbif - GBIF nubKey for this taxon

POST Traits

When entering few traits, it is strongly recommended that you enter traits one by one using the Web Interface form, which reduces the chance of duplicating trait definitions.

The traits endpoint interact with the Trait table. The POST method allows you to batch import traits into the database and is designed for transferring data to OpenDataBio from other systems, including Trait Ontologies.

1. As noted under the Trait Model description, it is important that one really checks whether a needed Trait is not already in the DataBase to avoid multiplication of redundant traits. The Web Interface facilitates this process. Through the API, OpenDataBio only checks for identical export_name, which must be unique within the database. Note, however, that Traits should also be as specific as possible for detailed metadata annotations.
2. Traits use User Translations for names and descriptions, allowing a multiple-languages

Fields allowed for the traits/ post API:

• export_name=string - a short name for the Trait, which will be used during data exports, are more easily used in trait selection inputs in the web-interface and also during data analyses outside OpenDataBio. Export names must be unique and have no translation. Short and CamelCase export names are recommended. Avoid diacritics (accents), special characters, dots and even white-spaces. required
• type=number - a numeric code specifying the trait type. See the Trait Model for a full list. required
• objects=list - a list of the Core objects the trait is allowed to be measured for. Possible values are ‘Individual’, ‘Voucher’, ‘Location’ and/or ‘Taxon’, singular and case sensitive. Ex: “{‘object’: ‘Individual,Voucher’}”; required
• name=json - see translations below; required
• description=json - see translations below; required
• Trait specific fields:
  • unit=string - required for quantitative traits only (the unit o measurement). This must be either a code or a name (in any language) of a unit already stored in the database. Units can only be define through the web interface.
  • range_min=number - optional for quantitative traits. specify the minimum value allowed for a Measurement.
  • range_max=number - optional for quantitative. maximum allowed value for the trait.
  • categories=json - required for categorical and ordinal traits; see translations below
  • wavenumber_min and wavenumber_max - required for spectral traits = minimum and maximum WaveNumber within which the ‘value_length’ absorbance or reflectance values are equally distributed. May be informed in range_min and range_max, priority for prefix wavenumber over range if both informed.
  • value_length - required for spectral traits = number of values in spectrum
  • link_type- required for Link traits - the class of link type, fullname or basename: eg. ‘Taxon’ or ‘App\Models\Taxon’.
• bibreference=mix - the id(s) or bibkey(s) of a BibReference already stored in the database, separated by ‘|’ or ‘;’
• parent - id or export_name of another Trait to which the current trait depends on. If you indicate a trait here, this means you add a RESTRICTION on the validation of the measurements. Adding a Measurement for the current trait will DEPEND on the database having a measurement for the trait here indicated, for the same object and same date. Example, you create a trait called POM (point of measurement) for recording the height on a tree where you measure a DBH (diameter at breast height). Adding DBH as a trait on which POM depends upon, means you can only add POM if there is a DBH value for the same tree on the same date.

Translations

• Fields name, description must have the following structure to account for User Translations. They should be a list with the language as ‘keys’. For example a name field may be informed as:

  • using the Language code as keys:

   [
     {"en": "Diâmetro na altura do peito"," pt-br": "Diâmetro a Altura do Peito"}
   ]
  

  • or using the Language ids as keys:

   [
     {"1":"Diâmetro à altura do peito","2":"Diâmetro a Altura do Peito"}
   ]
  

  • or using the Language names as keys:

   [
     {"English":"Diameter at Breast Height","Portuguese": "Diâmetro a Altura do Peito"}
   ]
  

• Alternatively, you can add the information as separate parameters. Instead of name you can use name.LANGUAGE_CODIGO_ou_ID, for example name.en or name.1 for the name in English and name.pt-br or name.2 for the name in Portuguese. Likewise for description: description.en or description.1, etc.

• Field categories must include for each category+rank+lang the following fields:

  • lang=mixed - the id, code or name of the language of the translation, required
  • name=string - the translated category name required (name+rank+lang must be unique)
  • rank=number - the rank for ordinal traits; for non-ordinal, rank is important to indicate the same category across languages, so may just use 1 to number of categories in the order you want. required
  • description=string - optional for categories, a definition of the category.
  • Example for categories:

    [
      {"lang":"en","rank":1,"name":"small","description":"smaller than 1 cm"},
      {"lang":"pt-br","rank":1,"name":"pequeno","description":"menor que 1 cm"}
      {"lang":"en","rank":1,"name":"big","description":"bigger than 10 cm"},
      {"lang":"pt-br","rank":1,"name":"grande","description":"maior que 10 cm"},
    ]
  

• Valid languages may be retrieved with the Language API.

POST Vernaculars

The vernaculars endpoint interacts with the Vernacular table, which contains information on common names to be related to Taxon and/or Individual records.

The following fields are allowed in the data import:

• name - required - the common name to be recorded;
• language - required - the name, code or id of the language related to the common name. See languages ​​endpoint
• taxons = list - scientific names or ids of taxons. See taxons endpoint
• individuals = list - fullnames, ids or uuids of individuals. See individuals endpoint
• citations = list - one or more bibliographic citations, which may have the following fields:
• citation = string - the text of the citation
• bibreference = mixed - the id or bibkey of the bibliographic reference that must be previously registered See bibreferences endpoint
• notes - any annotation
• parent - the id or name of another Vernacular to inform variants of popular names
• type - one of ‘use’ or ‘generic’ or ’etimology’

POST Vouchers

The vouchers endpoint interact with the Voucher table.

The following fields are allowed in a post API:

• individual=mixed - the numeric id or organismID of the Individual the Voucher belongs to required;
• biocollection=mixed - the id, name or acronym of a registered Biocollection the Voucher belongs to required;
• biocollection_type=mixed - the name or numeric code representing the kind of nomenclature type the Voucher represents in the Biocollection. If not informed, defaults to 0 = ‘Not a Type’. See nomenclature types for a full list of options;
• biocollection_number=mixed - the alpha numeric code of the voucher in the biocollection;
• number=string - the main collector number -only if different from the tag value of the Individual the voucher belongs to;
• collector=mixed - either ids or abbreviations of persons. When multiple values are informed the first is the main collector. Only if different from the Individual collectors list;
• date=YYYY-MM-DD or array - needed only if, with collector and number, different from Individual values. Date may be an IncompleteDate Model.
• dataset=number - inherits the project the Individual belongs too, but you may provide a different project if needed
• notes=string - any text note to add to the voucher, plain text or data in JSON;

Notes field

The notes field of any model is for plain text or text formatted as a JSON object containing structured data. The Json option allows you to store custom structured data in any model that has the notes field. You can, for example, store some secondary fields from original sources as notes when importing data, but you can store any additional data that is not provided by the OpenDataBio database framework. This data will not be validated nor searchable 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.

4 - Update Data - PUT