Detect Urban
1 credit / requestPOST /api/v1/detect-urbanBest for urban, indoor, roadside, zoo, farm, and other human-modified settings. Use this endpoint to analyze one image and get bounding boxes plus taxonomy-rich labels.
Try in PlaygroundRequired Parameters
image(file | base64 string) Image data. Raw image limit is 10MB.
Optional Parameters
country(string) Optional geofencing hint (CCA2/CCA3/full country name).threshold(number) Confidence threshold between 0.01 and 0.99. Default: 0.2.classify(boolean) Optional. Default: `true`. Set to `false` to skip SpeciesNet and return detector-only `animal`, `human`, or `vehicle` labels.smooth_herd(boolean) Optional. When `true`, similar animals in a herd can inherit the more precise label found in the same image.latitude(number) Optional. Used only when `longitude` and `country` are also present. Adds area-level geofencing inside the country.longitude(number) Optional. Used only when `latitude` and `country` are also present. Adds area-level geofencing inside the country.metadata(boolean) Optional. Set to `true` to include available image metadata in the response.
Supports multipart/form-data (recommended for files) and application/json with base64 image. Set `classify=false` for faster detector-only output. Set `smooth_herd=true` to smooth imprecise herd labels to precise labels seen in the same image. `latitude` and `longitude` must be sent together and only have effect when `country` is also present. Set `metadata=true` to request available image metadata. This Vertex-backed route accepts raw images up to 10MB.
Status Codes
200Detection completed.
400Validation error (bad payload, threshold, or image).
401Invalid, missing, or revoked API key.
402Credit limit exceeded.
413Payload too large for the Vertex-backed request limit.
429Rate limit exceeded.
503Upstream Vertex service error.
- Best for: urban, indoor, roadside, zoo, farm, and other human-modified scenes.
- Set `classify=false` to run detector-only mode for blank filtering. The response still uses `annotations`, but labels are coarse: `animal`, `human`, or `vehicle`.
- `smooth_herd=true` helps herd images by replacing non-precise labels such as `mammal` with a precise species already present in the same image when the model can do so.
- `latitude` and `longitude` require each other and `country`. Without all three, area-level geofencing has no effect.
- When `metadata=true`, the response includes a `metadata` object only for the fields the source image actually contains.
- Returns the same rich annotation shape as `/detect`, but optimized for a different image domain.
Node.js / Express
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://www.animaldetect.com/api/v1/detect-urban', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await response.json()Example 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
}
}