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