Format ouvert · CC0
Open adoptable-pet format 0.1.0
Cette page est en anglais, et c'est le texte anglais qui s'applique.
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
- The organisation stays in charge. Every record has its own page here and links to the organisation's listing (Taiwan's is the national adoption site); adoption happens with the organisation.
- Unknown is null. Nothing is guessed. "Good with cats: null" means nobody said.
- Open ids. Species and breeds carry Wikidata ids, so a Labrador is the same Labrador in every language and every country.
- Any language. Names and descriptions stay as the organisation wrote them; a
displayblock carries the reader's language. - Stable ids. A source prefix plus the source's own id never changes for the life of the listing.
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:
source: a stable id for where the record came from.data_licence: URL of the licence the data is under.photo_rights:shelter-granted(the shelter lets listing services show the photo; not an open licence),open-licence(the source's open licence covers it),link-out(not ours to show: no photo, onlyphoto_linkto the shelter's page) ornone.attribution:{ "text": ..., "url": ... }, the credit to show.
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
- JSON Schema (2020-12): /schema/pet.v1.json (also at /spec/pet.schema.json)
- Check a feed offline: download petnecto-validate.mjs (one file, sha256) and run
node petnecto-validate.mjs feed.json. Node 20 or newer; nothing to install, no network. It reads a list of records, an API answer or one record per line, and says in a sentence what is wrong and where. Verify the download withcurl -sO https://petnecto.com/tools/petnecto-validate.mjs; curl -s https://petnecto.com/tools/petnecto-validate.mjs.sha256 | sha256sum -c(macOS:shasum -a 256 -c). - Daily bulk file, one record per line, gzip: /data/pets.ndjson.gz (manifest: /data/pets.manifest.json). Only sources whose licence lets us pass the data on are in it; it has an
ETag, so sendIf-None-Match. - What changed: /schema/changes.v1.json describes the answer. See "Following the changes" below.
- Live examples: /api/v1/pets?country=TW®ion=Taipei City
- In assistants: the MCP server at
https://petnecto.com/mcp
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:
- 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). - Every call after that.
/api/v1/changes?cursor=<next>, wherenextis 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.
- Nothing is lost. Every change gets a sequence number when it is written, higher than any before it, and
nextis a position in that sequence. A change written while you are reading, or while our daily sync is still running, has a higher number than your cursor, so the next call returns it. Cap, page size and timing do not matter. - At least once. A first-contact
sinceis read to the minute, so a few changes just before it can come again. Handle anaddedorupdatedpet you already hold by replacing it, and aremovedpet you no longer hold by ignoring it. - Re-listed pets. A pet that left the list and came back is
updated, notadded. - Cursors expire. Removed listings are kept 30 days, so a cursor older than that answers 410: download the bulk file again and start over with
since. A cursor from another site, or made up, answers 400. - Errors. 400 (the message says what is wrong), 410 (expired cursor), 429 with
Retry-After(60 requests a minute per address).
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