# RescueGroups.org Adoptable Pet Finder by ZIP (`vexaloom-labs/rescuegroups-org-adoptable-pet-finder-by-zip`) Actor

Search RescueGroups.org adoptable dogs, cats, rabbits and more with Petfinder-style filters (species, breed, sex, age, size, ZIP + radius), fetch animals by ID, or browse rescue organizations and their contact details.

- **URL**: https://apify.com/vexaloom-labs/rescuegroups-org-adoptable-pet-finder-by-zip.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Lead generation, Integrations
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## RescueGroups.org Adoptable Pet Finder by ZIP

RescueGroups.org brings together adoptable animals from thousands of shelters and rescues across the United States and Canada. This actor searches that catalogue the way a Petfinder-style site does — **ZIP + radius, species, breed, sex, age, size, and temperament** — then opens each animal's public page for the shelter contact, description, photos and personality flags.

It also looks up specific animals by ID and fetches rescue organizations by ID. **No cookies, login, or API key are required.** An optional free RescueGroups.org API key adds API-only fields and organization name search.

### Modes

| Mode | What it does |
|---|---|
| `search` (default) | Finds adoptable pets by ZIP/radius and the filters below |
| `byAnimalIds` | Fetches the animals whose IDs (or animal-page URLs) you paste |
| `orgSearch` | Fetches rescue organizations by ID; with an optional API key it can also search organizations by name |

### What you get per animal

- **Identity:** `animalId`, `name`, `status`, `species`, `breedPrimary`, `breedSecondary`, `breedString`
- **Profile:** `sex`, `ageGroup`, `sizeGroup`, `sizePotential`, `colors`, `pattern`, `coatLength`
- **Temperament and care:** `isAltered`, `isHousetrained`, `isCurrentVaccinations`, `isMicrochipped`, `isDeclawed`, `isSpecialNeeds`, `isNeedingFoster`, `isCatsOk`, `isDogsOk`, `isKidsOk`, `isAdultsOk`, `isYardRequired`, `isCrateTrained`, `activityLevel`, `energyLevel`, `exerciseNeeds`, `groomingNeeds`, `indoorOutdoor`, `newPeopleReaction`, `obedienceTraining`, `ownerExperience`, `sheddingLevel`, `vocalLevel`
- **Story:** `descriptionText`, `descriptionHtml`, `adoptionArea`
- **Shelter:** `organizationId`, `organizationName`, `organizationAddress`, `organizationCity`, `organizationState`, `organizationPostalCode`, `organizationEmail`, `organizationPhone`, `organizationUrl`
- **Location:** `locationCity`, `locationState`, `distanceMiles` (radius searches)
- **Links and metadata:** `pictures[]`, `pictureThumbnailUrl`, `sourceUrl`, `adoptionUrl`, `recordType`, `scrapedAt`

With an optional API key the records can also include the API-only fields: `searchString`, `rescueId`, `ageString`, `birthDate`, `isBirthDateExact`, `sizeCurrent`, `colorDetails`, `adoptionFeeString`, `distinguishingMarks`, `specialNeedsDetails`, `qualities`, `summary`, `organizationIds`, `locationCountry`, and the full temperament set.

### What you get per organization

