Describing the API

All models are also available through a publicly available API which can be publicly reached via:

https://museum.api.biodiversityanalysis.nl/

List of the currently available models:

Model	Description
legacy-vlinders-v2	Butterflies from the papillot collection with south-east asian butterflies specimens.
legacy-vlinder-genera-v2	The butterfly model recognizing images on genera level.
legacy-vlinder-subfamilie-v2	The butterfly model recognizing images on subfamily level.
legacy-conidae-v2	Cone shells.
legacy-maskers-v2	Masks from the museon collection.
legacy-maskers-continent-v2	Masks from the museum collection grouped by continent.
legacy-shark-eggs-v2	Shark and ray eggs.
legacy-bird-eggs-v2	Bird eggs and egg shells (restricted).

Endpoints

And this API has for separate model the following endpoints. In this example the legacy-vlinders-v2 model is used, but you can pick any model from the table above.

Description	Method	Endpoint
Base	GET	/
Ping to check API	GET	/legacy-vlinders-v2/ping
Documentation of model api	GET	/legacy-vlinders-v2/documentation
Listed endpoints	GET	/legacy-vlinders-v2/endpoints
Identify image	POST	/legacy-vlinders-v2/identify
Authenticate	POST	/legacy-vlinders-v2/identify/auth
Identify image using token	POST	/legacy-vlinders-v2/identify/token/{token}
Classess recognized	GET	/legacy-vlinders-v2/taxa
Classess recognized (filter)	GET	/legacy-vlinders-v2/taxa/all?id={taxon_id}

Root endpoint

The front page of the API, containing some basic information.

URL: https://museum.api.biodiversityanalysis.nl/

Returns: Html page about the API.

Note that the contents of this content is currently not up to date. This is one of the issues that will be resolved in the near future.

/ping

To test if a specific model loaded and ready for identification, you can ping the model.

URL: https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/ping

Parameters: none

Methods: GET

Returns: pong

/documentation

To get a json representation of documentation and configuration of a certain model.

URL: https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/documentation

Methods: GET

Returns: json structure

/taxa

Returns an alphabetical list of all classes that a model contains ('recognized').

URL: https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/taxa

Parameters: none

Methods: GET

/identify

Endpoint to identify an image with.

URL: https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/identify

Parameters: image= (multipart/form-data); Methods: POST

Example using cURL:

curl -XPOST -F "image=@butterfly.jpg" \
  https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/identify

The response contains a 'predictions' field, which in turn contains a JSON-encoded list of taxa recognized in the uploaded image. Each prediction consists of a class and the probability that it involves that class (as a fraction of 1). The API always returns the predictions for all classes in the model, ordered descending by probability.

/identify/auth

A number of models are not publicly accessible or restricted. These are identified by the tag 'restricted' in the output of the models endpoint. To use these models, please contact Naturalis. If you have permission to use the corresponding endpoints use, then you should have been given a username and password provided for access. The authorization has been implemented as Basic Authorization. Example implementation using cURL, if you have the username 'my_name' and password 'secret' are given:

curl -u "my_name:secret" \
  https://museum.api.biodiversityanalysis.nl/legacy-bird-eggs-v2/identify/auth

/identify/{token}

Endpoint to identify an image with, using a token supplied by Naturalis. This can also be used for models that have restricted access or limited requests per period.

URL: https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/identify/token/{token}

Parameters: image= (multipart/form-data)

Methods: POST

Example using cURL:

curl -XPOST -F "image=@butterfly.jpg" \
  https://museum.api.biodiversityanalysis.nl/legacy-vlinders-v2/identify/token/{token}