Parcel records from the county that keeps them

Quickstart

You can make 10 lookups a day without a key, so the first call needs no sign-up.

1. Send a full address

   Send street, city and state. A partial address can geocode to nothing and return matched: false.

2. Check matched and atlas_indexed

   Both true means the county answered. A miss still returns 200, so branch on the fields and not on the status code.

3. Add a key when you need more

   A free uk_live_ key raises the limit to 500 calls a day. Send it as a bearer token.

Authentication

Lookup works without a key at a per-IP limit of 10 calls a day. A key swaps that limit for your plan's quota on lookup. The free plan allows 500 keyed calls per UTC day.

Send your uk_live_ key as Authorization: Bearer. The key authenticates the API directly, and a session JWT will not. Create a key on your account page.

The CLI reads UKS_API_KEY from the environment first and falls back to a key saved with uks login.

SDK, MCP, CLI and REST

The SDK, the CLI's county search and the npm MCP package work offline against bundled data and need no account. Owner data comes from the REST API and from 2 paid-plan tools on the hosted MCP server.

npm SDK

@urbankitstudio/atlas is TypeScript with zero dependencies. It carries the whole atlas, so county search runs in your bundle. Unknown input returns undefined and does not throw.

MCP server

@urbankitstudio/mcp-atlas runs over stdio with 4 offline discovery tools. The hosted server at /api/mcp has 7 tools that need no key, and adds enrich_address and radius_owners on a key. See the tool list.

uks CLI

uks needs Node.js 22 or newer. Every command prints one JSON document with --json and exits with a code a script can branch on. See the commands and exit codes.

Resolve one address to its parcel record

Geocodes the address, routes it to the county that owns it, and queries that county's parcel layer.

Without a key

10 a day per IP

Free key

500 a day

Keyed call

1 quota unit

Usable without a key at a lower IP-based rate limit; a free key raises it to 500/day. On a plan or free key, every keyed call counts one unit against the key's quota (a per-call rate limit), a call answered from a stale cached geocode included. Pay-as-you-go bills one unit only for a fresh answer from a county with a public parcel endpoint; a no-match, an unindexed county, a county with no endpoint, an outage, or a stale geocode is not billed.

Query parameters

• addressstring, min length 3Required

  Full street address including city and state. A partial address will usually fail to geocode.

• opstringOptional

  Idempotency token for a retry. Reusing it on an identical request reuses the reservation instead of billing again. It must match ^uklk[|][0-9a-fA-F-]{20,80}$.

Request headers

• AuthorizationBearer uk_live_...Optional

  A key swaps the anonymous per-IP limit of 10 calls a day for your plan's quota.

Response

• okbooleanAlways

  Always true on a 200.

• queryobject

  The request, echoed back.

• matchedbooleanAlways

  False when the address could not be geocoded.

• atlas_indexedboolean

  Whether the resolved county is in the atlas. False means we geocoded it but cannot query it.

• geocodeobject

  Where the address resolved.

  • lat, number
  • lon, number
  • countyName, string
  • stateAbbrev, string
  • countyFips, string
• geocode_staleboolean

  True when the U.S. Census geocoder was unavailable and the last cached geocode was served instead. Pay-as-you-go is not billed for such an answer. A plan or free key's call still counts its one unit, because that unit is a per-call rate limit rather than a charge for the answer.

• fallbackstring

  Present when the county is not indexed: where to go instead.

• requestobject

  Present on a not-indexed answer. body is ready to POST to url as-is; keys the server did not know are omitted. Requesting is free.

  • how, string
  • url, string
  • body, object
  • message, string
• messagestring

  Human-readable detail, such as why a geocode failed. Do not match on it.

• countyobject

  A county as served by the public API (snake_case; the registry's internal camelCase is not the wire shape). See observed health.

Observed health

The county record's observed_health is what the liveness probe last saw. Each state has a distinct shape, so it reads without color. A null value means no observation exists, so treat it as unknown.

Endpoints and parcel rows also carry endpoint_status, one of live, stale, unreachable or unverified. That is the registry's curated record, set by a person. It is not a probe result.

Errors

Every non-2xx response has one shape, with ok false, a stable error code and an optional message. Branch on error and never on message.

Rate limits

A 200 and a 429 carry the rate-limit headers below. A 429 adds retry-after.

For agents and scripts

Run the stdio server with npx -y @urbankitstudio/mcp-atlas, or point a client at the hosted endpoint. The hosted server takes an optional bearer key, which the 2 paid-plan tools need.

With the CLI, pass --json on every call and set UKS_API_KEY in the environment rather than running uks login.

MCP tools

Tools marked No need no key. Every request to the hosted server, keyed or not, counts against a per-IP cap of 120 a minute.

uks commands

CLI exit codes