Quick reference
List of endpoints and parameters!
6 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.
Download large datasets?
The `limit` 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](/en/docs/api/get-data/#jobs-endpoint).wildcards
Some parameters accept an asterisk as wildcard, so `api/v0/taxons?name=Euterpe` will return taxons with name exactly as "Euterpe", while `api/v0/taxons?name=Eut*` will return names starting with "Eut".| Parameter | Required | Description | Example |
|---|---|---|---|
id | No | Single id or comma-separated list to filter or target records. | 1,2,3 |
limit | No | Maximum number of records to return. | 100 |
offset | No | The starting position of the record set to be exported. Used together with limit to limit results. | 10000 |
fields | No | Comma separated list of the fields to include in the response or special words all/simple/raw, default to simple | id,scientificName or all |
save_job | No | If 1, save the results as file to download later via userjobs + get_file = T | 1 |
Endpoint parameters
| Endpoint | Description | Parameters |
|---|---|---|
| / | Tests your access/token. | — |
| bibreferences | Bibliographic references (GET lists, POST creates). | id, bibkey, biocollection, dataset, fields, job_id, limit, offset, save_job, search, taxon, taxon_root |
| biocollections | Biocollections (GET lists, POST creates). | id, acronym, fields, irn, job_id, limit, name, offset, save_job, search |
| datasets | Datasets and published dataset files (GET lists, POST creates via import job). | id, bibreference, fields, file_name, has_versions, include_url, limit, list_versions, name, offset, project, save_job, search, summarize, tag, tagged_with, taxon, taxon_root, traits |
| individuals | Individuals (GET lists, POST creates, PUT updates). | id, dataset, date_max, date_min, fields, job_id, limit, location, location_root, odbrequest_id, offset, person, project, save_job, tag, taxon, taxon_root, trait, vernacular |
| individual-locations | Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts). | id, dataset, date_max, date_min, fields, individual, limit, location, location_root, offset, person, project, save_job, tag, taxon, taxon_root |
| languages | Lists available interface/data languages. | fields, limit, offset |
| locations | Locations (GET lists, POST creates, PUT updates). | id, adm_level, dataset, fields, job_id, lat, limit, location_root, long, name, offset, parent_id, project, querytype, root, save_job, search, taxon, taxon_root, trait |
| measurements | Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates). | id, bibreference, dataset, date_max, date_min, fields, individual, job_id, limit, location, location_root, measured_id, measured_type, offset, person, project, save_job, taxon, taxon_root, trait, trait_type, voucher |
| media | Media metadata (GET lists, POST creates, PUT updates). | id, dataset, fields, individual, job_id, limit, location, location_root, media_id, media_uuid, offset, person, project, save_job, tag, taxon, taxon_root, uuid, voucher |
| persons | People (GET lists, POST creates, PUT updates). | id, abbrev, email, fields, job_id, limit, name, offset, save_job, search |
| projects | Projects (GET lists). | id, fields, job_id, limit, offset, save_job, search, tag |
| taxons | Taxonomic names (GET lists, POST creates). | id, bibreference, biocollection, dataset, external, fields, job_id, level, limit, location_root, name, offset, person, project, root, save_job, taxon_root, trait, valid, vernacular |
| traits | Trait definitions (GET lists, POST creates). | id, bibreference, categories, dataset, fields, job_id, language, limit, name, object_type, offset, save_job, search, tag, taxon, taxon_root, trait, type |
| vernaculars | Vernacular names (GET lists, POST creates). | id, fields, individual, job_id, limit, location, location_root, offset, save_job, taxon, taxon_root |
| vouchers | Voucher specimens (GET lists, POST creates, PUT updates). | id, bibreference, bibreference_id, biocollection, biocollection_id, collector, dataset, date_max, date_min, fields, individual, job_id, limit, location, location_root, main_collector, number, odbrequest_id, offset, person, project, save_job, taxon, taxon_root, trait, vernacular |
| userjobs | Background jobs (imports/exports) (GET lists). | id, fields, get_file, limit, offset, status |
| activities | Lists activity log entries. | id, description, fields, individual, language, limit, location, log_name, measurement, offset, save_job, subject, subject_id, taxon, taxon_root, voucher |
| tags | Tags/keywords (GET lists). | id, dataset, fields, job_id, language, limit, name, offset, project, save_job, search, trait |
POST DATA (imports)
Web-interface note
Importing data from files through the web-interface require specifying the POST verb parameters of the ODB API| Endpoint | Description | Parameters |
|---|---|---|
| bibreferences | Bibliographic references (GET lists, POST creates). | bibtex, doi |
| biocollections | Biocollections (GET lists, POST creates). | acronym, name |
| individuals | Individuals (GET lists, POST creates, PUT updates). | altitude, angle, biocollection, biocollection_number, biocollection_type, collector, dataset, date, distance, identification_based_on_biocollection, identification_based_on_biocollection_number, identification_date, identification_individual, identification_notes, identifier, latitude, location, location_date_time, location_notes, longitude, modifier, notes, tag, taxon, x, y |
| individual-locations | Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts). | altitude, angle, distance, individual, latitude, location, location_date_time, location_notes, longitude, x, y |
| locations | Locations (GET lists, POST creates, PUT updates). | adm_level, altitude, azimuth, datum, geojson, geom, ismarine, lat, long, name, notes, parent, startx, starty, x, y |
| locations-validation | Validates coordinates against registered locations (POST). | latitude, longitude |
| measurements | Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates). | bibreference, dataset, date, duplicated, link_id, location, notes, object_id, object_type, parent_measurement, person, trait_id, value |
| media | Media metadata (GET lists, POST creates, PUT updates). | collector, dataset, date, filename, latitude, license, location, longitude, notes, object_id, object_type, project, tags, title_en, title_pt |
| persons | People (GET lists, POST creates, PUT updates). | abbreviation, biocollection, email, full_name, institution |
| taxons | Taxonomic names (GET lists, POST creates). | author, author_id, bibreference, gbif, ipni, level, mobot, mycobank, name, parent, person, valid, zoobank |
| traits | Trait definitions (GET lists, POST creates). | bibreference, categories, description, export_name, link_type, name, objects, parent, range_max, range_min, tags, type, unit, value_length, wavenumber_max, wavenumber_min |
| vernaculars | Vernacular names (GET lists, POST creates). | citations, individuals, language, name, notes, parent, taxons, type |
| vouchers | Voucher specimens (GET lists, POST creates, PUT updates). | biocollection, biocollection_number, biocollection_type, collector, dataset, date, individual, notes, number |
| datasets | Datasets and published dataset files (GET lists, POST creates via import job). | description, license, name, privacy, project_id, title |
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 the `id` of the record to be updated.| Endpoint | Description | Parameters |
|---|---|---|
| individuals | Individuals (GET lists, POST creates, PUT updates). | id, collector, dataset, date, identification_based_on_biocollection, identification_based_on_biocollection_number, identification_date, identification_individual, identification_notes, identifier, individual_id, modifier, notes, tag, taxon |
| individual-locations | Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts). | id, altitude, angle, distance, individual, individual_location_id, latitude, location, location_date_time, location_notes, longitude, x, y |
| locations | Locations (GET lists, POST creates, PUT updates). | id, adm_level, altitude, datum, geom, ismarine, lat, location_id, long, name, notes, parent, startx, starty, x, y |
| measurements | Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates). | id, bibreference, dataset, date, duplicated, link_id, location, measurement_id, notes, object_id, object_type, parent_measurement, person, trait_id, value |
| media | Media metadata (GET lists, POST creates, PUT updates). | id, collector, dataset, date, latitude, license, location, longitude, media_id, media_uuid, notes, project, tags, title_en, title_pt |
| persons | People (GET lists, POST creates, PUT updates). | id, abbreviation, biocollection, email, full_name, institution, person_id |
| vouchers | Voucher specimens (GET lists, POST creates, PUT updates). | id, biocollection, biocollection_number, biocollection_type, collector, dataset, date, individual, notes, number, voucher_id |
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 |
Taxonomic ranks
| Code | Rank |
|---|---|
| -100 | clade |
| 0 | kingdom |
| 10 | subkingd. |
| 30 | div., phyl., phylum, division |
| 40 | subdiv. |
| 60 | cl., class |
| 70 | subcl., subclass |
| 80 | superord., superorder |
| 90 | ord., order |
| 100 | subord. |
| 120 | fam., family |
| 130 | subfam., subfamily |
| 150 | tr., tribe |
| 180 | gen., genus |
| 190 | subg., subgenus, sect. |
| 210 | section, sp., spec., species |
| 220 | subsp., subspecies |
| 240 | var., variety |
| 270 | f., fo., form |