`organizationId`, `name`, `about`, `services`, `adoptionProcess`, `adoptionArea`, `address`, `city`, `state`, `postalcode`, `country`, `phone`, `email`, `url`, `facebookUrl`, `donationUrl`, `adoptionUrl`, `isCommonApplicationAccepted`, `sourceUrl`, `recordType`, `scrapedAt`.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search`, `byAnimalIds`, or `orgSearch` |
| `apiKey` | secret | – | Optional free API key; adds API-only fields and org name search |
| `species` | string | `Dog` | Full species list, or `(any species)` |
| `breed` | string | – | Breed name, e.g. `Labrador Retriever` (matches any breed in the animal's breed string) |
| `sex` | string | – | `(any)`, `Male`, `Female` |
| `ageGroup` | string | – | `(any)`, `Baby`, `Young`, `Adult`, `Senior` |
| `sizeGroup` | string | – | `(any)`, `Small`, `Medium`, `Large`, `X-Large` |
| `specialNeedsOnly` | boolean | `false` | Only special-needs animals |
| `goodWithDogsOnly` | boolean | `false` | Only animals flagged good with dogs |
| `goodWithCatsOnly` | boolean | `false` | Only animals flagged good with cats |
| `goodWithKidsOnly` | boolean | `false` | Only animals flagged good with kids |
| `needsFosterOnly` | boolean | `false` | Only animals looking for a foster home |
| `housetrainedOnly` | boolean | `false` | Only house-trained animals |
| `declawedOnly` | boolean | `false` | Only declawed animals |
| `postalCode` | string | – | ZIP/postal code for a radius search; empty searches everywhere |
| `radiusMiles` | integer | `50` | Radius in miles (1–500; requests under 25 use 25, values between buckets round down, and requests above 200 use 200) |
| `includeDetails` | boolean | `true` | Open each animal's detail page (richer, slightly slower) |
| `animalIds` | array | `[]` | Animal IDs or page URLs for `mode=byAnimalIds` |
| `organizationIds` | array | `[]` | Organization IDs for `mode=orgSearch` |
| `orgQuery` | string | – | Organization name (needs the optional key) or a numeric ID / organization-page URL (keyless; legacy inputs supported) |
| `maxItems` | integer | `50` | Hard cap on emitted records (1–2000) |

#### Example: dogs within 25 miles of Boston

```json
{
  "mode": "search",
  "species": "Dog",
  "postalCode": "02108",
  "radiusMiles": 25,
  "maxItems": 50
}
```

#### Example: senior cats, good with kids

```json
{
  "mode": "search",
  "species": "Cat",
  "ageGroup": "Senior",
  "goodWithKidsOnly": true,
  "maxItems": 30
}
```

#### Example: one breed, nationwide

```json
{
  "mode": "search",
  "species": "Dog",
  "breed": "Labrador Retriever",
  "maxItems": 100
}
```

#### Example: look up animals by ID

```json
{
  "mode": "byAnimalIds",
  "animalIds": ["22514067", "22813117"]
}
```

#### Example: fetch a rescue organization

```json
{
  "mode": "orgSearch",
  "organizationIds": ["6260"]
}
```

### How it works

- **Default, credential-free path.** The actor reads the public National Pet Search toolkit pages (`toolkit.rescuegroups.org`), the same pages RescueGroups.org serves to any website visitor. Search pages return 24 animals at a time; the actor paginates until `maxItems` or the result set ends. Each animal's public detail page supplies the profile, shelter contact, description and photos.
- **Optional API path.** Paste a free RescueGroups.org public API key and the actor uses the official v5 JSON:API instead. It returns the same records plus API-only fields and supports organization name search. No key is required for any core mode.
- **Filters are source-side.** Species, breed, sex, age, size, ZIP/radius, special-needs, foster, house-trained, declawed and good-with filters are applied by the source, not discarded afterwards.
- **Pagination is honest.** The actor stops on `maxItems`, source exhaustion, or a short page — it never cuts a run short with a wall-clock timer.
- **Empty values are omitted.** A field the source does not expose for a particular animal is left out, never sent as `null`, `""`, `[]` or a placeholder.

### FAQ

**Do I need an API key?** No. The default path needs no key, account, cookie or proxy. The optional key is free and only adds fields and organization name search.

**Why is the radius rounded?** The public search page offers 25, 50, 100 and 200 mile buckets. The actor picks the closest supported bucket: values between buckets round down, requests under 25 use the 25-mile minimum, and requests above 200 use the 200-mile maximum instead of widening to a nationwide search.

**Why did a breed return nothing?** Breed names are shelter-entered. Use the exact name from the RescueGroups breed list, optionally prefixed with the species (`Dog: Labrador Retriever`).

**Are all adoptable animals included?** The public search lists currently available animals. Most have photos, but a few listings show only a placeholder, so their `pictures` fields are omitted.

**How fresh is the data?** Every run queries the live source.

**Is this affiliated with RescueGroups.org?** No. This is an independent third-party actor using publicly available pages and, optionally, the public API.

### Limitations

- The public search exposes 25/50/100/200-mile radius buckets; the actor rounds down, using 25 for smaller requests and 200 for larger ones.
- Age and size are single-choice filters on the public path (the source's own checkboxes support multiple values).
- Breed matching is exact after case-folding and matches any breed in the animal's breed string (primary or secondary); near-miss spellings return a clear status message instead of wrong results.
- Without an API key, organization lookup works by numeric ID only; organization name search needs the optional key.
- The source is US/Canada focused; most listings have photos, but some have no public photo and omit the picture fields.
- Some animals and organizations omit fields such as size, contact details, address or phone; those fields are absent from the record rather than guessed.

# Actor input Schema

## `mode` (type: `string`):

What to fetch: a pet search, specific animals by ID, or rescue organizations.

## `apiKey` (type: `string`):

Optional free public RescueGroups.org API key. Leave empty to use the cookieless public pet-search pages. A key adds API-only fields (adoption fee, energy level, exact birth date, and more) and organization name search.

## `species` (type: `string`):

Species filter (mode=search). Pick (any species) to search every species.

## `breed` (type: `string`):

Breed name filter (mode=search), e.g. `Labrador Retriever`. The cookieless source matches any breed in the animal's breed string (primary or secondary); with an optional API key the primary breed is matched exactly.

## `sex` (type: `string`):

Sex filter (mode=search).

## `ageGroup` (type: `string`):

General age filter (mode=search).

## `sizeGroup` (type: `string`):

Size filter (mode=search).

## `specialNeedsOnly` (type: `boolean`):

Only animals flagged as having special needs.

## `goodWithDogsOnly` (type: `boolean`):

Only animals flagged as good with dogs.

## `goodWithCatsOnly` (type: `boolean`):

Only animals flagged as good with cats.

## `goodWithKidsOnly` (type: `boolean`):

Only animals flagged as good with kids.

## `needsFosterOnly` (type: `boolean`):

Only animals currently looking for a foster home.

## `housetrainedOnly` (type: `boolean`):

Only animals flagged as house-trained.

## `declawedOnly` (type: `boolean`):

Only animals flagged as declawed.

## `postalCode` (type: `string`):

Center point for a radius search (mode=search). Leave empty to search everywhere.

## `radiusMiles` (type: `integer`):

Search radius around the postal code (mode=search). The source supports 25, 50, 100 and 200 miles; requests under 25 use 25, values between buckets round down, and requests above 200 use 200.

## `includeDetails` (type: `boolean`):

Open each animal's public detail page for shelter contact, description, photos and temperament flags. Turn off for a faster, lighter listing-only run. The optional API path always returns full details.

## `animalIds` (type: `array`):

RescueGroups animal IDs or animal page URLs, e.g. `22514067`.

## `organizationIds` (type: `array`):

RescueGroups organization IDs, e.g. `6260` (the number in a pet photo URL).

## `orgQuery` (type: `string`):

Optional organization name filter. Name search needs the optional `apiKey`; a numeric ID or organization-page URL works without one (legacy `orgQuery` inputs are supported).

## `maxItems` (type: `integer`):

Hard cap on emitted records.

## Actor input object example

```json
{
  "mode": "search",
  "species": "Dog",
  "sex": "",
  "ageGroup": "",
  "sizeGroup": "",
  "specialNeedsOnly": false,
  "goodWithDogsOnly": false,
  "goodWithCatsOnly": false,
  "goodWithKidsOnly": false,
  "needsFosterOnly": false,
  "housetrainedOnly": false,
  "declawedOnly": false,
  "postalCode": "02108",
  "radiusMiles": 25,
  "includeDetails": true,
  "animalIds": [],
  "organizationIds": [],
  "orgQuery": "",
  "maxItems": 3
}
```

# Actor output Schema

## `animals` (type: `string`):

Dataset containing every scraped adoptable animal and rescue organization.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "species": "Dog",
    "sex": "",
    "ageGroup": "",
    "sizeGroup": "",
    "specialNeedsOnly": false,
    "goodWithDogsOnly": false,
    "goodWithCatsOnly": false,
    "goodWithKidsOnly": false,
    "needsFosterOnly": false,
    "housetrainedOnly": false,
    "declawedOnly": false,
    "postalCode": "02108",
    "radiusMiles": 25,
    "includeDetails": true,
    "animalIds": [],
    "organizationIds": [],
    "orgQuery": "",
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/rescuegroups-org-adoptable-pet-finder-by-zip").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "species": "Dog",
    "sex": "",
    "ageGroup": "",
    "sizeGroup": "",
    "specialNeedsOnly": False,
    "goodWithDogsOnly": False,
    "goodWithCatsOnly": False,
    "goodWithKidsOnly": False,
    "needsFosterOnly": False,
    "housetrainedOnly": False,
    "declawedOnly": False,
    "postalCode": "02108",
    "radiusMiles": 25,
    "includeDetails": True,
    "animalIds": [],
    "organizationIds": [],
    "orgQuery": "",
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/rescuegroups-org-adoptable-pet-finder-by-zip").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "species": "Dog",
  "sex": "",
  "ageGroup": "",
  "sizeGroup": "",
  "specialNeedsOnly": false,
  "goodWithDogsOnly": false,
  "goodWithCatsOnly": false,
  "goodWithKidsOnly": false,
  "needsFosterOnly": false,
  "housetrainedOnly": false,
  "declawedOnly": false,
  "postalCode": "02108",
  "radiusMiles": 25,
  "includeDetails": true,
  "animalIds": [],
  "organizationIds": [],
  "orgQuery": "",
  "maxItems": 3
}' |
apify call vexaloom-labs/rescuegroups-org-adoptable-pet-finder-by-zip --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/rescuegroups-org-adoptable-pet-finder-by-zip"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jvPNFOkWdHfMwL4DL/builds/Bm2HW4YnM5nDD2nF9/openapi.json