オープンフォーマット · CC0

Open adoptable-pet format 0.1.0

このページは英語です。英語の本文が適用されます。

One small, plain record for one pet that is waiting for a home: what it is, who has it, and where to meet it. Free to use (CC0) by any shelter system, portal, website or AI assistant.

Principles

One record

A JSON object per pet. Required: id, source, name, species, breeds, good_with, photos, listing_url, rescue (the organisation: name, place, how to adopt) and the rights block below. Everything else is optional or null: age, sex, size, colour, temperament flags, fee, summary, listing and update dates, coordinates, Wikidata ids. Unknown fields are not allowed in version 0.1.0, so a typo is an error, not silence.

Photos

photos is a list. Each has small (for cards and lists), large (for one pet's page) and original (the source's own address). When we cut the photo ourselves, small is a 4:3 card and large the whole photo, never cropped. A photo we cut ourselves may also carry focus and focus_small: where to aim a crop of large and of small, the pet's head when it was found, else the photo's focal point. Each is { "x": 0.52, "y": 0.31 }, fractions of the image's width and height from its top-left corner, so a square, portrait or arch frame keeps the face: in CSS, object-position: 52% 31% (x and y as percentages) always keeps that point inside the frame. No focus means none was found; centre the crop. A photo that was small at the source may carry "enhanced": true: we cleaned up its compression speckle and enlarged it before cutting. Show it labelled "Enhanced", with original one tap away.

The rights block

Every record says where it came from and what may be done with it, so a copy never loses its licence:

Where each of our sources stands today: /sources.

Versions

The version is MAJOR.MINOR.PATCH and every API response carries it as schema_version (each line of the bulk file does too). A patch changes wording only; a minor version adds optional fields; a major version may break readers and gets a new address (pet.v2.json); the old one stays up. Version 0.1.0 is a draft: expect minor versions before 1.0.

Machine-readable

Following the changes

For a mirror or an app that keeps its own copy. Download the bulk file once, then follow GET /api/v1/changes:

  1. First contact. /api/v1/changes?since=2026-10-07T00:00:00Z (an ISO date or time within the last 30 days; read to the minute).
  2. Every call after that. /api/v1/changes?cursor=<next>, where next is from the last answer. Never build a time yourself.

The answer is { "schema_version", "changes": [{ "id", "op" }], "next", "has_more", "limit" }. op is added, updated (fetch the pet) or removed (drop it; this includes a listing taken down on request). A page holds up to limit changes (default 1000, at most 5000). While has_more is true, ask again at once with the new next; when it is false you are up to date, and next is where to resume, in a few minutes or tomorrow.

Name

"Open adoptable-pet format" is a working name; a final name will replace it and the addresses above will keep redirecting.

Publish yours

Run a shelter system or a rescue website? Serve your adoptable pets as an array of these records at any URL and tell us where: we'll read it daily, show it in assistants with your name and link, and remove anything you ask within one business day. hello@petnecto.com