Detect Urban
1 credit / requestPOST /v1/detect-urbanAnalyze one urban or human-modified image and return bounding boxes, labels, and taxonomy details.
Processing images regularly or at large scale?
Use this synchronous endpoint for first tests, debugging, and small workflows. For steady pipelines, larger files, or bursty camera-fleet uploads, approved customers can use Async Image Processing.
Open Async Image ProcessingExamples
const form = new FormData()
form.append('image', imageFile)
form.append('country', 'USA')
form.append('threshold', '0.2')
form.append('classify', 'true')
form.append('smooth_herd', 'true')
form.append('latitude', '56.834')
form.append('longitude', '9.994')
form.append('metadata', 'true')
const response = await fetch('https://api.animaldetect.com/v1/detect-urban', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await response.json(){
"id": "c2f3d6ca-8390-49d4-b103-cc82975a5d48",
"expires_at": "2026-03-12T09:44:20.954Z",
"annotations": [
{
"id": 0,
"bbox": [0.12, 0.24, 0.31, 0.44],
"score": 0.98,
"label": "red fox",
"taxonomy": {
"id": "species-id",
"class": "mammalia",
"order": "carnivora",
"family": "canidae",
"genus": "vulpes",
"species": "vulpes vulpes"
}
}
],
"metadata": {
"image_width": 4000,
"image_height": 3000,
"file_size": 2456789
},
"info": {
"processing_time_ms": 812,
"model_version": "mdv5-speciesnet",
"model_id": "mdv5-speciesnet",
"country_processed": "USA",
"threshold_applied": 0.2
}
}Parameters
Required
Image data. Upload request body limit is 20MB; raw image budget is 10MB.
Optional
Optional geofencing hint (CCA2/CCA3/full country name).
Confidence threshold between 0.01 and 0.99. Default: 0.2.
Default: `true`. Set to `false` for detector-only `animal`, `human`, or `vehicle` labels.
When `true`, herd animals can use a precise label already found in the same image. Experimental: Denmark only.
Optional. Used only when `longitude` and `country` are also present. Adds area-level geofencing inside the country.
Optional. Used only when `latitude` and `country` are also present. Adds area-level geofencing inside the country.
Set to `true` to include available image metadata in the response.
Positive integer (1-10). With `classify=true`, returns alternative species candidates on each annotation.
Request Notes
Send multipart/form-data for files or JSON with a base64 image. Use `classify=false` for faster coarse labels. Send `latitude` and `longitude` together; they only apply when `country` is also present. Limits: 20MB request body and 10MB raw image.
Status Codes
Notes
- Best for: urban, indoor, roadside, zoo, farm, and other human-modified scenes.
- Use `classify=false` for faster blank filtering. Labels become coarse: `animal`, `human`, or `vehicle`.
- `smooth_herd=true` can replace broad herd labels such as `mammal` with a precise species already present in the image. Experimental: Denmark only.
- `latitude` and `longitude` require each other and `country`. Without all three, area-level geofencing has no effect.
- `metadata=true` includes metadata only for fields found in the source image.
- `top_candidate` with `classify=true` can add ranked alternative species to each annotation.
- Use `/detect` for classical camera-trap imagery.