Identify

Updated: 28-6-2023

Description

Provides species identification implementations based on images

Endpoint

/v2/observation/identify

Method

POST

Parameters

Required

See Required form parameter for details.

image

binary image data.

Optional

See Optional form parameters for details.

location_coordinates

Lat/long coordinates of the current location in degrees, separated by ,. If the parameter is given, the ā€œlocation_confidenceā€, calculated from the modelā€™s geography limits, is returned in the response.

autozoom_enabled

0 (default) or 1.

taxon_namespace

Map and filter output using a specific taxon namespace. Valid values depend on the model.

force_submodel

Compute predictions for a specific submodel only.

Response (successful)

HTTP Code: 200

JSON-structure, containing the following elements:

  • identification
    • image
      • confidence
    • location
      • confidence
    • links
      • taxa
        • url
      • taxa_with_filter
        • url
    • media
      • filename
      • id
    • predictions
      • taxa
        • (list of “prediction”)
      • taxa_hierarchy_full
        • (tree of “prediction”)
      • taxa_hierarchy_simplified
        • (tree of “prediction”)
    • region_groups
      • list of “region group”
JSON field data-type values description
identification.image.confidence string - confident: the most likely prediction has a probability in range (0.9, 1.0].
- uncertain: the most likely prediction has a probability in range (0.2, 0.9].
- unknown: the most likely prediction has a probability in range [0, 0.2]		 indicates in words the confidence of the image based species identification
identification.location.confidence float 0 or 1 1 if location falls into the specified polygon for this model, 0 otherwise
predictions[p_] object prediction json prediction
predictions[p_].region_group_id string valid region group ID reference to region group
predictions[p_].taxa.type object one of {‘multiclass’, ‘multilabel’} type of taxon prediction
predictions[p_].taxa.items[t_] object taxon json predicted taxon
predictions[p_].taxa.items[t_].scientific_name string taxon name name of predicted taxon
predictions[p_].taxa.items[t_].scientific_name_id string taxon ID reference to taxon ID
predictions[p_].taxa.items[t_].probability float [0.0, 1.0] probability of taxon
predictions[p_].taxa_hierarchy_full object full hierarchical taxa json hierarchical form of the prediction
predictions[p_].taxa_hierarchy_full.type string ‘hierarchical’ hierarchical form of the prediction
predictions[p_].taxa_hierarchy_full.items[t_].items[t2_]… object taxon json the nesting can be arbitrarily deep
predictions[p_].taxa_hierarchy_simplified object simplified hierarchical taxa json hierarchical form of the prediction
predictions[p_].taxa_hierarchy_simplified.type string ‘hierarchical’ hierarchical form of the prediction
region_groups[rg_] object region group json region group describing a set of regions point to the same organism, can be in multiple images
region_groups[rg_].id string region group ID -
region_groups[rg_].individual_id string ID of individual organism used for multipart classification, tracking, etc where one organism is represented by multiple organisms
region_groups[rg_].regions[rg_r_] object region json
region_groups[rg_].regions[rg_r_].id string ID of region -
region_groups[rg_].regions[rg_r_].media_id string valid media ID -
region_groups[rg_].regions[rg_r_].box object box json -
region_groups[rg_].regions[rg_r_].box.x1 int [0.0, 1.0] normalized left coordinate
region_groups[rg_].regions[rg_r_].box.x2 int [0.0, 1.0] normalized right coordinate
region_groups[rg_].regions[rg_r_].box.y1 int [0.0, 1.0] normalized top coordinate
region_groups[rg_].regions[rg_r_].box.y2 int [0.0, 1.0] normalized bottom coordinate
links.taxa.url string valid URL
endpoints.taxa_with_filter.url string valid URL points to the endpoint for retrieving the taxa based on a filter

Response (error)

HTTP code: 400 - Did not receive any files

 {
   "error": {
     "code": "received_no_files",
     "message": "Did not receive any files"
   }
 }

HTTP code: 405 - Method not allowed (only supports POST)

 {
   "error": {
     "code": "method_not_allowed",
     "message": "Method not allowed (only supports POST)"
   }
 }

HTTP code: 415 - Unsupported media type

 {
   "error": {
     "code": "unsupported_media_type",
     "message": "Unsupported media type"
   }
 }

HTTP code: 429 - Too Many Requests: 10 per 1 day

 {
   "error": {
     "code": "too_many_requests",
     "message": "Too Many Requests: 10 per 1 day"
   }
 }

HTTP code: 500 - General server error

 {
   "error": {
     "code": "general_server_error",
     "message": "General server error"
   }
 }

Example request

Get test image Get test image

​
 curl \
     -X POST \
     -F "image=@27127725.jpg" \
     -F "image=@27127726.jpg" \
     -F "location_coordinates=52.16507, 4.47371" \
     -F "autozoom_enabled=1" \
     -F "taxon_namespace=NIA" \
     "https://multi-source.identify.biodiversityanalysis.eu/v2/observation/identify" | \
 jq

Requires curl and jq to be installed.

 import json
 
 import requests
 
 
 def example_request():
     url = (
         "https://multi-source.identify."
         "biodiversityanalysis.eu/v2/"
         "observation/identify"
     )
     test_image_1 = "27127725.jpg"
     test_image_2 = "27127726.jpg"
 
     data = {
         "location_coordinates": "52.16507, 4.47371",
         "autozoom_enabled": "1",
         "taxon_namespace": "NIA",
     }
 
     with open(test_image_1, "rb") as image_1:
         with open(test_image_2, "rb") as image_2:
             response = requests.post(
                 url=url,
                 files=(
                     ("image", image_1),
                     ("image", image_2),
                 ),
                 data=data,
             )
     return response.json()
 
 
 if __name__ == "__main__":
     json_response = example_request()
     print(json.dumps(json_response, indent=2))

