areaops

The official command-line tool for AreaOps — Census-scored ZIP code territory intelligence for home-services brands.

Score a market, profile a ZIP, and print MCP client configuration from a shell, a script, or a CI job. Every command takes --json, so an agent can consume the output directly.

Zero runtime dependencies.

Install

npm install -g areaops
# or run it without installing
npx areaops zip 30309

Requires Node 20 or newer.

Authenticate

Public commands need no credential. For everything else, mint a key in AreaOps under Settings → Developers & API and export it:

export AREAOPS_API_KEY=aoa_live_...

Or pass --api-key per invocation.

Commands

| Command | What it does | Key required | | --- | --- | --- | | areaops zip <zipcode> | Census demographics and per-vertical scores for one ZIP | no | | areaops score <vertical> | Ranked territory plan for a metro or ZIP list | yes | | areaops mcp-config | Print MCP client configuration | no | | areaops openapi | Fetch the published OpenAPI 3.1 contract | no | | areaops help [command] | Usage | no |

Examples

# A public ZIP profile — no key needed
areaops zip 30309

# One vertical's score for that ZIP, as JSON
areaops zip 30309 --vertical roofing --json

# Rank the top 20 roofing ZIPs in Atlanta
areaops score roofing --metro atlanta-ga --limit 20

# Build a direct-mail list from an explicit ZIP set
areaops score hvac --zips 75201,75202,75203 --objective direct_mail --json

# Wire up an agent
areaops mcp-config > ~/.config/mcp/areaops.json

# Generate a client from the contract
areaops openapi > areaops-openapi.json

Options

| Flag | Meaning | | --- | --- | | --json | Emit JSON instead of formatted text | | --api-key <key> | API key; defaults to $AREAOPS_API_KEY | | --base-url <url> | API base; defaults to $AREAOPS_BASE_URL or https://areaops.app | | --metro <slug> | (score) Launched metro, e.g. atlanta-ga | | --zips <a,b,c> | (score) Explicit ZIP list instead of a metro | | --objective <name> | (score) expansion, lsa, direct_mail, or cleanup | | --limit <n> | (score) 3–50, default 12 | | --vertical <slug> | (zip) Restrict to one vertical |

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | API or network failure | | 2 | Usage error |

Rate limits and metering

The CLI surfaces the API's rate-limit headers on failure, including Retry-After. Authenticated tool calls also consume metered units against your plan's monthly allowance — 1,000 included, score costs 10 per call. A 402 with code: usage_quota_exceeded means the allowance is spent.

Using AreaOps from an AI agent

The CLI is the scripting path. For an agent, prefer the Model Context Protocol server, which exposes 17 typed tools with confirm-gated writes:

claude mcp add --transport http areaops https://areaops.app/api/mcp \
  --header "Authorization: Bearer $AREAOPS_API_KEY"

Discovery is public and needs no key: https://areaops.app/api/mcp/info.

Links

• Developer portal — https://areaops.app/developers
• OpenAPI contract — https://areaops.app/openapi.json
• Agent instructions — https://areaops.app/llms.txt
• Support — [email protected]