---
title: "Search animals."
method: GET
path: "/animals"
tags: ["Catalogue"]
---

# Search animals.

`GET /animals`

## Request

- Base URL: `https://animalchecklist.com/api/v1`
- URL: `https://animalchecklist.com/api/v1/animals`
- Auth: none required

Searches the catalogue and answers one page of animals, ranked by iNaturalist observation count. `q` matches common names in all eight languages, the scientific name and category words; it is a prefix match, ignores diacritics and falls back to a substring match from three characters. Pass `ids` to read up to 500 known animals in one request; the answer is then a plain array.

## Query parameters

- `q` string
- `ids` string
- `category` 'mammals' | 'birds' | 'reptiles' | 'amphibians' | 'fish' | 'insects' | 'other'
- `habitat` 'forest' | 'grassland' | 'freshwater' | 'sea' | 'mountains' | 'urban' | 'farm' | 'zoo' | 'savanna' | 'jungle' | 'arctic' | 'desert'
- `country` string
- `page` integer
- `per` integer
- `lang` 'en' | 'de' | 'es' | 'fr' | 'it' | 'nl' | 'pt' | 'pl': Display language of `name`, category labels and the summary. Falls back to `en`.

## Response `200`

One page of animals. Cached 5 minutes.

- object
  - `data` object, required
    - `items` AnimalSummary[], required
      - `id` string, required: Slug of the animal taxon, for example `red-fox`.
      - `name` string, required: Name in the requested language, English when none exists.
      - `nameEn` string, required: English common name.
      - `nameSci` string, required: Scientific name.
      - `taxonRank` string: Taxonomic rank. Legacy records default to species.
      - `parentNameSci` string, nullable: Parent species scientific name for a subspecies. Null for species.
      - `categoryId` 'mammals' | 'birds' | 'reptiles' | 'amphibians' | 'fish' | 'insects' | 'other', required
      - `habitats` string[], required
      - `tickable` boolean: Whether a new checklist sighting is allowed.
      - `sourceUrl` string, uri
      - `image` object, nullable, required
        - `url` string, uri, required
    - `total` integer, required: Species that match the filters.
    - `page` integer, required
    - `per` integer, required
    - `byDescription` boolean: Present and true when no name matched `q` and the animals were found by a description of colour, size, markings or body form.

## Other responses

- `400`: Invalid input.
- `404`: Not found.
- `429`: Rate limited.
- `500`: Unexpected error.

---

[API](https://skmtc.dev/animalchecklist/apis/animal-checklist-api.md) · [All operations](https://skmtc.dev/animalchecklist/apis/animal-checklist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/animalchecklist/apis/animal-checklist-api/revisions/0910760ad25b?raw)