Catalog

Search areas

Find areas and ZIP or postal codes by name across a country.

GETapi.leadity.io/v1/areas/search

Scope readMCP tool search_areas

Searches every area name and every ZIP or postal code in one country. An area hit carries all of its codes, a code hit names the area it sits in. truncated is true when more matched than were returned, so narrow the query rather than assuming these are all.

Example request

curl "https://api.leadity.io/v1/areas/search?country=US&q=el+paso" \
  -H "Authorization: Bearer $LEADITY_API_KEY"

Example response

{
  "country": "US",
  "hits": [
    {
      "kind": "area",
      "state": "TX",
      "area": "El Paso",
      "zips": [
        "79901",
        "79902"
      ]
    }
  ],
  "truncated": false
}

Headers

Authorizationstringrequired

Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

Query parameters

countrystringrequired

The two-letter country code, e.g. US. list_territories names the countries on sale.

Matches ^[A-Z]{2}$.

qstringrequired

A place name or the start of a code, e.g. paso or 787.

1 to 100 characters.

Response

countrystringrequired

hitsobject[]required

Each one of 2 shapes.

Show child attributes

Option 1object

Show child attributes

kindstringrequired

One ofarea

statestringrequired

areastringrequired

zipsstring[]required

Every code the area holds.

Option 2object

Show child attributes

kindstringrequired

One ofzip

statestringrequired

areastringrequired

The area the code sits in.

zipstringrequired

truncatedbooleanrequired

More matched than were returned.

Errors

Every refusal answers { error, message } with the status below. The full list is on the Errors page.

Code	Status	Meaning	Extra fields
unauthorized	401	The API key is missing, malformed, revoked or expired.	-
wrong_key_kind	401	This key opens the other surface: an API key works on the HTTP API, an MCP key on the MCP server.	-
account_suspended	403	The account is suspended.	-
email_not_verified	403	The account's email address is not verified yet.	-
invalid_body	400	The request does not match the operation's schema.	`issues`: The problems found, each with path (the field as a dotted path, led by the part of the request it travels in: path, query or body, such as body.items.1) and message (what is wrong there).
rate_limited	429	Too many requests. Wait for the Retry-After seconds and try again.	`retryAfterSeconds`: The seconds to wait, the same number as the Retry-After header.
try_again	503	Leadity could not answer just now. Retry in a moment, with the same Idempotency-Key on a spending call.	`retryAfterSeconds`: When a request with this Idempotency-Key is still being processed: the seconds to wait before retrying with the same key, as the Retry-After header says.
internal_error	500	Something failed on our side. Nothing was charged twice.	`body`: On the MCP server, when Leadity answered in a shape the tool does not publish: that answer as it came.