Insect.id is a machine learning-based service to identify beetles, spiders, centipedes, butterflies, ants, bees and other insect-like animals from images. To use the API you need to get an API key.
\nTo use API from python, use SDK: kindwise API client.
\nThis is a description of an important part of the API. The specification of the endpoints is given below. In the right column, you can find example calls of these endpoints (on the right you can toggle between different examples).
\nYou can also open this documentation directly on postman, where you can see endpoints and examples, and you can also try it out (after providing your API key).
\nMore implementation examples can be found here.
\nHere is openAPI definition of this api.
\nYou should provide the Api-Key header with your API key. You can request it here.
There are two methods to create a new identification:
\nusing application/json request - all attributes including images are encoded in json body - see the example
using multipart/form-data request - attributes are sent in text fields; images are sent as files - see the example
Attributes:
\nimages
application/json: a list of strings (required) with one or more images of the insect you want to identify of either:
image(s) encoded as strings in Base64,
\npublic URL(s) of images
\nmultipart/form-data - all images in file fields (names of file fields are not important)
latitude - float (optional) - geographic coordinate, increases the identification accuracy
longitude - float (optional) - geographic coordinate, increases the identification accuracy
similar_images - boolean (optional) - if true, the model also selects images similar to the provided images for each suggestion
custom_id - int (optional) - unique identifier, can be used to access the identification results
datetime - str (optional) - to improve results, e.g. for images taken at different seasons, specify the date when the images were taken in ISO format with variable precision (e.g. 2023-06-22 for days or 2023-06-22T11:28 for minutes)
suggestion_filter - dict (optional) in format {\"classification\": \"FILTER_NAME (filter examples below)\"} - restricts the output of the model to specified list of classes (based on taxonomy) and adjusts the probabilities. The lists can be combined with logical operators and parentheses. The lists are available here. Examples:
Butterflies and moths - {\"classification\": \"lepidoptera\"}
Arachnids and beetles - {\"classification\": \"arachnida OR coleoptera\"}
Here we comment on important parts of the result. For a complete example of the results see the response examples below.
\naccess_token - a unique identifier of the identification, can be used to access the identification results
result->classification->suggestions - predictions of the model containing taxa (order, family, genus or species) suggestions and additional information; each suggestion consists of:
id - the id of the suggested taxon, which doesn't change over time
name - the name of the taxon in our database (this name can change over time)
probability - the level of certainty that suggested taxon is the one in the image
similar_images - if similar_images=true is in request - list of representative images of the identified taxon carefully selected by the model to resemble the input image; the images may also contain license data that should be cited when using the image
details - additional info you requested, see below
result->is_insect - prediction of the model about presence of an insect in the input images
binary - if false images probably do not contain an insect
treshold - treshold used for the binary result
probability - probability that images contain an insect - you can apply your own threshold
There is a list of additional information about insect that you can get in identification result. To get specific information, include the detail's name in the GET parameters.
\nThe default language is English; to get details in a different language include the language parameter in the GET parameters. ISO 639 two-letter language codes are used, except for Chinese where zh is Simplified Chinese and zh-hant is Traditional Chinese.
Some details are licensed. If you want to use this detail, you should also cite the source.
\nSome details are not available for all entities, if unavailable, null is returned.
⚠️ We are not liable for damages or injury caused by actions based on inaccurate, misleading, incomplete or wrong information provided.
\nThis is a basic description of the available details. To see examples of return values and their exact format, see this example with all details for a single language or this example with multiple languages.
\ncommon_names - list of strings - localized - local, non-scientific name
url - string - localized - link to insect profile page (usually Wikipedia); if localized page not available, an English one is provided
description - string - localized, with license - short description from Wikipedia
**description_gpt**- string - localized - short description from GPT
**description_all**- string - localized, some with license - short description, combined Wikipedia and GPT. Read more.
taxonomy - dict - scientific taxonomy
rank - string - taxonomic rank
gbif_id - int - id in GBIF database
inaturalist_id - int - id in iNaturalist database
image - string - with licence - url of representative image
images - list - with licences - list of more urls of representative images
red_list - string - conservation status and extinction risk from IUCN Red List of Threatened Species
synonyms - list of strings - other names of the insect
danger - list of strings - tags suggesting the danger of the insect, possible values:
harmless to human health
bites or stings
bites pets
disease transmission
rash or skin irritation
allergenic
non-venomous
mildly venomous
highly venomous
danger_description - string - short description of the danger of the insect
role - list of strings - tags suggesting the role of the insect in the environment and its interaction with humans, possible values:
beneficial
pollinator
agriculture or garden pest
household pest
wood destroying
Send images for identification. See above for description of response and request body.
\n","auth":{"type":"apikey","apikey":{"value":"your_api_key","key":"comma separetad list of requested insect details (optional)\nsee detail description above
\n","type":"text/plain"},"key":"details","value":"common_names,url,description,image"},{"disabled":true,"description":{"content":"two-letter ISO 639-1 language code (optional, default en) - language of localized insect details can be multiple (up to 3), separated by comma - i.e. (en,de,sv)
boolean (optional) - if true: request does not wait for identification to complete and response does not contain result section; result can be later retrieved by next endpoint
Can be used to
\nretrieve identification result when identification is created with async=True
retrieve past identifications (available for 6 months)
\nretrieve identification results with different details or languages
\ncomma separetad list of requested insect details (optional)\nsee detail description above
\n","type":"text/plain"},"key":"details","value":"common_names,url,description,image"},{"disabled":true,"description":{"content":"two-letter ISO 639-1 language code (optional, default en) - language of localized insect details can be multiple (up to 3), separated by comma - i.e. (en,de,sv)
access_token retrieved on identification creation (or provided custom_id)
access_token retrieved on identification creation (or provided custom_id)
Can be used to get API key statistics. To:
\nactive)credit_limits for day, week, month or total)used by your API keycan_use_credits => hasn't reached the limit and has enough credits left)remaining credits of your API keyCan be used to send a user feedback to an identification.
\nSpecifics:
\nrating - a number from 0-5 or comment - a text comment from the user. Or include bothFeedback can help us improve our model, so thank you for sending it.
\n","auth":{"type":"apikey","apikey":{"value":"your_api_key","key":"access_token retrieved on identification creation (or provided custom_id)
This endpoint is alpha beta testing and can change!
\nSearch insect knowledge base by query. Entities are searchable by scientific names, common names (in specified language), synonyms.
\nEntity name and query are always matched from the start of a word., i.e. \"Lucanus cervus\" is searchable by \"lucanus\", \"lucanu\", \"cervus\", \"cervu\", \"lucanus cervu\"...
\n","auth":{"type":"apikey","apikey":{"value":"your_api_key","key":"int (optional) - maximum of returned result, max. 20, default 10
\n","type":"text/plain"},"key":"limit","value":"10"},{"disabled":true,"description":{"content":"two-letter ISO 639-1 language code (optional, default en) - language of common names\ncan be multiple (up to 3), separated by comma - i.e. (en,de,sv)
bool (optional) - add for each result 64x64 thumbnail encoded as base64 image
\n","type":"text/plain"},"key":"thumbnails","value":"true"}],"variable":[]}},"response":[{"id":"dea68880-aadb-4efe-bac6-e9b40201db26","name":"Basic","originalRequest":{"method":"GET","header":[{"key":"Api-Key","value":"your_api_key"},{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://insect.kindwise.com/api/v1/kb/insect/name_search?q=lucanus","host":["https://insect.kindwise.com"],"path":["api","v1","kb","insect","name_search"],"query":[{"key":"q","value":"lucanus"},{"key":"limit","value":"10","description":"int (optional) - maximum of returned result, max. 20, default 10","disabled":true},{"key":"language","value":"en","description":"two-letter [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (optional, default `en`) - language of common names\ncan be multiple (up to 3), separated by comma - i.e. (`en,de,sv`)","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 31 Jan 2024 10:57:20 GMT"},{"key":"Server","value":"WSGIServer/0.2 CPython/3.10.13"},{"key":"Content-Type","value":"application/json"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Length","value":"1730"},{"key":"Vary","value":"origin"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"unsafe-none"}],"cookie":[],"responseTime":null,"body":"{\n \"entities\": [\n {\n \"matched_in\": \"Lucanus cervus\",\n \"matched_in_type\": \"entity_name\",\n \"access_token\": \"RXJVMyhOWGtDdC1JUjQQcXpJcElRYi5Ld0JWb2FWLE4-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Lucanus cervus\"\n },\n {\n \"matched_in\": \"Lucanus chrysomelinus\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"QnIBMypODWsRdCtJBDRDcS1JfElWYn5LcUIJb29WLU4-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Ceruchus chrysomelinus\"\n },\n {\n \"matched_in\": \"Lucanus rufipes\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"F3JSM39OCmtNdC9JBTRHcXlJe0kEYn5LckINb2dWK04-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Platycerus caraboides\"\n },\n {\n \"matched_in\": \"Lucanus inclinatus\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"QXJVMy9OXmsVdH9JBDRAcShJeEkAYipLd0JebzdWe04-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Prosopocoilus inclinatus\"\n },\n {\n \"matched_in\": \"Lucanus tenebrioides\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"RXJXM3pOXmtEdH5JVjRHcXpJeElTYi5LJEIKb25WL04-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Sinodendron cylindricum\"\n },\n {\n \"matched_in\": \"Lucanus aeneus\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"SnIFM35OW2sVdHlJBDRDcX5JL0lTYi5LJEJbb2BWKk4-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Lamprima aurata\"\n },\n {\n \"matched_in\": \"Lucanus caprea\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"E3IFMyhOD2tGdH1JUTRDcX9JekkGYilLdkJdbzJWfU4-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Platycerus caprea\"\n },\n {\n \"matched_in\": \"Lucanus capra\",\n \"matched_in_type\": \"synonym\",\n \"access_token\": \"EHJRMytOCGtFdCtJVTQScXFJKElbYihLIUIKb2RWeE4-\",\n \"match_position\": 0,\n \"match_length\": 7,\n \"entity_name\": \"Dorcus parallelipipedus\"\n }\n ],\n \"entities_trimmed\": false,\n \"limit\": 10\n}"}],"_postman_id":"bb0edb3d-b993-4dbf-9571-f1322ea6d430"},{"name":"Insect detail","id":"a1787369-e955-48db-8711-06d225472de9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://insect.kindwise.com/api/v1/kb/insect/:access_token?details=common_names,url,description,image","description":"This endpoint is alpha beta testing and can change!
\nGet entity details based on access token from Insect search endpoint.
\nOne call cost 0.5 credits.
\n","auth":{"type":"apikey","apikey":{"value":"your_api_key","key":"comma separetad list of requested plant details (required)\nsee detail description above
\n","type":"text/plain"},"key":"details","value":"common_names,url,description,image"},{"disabled":true,"description":{"content":"two-letter ISO 639-1 language code (optional, default en) - language of localized plant details \ncan be multiple (up to 3), separated by comma - i.e. (en,de,sv)