canonical: https://jentic.com/apis/interzoid.com/interzoid-zip-code-detailed-info-api

# Interzoid Zip Code Detailed Info API

The Interzoid Zip Code Detailed Info API returns geographic and demographic detail for a US zip code, including the resolved city and state, latitude and longitude, area in square miles, total population, and household-level percentages for income brackets, married, elderly, and farming households. It is designed to enrich US-shaped data with a single GET call so workflows that hold only a zip code can support segmentation, mapping, and territory planning. The endpoint accepts one zip per call and returns a structured JSON object.

## For AI agents

Look up city, state, lat/long, and demographic detail for a US zip code so an agent can enrich a contact, segment by income, or place a row on a map.

## Scope

Does not validate full street addresses, support non-US postal codes, or return individual-level demographics - use for zip-level US geographic and household-aggregate enrichment only.

## Capabilities

- Resolve a US zip code to its City, State, Latitude, and Longitude
- Read household income percentages for a zip to segment leads by income bracket
- Capture total Population and AreaSquareMiles for a zip into a territory record
- Apply MarriedHouseholdPercent and ElderlyHouseholdPercent to demographic targeting
- Identify zip codes with FarmerHouseholdPercent above a threshold for sector-specific outreach

## Use cases

### Lead Segmentation by Income

Segment a US lead list by household income tier by reading IncomePercent50k, IncomePercent100k, and IncomePercent200k for each lead's zip code. The Zip Code Detailed Info API returns these percentages directly, so agents can route the top tier to a high-touch sales queue without buying a separate demographic dataset. The endpoint accepts one zip per call.

Example prompt: For each lead, call /getzipcodeinfo with zip set to the lead's zip and route the lead to the high-touch queue if IncomePercent200k exceeds 20.

### Territory Mapping

Place each customer on a map by enriching their zip code with Latitude and Longitude, then aggregate by AreaSquareMiles and Population for territory sizing. The API returns these fields together so a territory tool can call once per zip and persist the result. City and State are echoed back for human-readable labels.

Example prompt: Call /getzipcodeinfo for each customer zip and write the returned Latitude and Longitude into a Mapbox-ready customers table.

### Sector-Specific Outreach

Identify zip codes with elevated FarmerHouseholdPercent or MarriedHouseholdPercent to drive sector-specific outreach campaigns. The API returns these household-level percentages alongside core geographic data, so a single call enriches both the geographic and the segmentation needs of the campaign. Rows whose demographic flags fall below threshold can be deprioritized.

Example prompt: Call /getzipcodeinfo for every zip on a US prospect list and filter to zips where FarmerHouseholdPercent exceeds 10 for an agriculture-sector campaign.

### Agent-Driven Customer Enrichment via Jentic

An AI customer-enrichment agent uses Jentic to call the Interzoid Zip Code Detailed Info API for every new US signup, writing City, State, Latitude, Longitude, and Population to the customer record. Through Jentic the Interzoid license key is held in the credential vault and never enters the agent context. The agent does not need to ship Interzoid SDK code.

Example prompt: Use Jentic to search for 'get detailed information for a US zip code', load /getzipcodeinfo, and execute it for every new signup to populate the customer's geographic and demographic columns.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/getzipcodeinfo` | Return city, state, lat/long, area, population, and demographic percentages for a US zip code |

## Key resources

- **Detailed Zip Code Information** — GET endpoint that accepts a US zip code and returns City, State, Latitude, Longitude, AreaSquareMiles, Population, and household-level income, age, marital, and farming percentages.

## Why Jentic

- **Setup:** Wiring the Interzoid Zip Code Detailed Info API by hand means obtaining a license key, appending it as a license query parameter on each call to /getzipcodeinfo, and handling the request plumbing yourself. Through Jentic you install once, import this API from the API Directory, store the license key once, and your agent calls it.
- **Permission scoping:** This API exposes a single read-only GET /getzipcodeinfo operation that takes a US zip code in the query, with no resource id in the URL path, so scoping is at the operation level: you limit the agent to the zip-level enrichment lookup it needs. It only reads geographic and household-aggregate data and writes nothing, so there is no destructive operation to include.
- **Credential handling:** Your Interzoid license key is stored once, encrypted, by your own Jentic One instance and injected as the license parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get detailed information for a US zip code', and Jentic returns the Zip Code Detailed Info operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Smarty US ZIP Code** — US zip code lookup focused on validation and city-state-zip combinations rather than demographic detail.
- **Interzoid State Data Standardization API** — Standardizes US and Canadian state names to two-letter abbreviations, often run alongside zip enrichment.
- **Interzoid Get Weather By Zip Code API** — Returns current weather for a US zip code, useful when a workflow needs both demographic and live-conditions data.

## FAQ

### What authentication does the Interzoid Zip Code Detailed Info API use?

The API uses an Interzoid license key passed as the required `license` query parameter on /getzipcodeinfo. Through Jentic the license key is held in the credential vault and injected at execution time, so the raw key never enters the agent context.

### Can I retrieve latitude and longitude with this API?

Yes. The 200 response on /getzipcodeinfo includes Latitude and Longitude alongside City, State, AreaSquareMiles, and Population, so a single call covers both geographic and demographic enrichment needs.

### What are the rate limits for the Interzoid Zip Code Detailed Info API?

The OpenAPI spec does not declare a numeric rate limit. Each successful call decrements a credit balance returned in the Credits response field, and a 402 status is returned when credits are exhausted. Refer to interzoid.com for current per-license-tier throughput.

### How do I enrich a US zip code through Jentic?

Install the SDK with `pip install jentic`, search for 'get detailed information for a US zip code', load /getzipcodeinfo, and execute it with zip set to the five-digit code. The IncomePercent200k, Latitude, and Longitude fields are ready for use.

### Does the API cover non-US zip codes?

No. /getzipcodeinfo accepts US zip codes only. For Canadian postal-code enrichment or international postal data, use a different provider.

### What does the API return for household demographics?

The 200 response includes IncomePercent50k, IncomePercent100k, IncomePercent200k, MarriedHouseholdPercent, ElderlyHouseholdPercent, and FarmerHouseholdPercent. These are intended for segmentation rather than individual targeting.

### Can I limit what my agent is allowed to do with the Interzoid Zip Code Detailed Info API?

Yes. Because you run Jentic One self-hosted, your own rules decide which operations and credentials the agent may use, and this API exposes only the single read-only GET /getzipcodeinfo lookup. You scope at the operation level, granting the agent just that zip-code enrichment call so it can read geographic and household-aggregate fields for a US zip and nothing more. Since the operation writes nothing and takes no resource id in the path, there is no destructive action to expose.