Radius search
radius_searchFind every US ZIP Code and Canadian postal area within a radius of a centre point, with the distance to each. The centre takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair; a ZIP+4 searches from its parent ZIP, and coordinates are used as the point itself, so the centre comes back with no code. Centroid mode measures centre to centre and reaches 500 miles; spatial mode intersects real boundaries, reports how much of each area falls inside, and reaches 250 miles. Set a minimum radius to search a ring rather than a circle. summary.total_count is the number of matches returned; when the list is cut, summary.total_available is the number in the radius and a notice says so. ACS statistics always cover the whole radius. They are aggregates of the ZIP Codes' estimates: est and pct only, with no margin of error or Census column; for one ZIP Code's estimate with its margin of error, use zip_lookup. timezone and ACS come back with the search itself; only census and district data need zip_lookup per ZIP. Without an API key the count and a sample of matches are returned and the rest is withheld; free-tier keys are capped at 100 miles centroid and 50 spatial.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"code": "<code>",
"max": "<max>"
},
"name": "radius_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max | Yes | Radius in miles, as a number or a string. Up to 500 in centroid mode or 250 in spatial mode; exceeding the cap is an error rather than being reduced. May also be 'auto' to pick a radius from local population density, or 'auto-commute' to use commuting patterns where available. | |
| min | No | Minimum radius in miles, to exclude the middle and search a ring. Must be less than max. Defaults to 0. | |
| code | Yes | Centre point: a US ZIP Code, ZIP+4, Canadian FSA or postal code, or a latitude,longitude pair. | |
| mode | No | How to measure. centroid measures centre to centre and is the default when omitted; spatial intersects actual boundaries and adds how much of each area lies inside, at a lower maximum radius. | |
| limit | No | Maximum number of matches to return, up to 100, which is also the default. A larger value is reduced to 100 and the result says so in notices. When the list is cut, summary.total_available is the number of matches in the radius (summary.total_count is the number returned) and a RESULTS_CAPPED notice says so; to see matches beyond the first 100, narrow the radius or raise `min` to step outwards in bands. | |
| api_key | No | Your ZIP-Codes.com API key, only when you cannot send it as the X-Api-Key or Authorization: Bearer header (for example a key bought with buy_credits in this conversation). Leave it out to use the free tier. It is never shown back in a response. | |
| include | No | Enrichments, spelled as the REST API's /v2/radius include flags; each multiplies the credit cost. timezone lands on each match. acs_PROFILE (current release) and acs_PROFILE_YYYY return aggregate statistics across the whole result set, with the same field paths every year. Census and district enrichments are not available here; use zip_lookup. At most 16 ACS profile-years per call (one profile for one year is one); split a larger request into several calls. Accepted: timezone, acs_demographic, acs_social, acs_economic, acs_housing; acs_demographic_YYYY, acs_social_YYYY, acs_economic_YYYY, acs_housing_YYYY for YYYY 2011-2024. A bare flag is its newest year. | |
| acs_years | No | Alias, kept for clients that learned it before include took year flags: ACS release years for the bare acs_ profiles in include (acs_social with acs_years [2015] is acs_social_2015). Prefer the year flags in include. At most 16 profile-years per call. 2011 to 2024 (2024 is the current release). |