Quick reference
List of endpoints and parameters!
5 minute read
API call format
base-URL + ‘/api/v0/’ + endpoint + ‘?’ + request-parametersTaxons endpoint example
https://opendb.inpa.gov.br/api/v0/taxons?valid=1&limit=2&offset=10GET DATA (downloads)
Shared get-parameters
When multiple parameters are specified, they are combined with an AND operator. There is no OR parameter option in searches.
All endpoints share these GET parameters:
idreturn only the specified resource. May be number or a comma delimited list, such asapi/v0/locations?id=1,50,124limit: the number of items that should be returned (must be greater than 0). Example:api/v0/taxons?limit=10offset: 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=10000returns 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=allmay 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,validsave_job: for large data retrieval, if you addsave_job=1to the params list a job will be created for your search, and the data can then be obtained using the userjobs api.
Download large datasets?
Thelimit and offset parameters can be used to divide your search into parts. Alternatively, use the save_job=T option and then download the data with the get_file=T parameter from the userjobs API.wildcards
Some parameters accept an asterisk as wildcard, soapi/v0/taxons?name=Euterpe will return taxons with name exactly as “Euterpe”, while api/v0/taxons?name=Eut* will return names starting with “Eut”.Endpoint parameters
| Endpoint | Description | Possible parameters |
|---|---|---|
| / | Tests your access | none |
| bibreferences | Lists of bibliographic references | id, bibkey |
| biocollections | List of Biocollections and other vouchers Repositories | id |
| datasets | Lists registered datasets or downloand the files of dataset versions | id, list_versions, file_name |
| individuals | Lists registered individuals | id, location, location_root,taxon, taxon_root, tag,project, dataset |
| individual-locations | Lists occurrences for individuals | individual_id, location, location_root,taxon, taxon_root, dataset |
| languages | Lists registered languages | |
| measurements | Lists Measurements | id, taxon,taxon_root,dataset,trait,individual,voucher,location,location_root |
| media | Lists Media Metadata | id, taxon,taxon_root,dataset,individual,voucher,location,location_root |
| locations | Lists locations | root, id, parent_id,adm_level, name, limit, querytype, lat, long,project,dataset |
| persons | Lists registered people | id, search, name, abbrev, email |
| projects | Lists registered projects | id only |
| taxons | Lists taxonomic names | root, id, name,level, valid, external, project,dataset |
| traits | Lists variables (traits) list | id, name |
| vernacular | Lists vernaculars | id, individual,taxon,taxon_root |
| vouchers | Lists registered voucher specimens | id, number, individual, location, collector, location_root,taxon, taxon_root, project, dataset |
| userjobs | Lists user Jobs | id, status,get_file |
POST DATA (imports)
Web-interface note
- Importing data from files through the web-interface require specifying the POST verb parameters of the ODB API
- Batch imports of Bibliographic References and MediaFiles are possible only through the web interface.
| Endpoint | Description | POST Fields |
|---|---|---|
| bibreferences | Import BibReferences | doi or bibtex |
| biocollections | Import BioCollections | name, acronym |
| individuals | Import individuals | collector, tag, dataset, date, (location or latitude + longitude)**, altitude, location_notes, location_date_time, x, y, distance , angle , notes , taxon , identifier , identification_date , modifier, identification_notes , identification_based_on_biocollection, identification_based_on_biocollection_id , identification_individual |
| individual-locations | Import IndividualLocations | individual, (location or latitude + longitude), altitude, location_notes, location_date_time, x, y, distance, angle |
| locations | Import locations | name, adm_level, (geom or lat+long)** , parent, altitude, datum, x, y , startx, starty, notes, ismarine |
| measurements | Import Measurements to Datasets | dataset, date, object_type, object_id, person, trait_id, value**, link_id, bibreference, notes, duplicated,location, parent_measurement |
| media | Import Media | a zip file containing media and an attribute table see details here |
| persons | Imports a list of people | full_name**, abbreviation, email, institution, biocollection |
| traits | Import traits | export_name, type, objects, name, description**, units, range_min, range_max, categories, wavenumber_min and wavenumber_max, value_length, link_type, bibreference, tags |
| taxons | Imports taxonomic names | name**, level, parent, bibreference, author, author_id or person, valid, mobot, ipni, mycobank, zoobank, gbif |
| vouchers | Imports voucher specimens | individual, biocollection, biocollection_type, biocollection_number, number, collector, date, dataset, notes |
| vernacular | Imports Vernaculars | name, language,taxons,individuals,citations,parent,type |
PUT DATA (updates)
Attention
Only the endpoints listed below can be updated using the API and only the listed PUT fields can be updated on each endpoint. Field values are as explained for the POST API endpoints, except that in all cases you must also provide theid of the record to be updated.| Endpoint | Description | PUT Fields |
|---|---|---|
| individuals | Update Individuals | (id or individual_id),collector, tag, dataset, date, notes , taxon , identifier , identification_date , modifier, identification_notes , identification_based_on_biocollection, identification_based_on_biocollection_id , identification_individual |
| individual-locations | Update Individual Locations | (id or individual_location_id), individual, (location or latitude + longitude), altitude, location_notes, location_date_time, x, y, distance, angle |
| locations | Update Locations | (id or location_id), name, adm_level, (geom or lat+long) , parent, altitude, datum, x, y , startx, starty, notes, ismarine |
| measurements | Update Measurements | (id or measurement_id), dataset, date, object_type, object_type, person, trait_id, value, link_id, bibreference, notes, duplicated,location, parent_measurement |
| media | Update Media Metadata | (media_id ou media_uuid), collector,tags, date, title_en, title_pt, license, dataset, project, notes, (location ou longitude + latitude) |
| persons | Update Persons | (id or person_id),full_name, abbreviation, email, institution, biocollection |
| vouchers | Update Vouchers | (id or voucher_id),individual, biocollection, biocollection_type, biocollection_number, number, collector, date, dataset, notes |
Nomenclature types
| Nomenclature types numeric codes | |
|---|---|
| NotType : 0 | Isosyntype : 8 |
| Type : 1 | Neotype : 9 |
| Holotype : 2 | Epitype : 10 |
| Isotype : 3 | Isoepitype : 11 |
| Paratype : 4 | Cultivartype : 12 |
| Lectotype : 5 | Clonotype : 13 |
| Isolectotype : 6 | Topotype : 14 |
| Syntype : 7 | Phototype : 15 |
Taxon Level (Rank)
| Level | Level | Level | Level |
|---|---|---|---|
-100 clade | 60 cl., class | 120 fam., family | 210 section, sp., spec., species |
0 kingdom | 70 subcl., subclass | 130 subfam., subfamily | 220 subsp., subspecies |
10 subkingd. | 80 superord., superorder | 150 tr., tribe | 240 var., variety |
30 div., phyl., phylum, division | 90 ord., order | 180 gen., genus | 270 f., fo., form |
40 subdiv. | 100 subord. | 190 subg., subgenus, sect. |