Note: this documentation refers to the 2021 API (since Jan 2021).
A REST-style API existed in 2020 (old documentation). The
original JSON/CSV API (of the form
is no longer functional.
- Endpoint: https://arctos.database.museum/component/api/v1/. Accepts both HTTP GET and POST. Use POST for long query strings
- API key: most API requests must be accompanied by the key-value
api_key=...in the query string. To obtain a key:
- Ask anyone with Arctos
global_adminaccess. They should look under the menus: ‘Manage Arctos -> Developer Tools -> Manage API Keys’
- Or file a request as an Issue at https://github.com/ArctosDB/arctos/issues
- Ask anyone with Arctos
- Services (append these to the endpoint URL above):
about.cfc?method=api_map: Basic info about the API (no API key required)
catalog.cfc?method=about: API usage documentation and list of variables for catalog queries, and fields for requesting in results (no API key required)
authority.cfc?method=code_tables: List code tables. With parameter
tbl=...request contents of a code table (requires API key)
catalog.cfc?method=getCatalogData: Main specimen search (requires API key)
Specimen query terms
- The API uses the same underlying code that
SpecimenResults.cfmuses, so documentation for a search field can be found by clicking on the field name in the standard Arctos Specimen form.
- Search terms are added as key-value pairs using the terms listed in
catalog.cfc?method=about. When two or more search terms are used a logical ‘AND’ is assumed.
- Sets of specimens can be requested via a comma-delimited list of GUIDs.
- Only JSON results are currently available.
- The default fields returned for a specimen search are:
coordinateuncertaintyinmeters. To add additional fields use the
cols=...key-value pair, with field names separated by commas.
- By default, a maximum of 10 records are returned. Sending
pgsz=...can be used to ask for more records (tested up to 20,000). If a page size limit is reached, the results will need to be collected via multiple calls to the API, paging with the
"TotalRecordCount":"..."(in the JSON) is reached. Note that in the original query, a
"tbl":"..."value is returned - this is an identifier for the temporary results set. During pagination, calling
tbl=...&pgsz=...&pg=...will be faster than requesting paginated results via original query parameters.
Single specimen by GUID, with additional columns: https://arctos.database.museum/component/api/v1/catalog.cfc?method=getCatalogData&api_key=...&guid=UAM:Herb:34746&cols=partdetail,phylum Several specimens by GUID: https://arctos.database.museum/component/api/v1/catalog.cfc?method=getCatalogData&api_key=...&guid=UAM:Herb:34746,UAM:Herb:34745 Specimens by name: https://arctos.database.museum/component/api/v1/catalog.cfc?method=getCatalogData&api_key=...&genus=Claytonia&species=arctica
Edit this Documentation
If you see something that needs to be edited in this document, you can create an issue using the link under the search widget at the top left side of this page, or you can edit directly here.