Adoptable Pets Feed Format for NC Shelters

The basics

One JSON file in UTF-8 at a fixed address, for example https://yourshelter.org/adoptable-pets.json, replaced at least once a day.
It lists every pet available for adoption right now. A pet that is adopted or no longer available simply drops off the next file.
No login, key or cookie needed to read it. Anyone can read it, so leave out anything private, such as finder or owner details.
Our combined copy, at /adopt/feed.json, holds one of these per shelter in a list called shelters.

The file

Field	Type	Required	What it holds
`format`	text	Yes	Always "ncpet-adoptable-pets".
`version`	text	Yes	"1.0" for this version.
`shelter`	object	Yes	Who publishes the list (fields below).
`updated_at`	date and time	Yes	When the file was made, ISO 8601 with a time zone, for example 2026-10-16T05:30:00-04:00.
`animals`	list	Yes	Every pet available for adoption right now, including pets in foster homes. An empty list means no pets, not an error.

The shelter

Field	Type	Required	What it holds
`name`	text	Yes	The shelter or rescue name people know.
`county`	text	Yes	The North Carolina county it serves, without the word County, for example Wake.
`adopt_url`	web address	Yes	The page that explains how to adopt.
`phone`	text	No	A phone number for adoption questions.

Each pet

Field	Type	Required	What it holds
`id`	text	Yes	Your own ID for the pet. It stays the same while the pet is listed.
`name`	text	Yes	The pet's name.
`species`	text	Yes	"Dog", "Cat" or "Other".
`breed`	text or null	No	Main breed, as you list it.
`breeds`	list of text	No	Every breed you list, main breed first.
`sex`	text or null	No	"Male" or "Female".
`age_text`	text or null	No	Age as you would say it, for example "2 years" or "8 weeks".
`age_group`	text or null	No	"Baby" (under 1 year), "Young" (1 to 3 years), "Adult" (3 to 8 years) or "Senior" (8 years and up).
`age_days`	number or null	No	Approximate age in days, for sorting.
`weight_lbs`	number or null	No	Weight in pounds.
`size`	text or null	No	"Small", "Medium", "Large" or "Extra large".
`location`	text or null	No	"Shelter" or "Foster".
`pending`	true or false	Yes	true once someone has started adopting this pet.
`hold`	true or false	No	true while the pet is on a stray hold and cannot be adopted yet. Leave it out, or use false, for pets ready to adopt. Tools that show adoptable pets can hide pets with hold set to true.
`listed_since`	date or null	No	The day the pet came in or became available, as YYYY-MM-DD.
`photo_url`	web address or null	No	One photo, at least 400 pixels on its short side.
`url`	web address	Yes	The pet's own page on your site, where people start the adoption.

Our combined copy

Field	Type	Required	What it holds
`format`	text	Yes	Always "ncpet-adoptable-pets".
`version`	text	Yes	"1.0" for this version.
`spec`	web address	Yes	This page.
`generated_at`	date and time	Yes	When we made the combined file, ISO 8601 in UTC.
`shelters`	list	Yes	One entry per shelter, each with shelter, updated_at, ok and animals.
`shelters[].updated_at`	date and time or null	Yes	When we last read that shelter's list successfully. null means we have not read it yet, and its animals list is empty.
`shelters[].ok`	true or false	Yes	false when our latest read of that shelter did not go through. Its animals are then from the last good read, dated by updated_at.

Example

{
  "format": "ncpet-adoptable-pets",
  "version": "1.0",
  "shelter": {
    "name": "Example County Animal Services",
    "county": "Wake",
    "adopt_url": "https://example.org/adopt",
    "phone": "919-555-0100"
  },
  "updated_at": "2026-10-16T05:30:00-04:00",
  "animals": [
    {
      "id": "A123456",
      "name": "Biscuit",
      "species": "Dog",
      "breed": "Labrador Retriever",
      "breeds": [
        "Labrador Retriever",
        "Hound"
      ],
      "sex": "Female",
      "age_text": "2 years",
      "age_group": "Young",
      "age_days": 730,
      "weight_lbs": 48,
      "size": "Medium",
      "location": "Foster",
      "pending": false,
      "listed_since": "2026-09-30",
      "photo_url": "https://example.org/photos/A123456.jpg",
      "url": "https://example.org/adopt/A123456"
    }
  ]
}

Send us your feed

Email the address of your file to info@ncpetproject.org. We read it once a day and link every pet back to your own page.