Requires the Python requests library. Available with pip install requests.

Example response

 {
   "api_implementation": {
     "tag": "api-v2:2.1.0-20230616",
     "version": "49476035"
   },
   "generated_by": {
     "datetime": "2023-06-26T09:55:30.010063",
     "parameters": {},
     "tag": "algorithm=msm-eur:1.1-20230619,api=api-v2:2.1.0-20230616",
     "version": "algorithm=df722733dc3eb9647870d237c918cecd0d8aabeb,api=49476035"
   },
   "identification": {
     "image": {
       "confidence": "confident"
     },
     "location": {
       "confidence": 1
     }
   },
   "links": {
     "taxa": {
       "url": "v2/taxa/main_order"
     },
     "taxa_with_filter": {
       "url": "v2/taxa/main_order?id={taxon_id}"
     }
   },
   "media": [
     {
       "filename": "27127725",
       "id": "image0"
     },
     {
       "filename": "27127726",
       "id": "image1"
     }
   ],
   "model_implementation": {
     "algorithm_tag": "msm-eur:1.1-20230619",
     "tag": "main_order",
     "version": "df722733dc3eb9647870d237c918cecd0d8aabeb"
   },
   "predictions": [
     {
       "region_group_id": "individual0",
       "taxa": {
         "items": [
           {
             "probability": 0.995506,
             "scientific_name": "Rorippa austriaca",
             "scientific_name_id": "GBIF:3053406"
           },
           {
             "probability": 0.002862,
             "scientific_name": "Bunias orientalis",
             "scientific_name_id": "GBIF:3050364"
           },
           {
             "probability": 0.001321,
             "scientific_name": "Rorippa armoracioides",
             "scientific_name_id": "GBIF:3693306"
           },
           {
             "probability": 0.000171,
             "scientific_name": "Rorippa amphibia",
             "scientific_name_id": "GBIF:3053201"
           },
           {
             "probability": 6.3e-5,
             "scientific_name": "Lepidium latifolium",
             "scientific_name_id": "GBIF:5376692"
           },
           {
             "probability": 4.1e-5,
             "scientific_name": "Armoracia rusticana",
             "scientific_name_id": "GBIF:3041022"
           },
           {
             "probability": 6e-6,
             "scientific_name": "Brassica nigra",
             "scientific_name_id": "GBIF:3042658"
           },
           {
             "probability": 4e-6,
             "scientific_name": "Brassica juncea",
             "scientific_name_id": "GBIF:3042751"
           },
           {
             "probability": 4e-6,
             "scientific_name": "Sisymbrium austriacum subsp. chrysanthum",
             "scientific_name_id": "GBIF:3046925"
           },
           {
             "probability": 3e-6,
             "scientific_name": "Rorippa",
             "scientific_name_id": "GBIF:3053118"
           }
         ],
         "type": "multiclass"
       }
     }
   ],
   "region_groups": [
     {
       "id": "individual0",
       "individual_id": "individual0",
       "regions": [
         {
           "box": {
             "x1": 0,
             "x2": 1,
             "y1": 0.125,
             "y2": 0.875
           },
           "id": "image0?region=full",
           "media_id": "image0"
         },
         {
           "box": {
             "x1": 0,
             "x2": 1,
             "y1": 0.125,
             "y2": 0.875
           },
           "id": "image1?region=full",
           "media_id": "image1"
         }
       ]
     }
   ]
 }

Full hierarchical example response

 {
   "children": [
     {
       "scientific_name": "Plantae",
       "scientific_name_id": "NIA:c98b57523dc855b803fa728c667be05e35dabebe8499f1c8f07d1efe",
       "probability": 0.9993,
       "children": [
         {
           "scientific_name": "Tracheophyta",
           "scientific_name_id": "APSE:6000506",
           "probability": 0.9993,
           "children": [
             {
               "scientific_name": "Magnoliopsida",
               "scientific_name_id": "APSE:4000140",
               "probability": 0.9993,
               "children": [
                 {
                   "scientific_name": "Rosales",
                   "scientific_name_id": "GBIF:691",
                   "probability": 0.9993,
                   "children": [
                     {
                       "scientific_name": "Rosaceae",
                       "scientific_name_id": "APSE:2002762",
                       "probability": 0.9993,
                       "children": [
                         {
                           "scientific_name": "Geum",
                           "scientific_name_id": "APSE:1006244",
                           "probability": 0.9993,
                           "children": [
                             {
                               "scientific_name": "Geum aleppicum",
                               "scientific_name_id": "APSE:221490",
                               "probability": 0.9954,
                               "children": []
                             },
                             {
                               "scientific_name": "Geum macrophyllum",
                               "scientific_name_id": "APSE:223036",
                               "probability": 0.0039,
                               "children": []
                             }
                           ]
                         }
                       ]
                     }
                   ]
                 }
               ]
             }
           ]
         }
       ]
     }
   ]
 }

Simplified hierarchical (display suggestion) example response

 {
   "children": [
     {
       "scientific_name": "Geum aleppicum",
       "scientific_name_id": "APSE:221490",
       "probability": 0.9954,
       "children": []
     },
     {
       "scientific_name": "Geum macrophyllum",
       "scientific_name_id": "APSE:223036",
       "probability": 0.0039,
       "children": []
     }
   ]
 }