# propdata

Zillow property data through the APIllow API: search homes by
city or ZIP code, pull a single property by its Zillow ID,
its listing URL or its street address, look up several
addresses in one call, check which addresses currently have
an active listing, create a free account, and see how much
of the monthly quota is left.

Property answers come from the upstream service and are
passed through untouched, so a property record carries what
APIllow returns for it — identifiers, address, status and
type, bed and bath counts, living area and lot size, year
built, pricing and estimates, sale and tax history, a small
set of comparable homes, photos, and nearby schools.

Nine tools are provided. A tenth tool in the upstream
catalogue, a plan-upgrade helper whose only output is a
payment link, is deliberately not part of this package.

The nine tools:

- `search_properties` — search by city or area, with an
  optional listing type and a cap on how many results come
  back.
- `search_by_zip` — search by one or more ZIP codes.
- `get_property` — one property by its Zillow property ID.
- `get_property_by_url` — one property from its Zillow
  listing URL.
- `get_property_by_address` — one property by street
  address.
- `get_properties_by_addresses` — several street addresses
  looked up in a single request.
- `check_addresses` — which of a set of addresses has an
  active Zillow listing, with the listing URL.
- `signup` — create a free account; the API key arrives by
  email after verification.
- `check_usage` — current usage, quota and plan details.

## Configuration

```bash
export APILLOW_API_KEY="..."   # required for every tool except signup
export APILLOW_BASE_URL="https://apillow.co/api"   # optional override
```

Without a key, every tool except `signup` fails with
`APILLOW_API_KEY is not set`, before any argument checking.
The key is sent to the API as an `X-API-Key` header.

## CLI

Each tool is a subcommand taking one JSON argument string:

```bash
npx @reneturcios/propdata search_properties '{"query":"Austin TX","type":"sale","max_items":10}'
npx @reneturcios/propdata search_by_zip '{"zip_codes":[90210]}'
npx @reneturcios/propdata get_property '{"zpid":12345678}'
npx @reneturcios/propdata check_usage '{}'
npx @reneturcios/propdata --version
```

Output is the upstream JSON, printed unchanged. Exit codes:
`0` on success, `1` on a runtime error (including a
validation or upstream failure), `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/propdata mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "propdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/propdata", "mcp"],
      "env": {
        "APILLOW_API_KEY": "..."
      }
    }
  }
}
```

## Docker

```bash
docker run -i -e APILLOW_API_KEY="..." ghcr.io/cloudcorprecords/propdata
docker run --rm -e APILLOW_API_KEY="..." ghcr.io/cloudcorprecords/propdata check_usage '{}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios