Random animal API and catalog download

Random animal API

One endpoint. No key and no sign-up. CORS is open, so a web page can call it directly. It draws with the same method as the generator, so a batch never holds the same animal twice.

GET https://animalrandomizer.com/api/random

Parameters

No repeats across calls

The API keeps nothing between calls. To avoid a repeat, send every id you have drawn so far in exclude. When no eligible animal is left, exhausted is true and animals is empty.

// Three batches of 5, and no animal twice.
const seen = [];
for (let i = 0; i < 3; i++) {
  const q = new URLSearchParams({ count: "5" });
  if (seen.length) q.set("exclude", seen.join(","));
  const res = await fetch(`https://animalrandomizer.com/api/random?${q}`);
  const data = await res.json();
  seen.push(...data.animals.map((a) => a.id));
  console.log(data.animals.map((a) => a.name));
}

Examples

curl "https://animalrandomizer.com/api/random?count=3&group=bird"

const res = await fetch("https://animalrandomizer.com/api/random?count=3");
const data = await res.json();
console.log(data.animals.map((a) => a.name));

import requests

data = requests.get("https://animalrandomizer.com/api/random", params={"count": 3}).json()
print([a["name"] for a in data["animals"]])

Response

This is the reply to ?count=3&group=bird. The shape is exact. The animals change on every call.

{
  "catalog_version": "1.2.1",
  "group": "bird",
  "requested": 3,
  "count": 3,
  "eligible": 89,
  "exhausted": false,
  "animals": [
    {
      "id": "chaffinch",
      "name": "chaffinch",
      "group": "bird"
    },
    {
      "id": "american-robin",
      "name": "American robin",
      "group": "bird"
    },
    {
      "id": "roseate-spoonbill",
      "name": "roseate spoonbill",
      "group": "bird"
    }
  ],
  "license": "CC BY 4.0",
  "attribution": "Animal Randomizer (animalrandomizer.com), catalog v1.2.1, CC BY 4.0",
  "docs": "https://animalrandomizer.com/data"
}

Limits and errors

• Each address may send 30 requests a minute. IPv6 addresses count by their /64 prefix.
• Past that, the reply is 429 with a Retry-After header of 60 seconds.
• A bad parameter returns 400 and a body with error.code, error.param and error.message.
• Replies are never cached. For a large or repeated use, download the catalog below and draw on your own machine.

Download the catalog

Catalog v1.2.1: 448 animals in six groups (Mammals 90, Birds 89, Reptiles 62, Amphibians 46, Fish 71, Invertebrates 90). The files are built from the records the generator draws from, so they cannot differ from all 448 animals.

• /data/animals.csv448 rows: id, name, group, catalog_version.
• /data/animals.jsonThe same animals, with counts by group, the licence and what the group labels were checked against.
• /data/photos.csv12 rows, one for each photograph, with its creator, licence and source.
• /data/photos.jsonThe same photo credits as JSON.

animals.csv, first rows

id,name,group,catalog_version
african-elephant,African elephant,mammal,1.2.1
tiger,tiger,mammal,1.2.1
gray-wolf,gray wolf,mammal,1.2.1
red-fox,red fox,mammal,1.2.1

group is one of mammal, bird, reptile, amphibian, fish, invertebrate. id never changes and is never reused for a different animal.

photos.csv columns

id, name, group, creator, license, license_url, attribution, source_file_page, changes_made, retrieved, image_url, width, height, alt.

Licence

Our catalog data is licensed CC BY 4.0. That covers our compilation: the ids, the names as chosen, the group on each record and the selection of animals. You may use, share and adapt it, including commercially, if you credit us. Use this line and a link to this page:

Animal Randomizer (animalrandomizer.com), catalog v1.2.1, CC BY 4.0

The photographs are not covered by that licence. Each keeps its own, recorded per photograph in the photo files and on the credits page. Of the 12 photographs: 5 under CC BY-SA 3.0, 3 under CC BY-SA 4.0, 1 under CC BY 2.0, 1 under CC BY 4.0, 1 under CC BY-SA 2.0, 1 under Public domain. A ShareAlike licence means an adapted photograph must carry the same licence. The API returns no photographs.

The group labels were checked against Integrated Taxonomic Information System (ITIS) on 2026-09-19, at the level of the six labels and not animal by animal. Names are everyday English, not species identifications. There are no scientific names in these files.

How this was made

Date

30 September 2026. Catalog v1.2.1.

Source

The names are chosen by the maintainer. Group labels were checked against ITIS on 2026-09-19. The 12 photographs are from Wikimedia Commons, retrieved on 2026-09-19, with each licence as the source record stated it.

Method

Each file is written from the same records the generator draws from, at the moment it is requested. The API uses the generator’s own draw, a partial Fisher-Yates shuffle without replacement.

Checks

Automated tests check that the files match the catalog, that every id is unique, that no batch repeats an animal, that exclude is honoured, that a bad parameter is refused, and that the rate limit holds.

Not included

Scientific names, facts and photographs of the other 436 animals. The catalog holds common names only.

Cite this

Animal Randomizer. (2026). Animal Randomizer catalog, version 1.2.1 [Data set]. https://animalrandomizer.com/data

Changelog

• 30 Sep 2026First release: the catalog (448 animals, v1.2.1) and the 12 photo credits as CSV and JSON, and the /api/random endpoint.