canonical: https://jentic.com/apis/geocod.io/geocodio

# Geocod Geocodio

Geocode individual and batch addresses to coordinates, reverse geocode coordinate pairs to addresses, and append data fields like congressional districts, census tracts, school districts, timezones, and ACS demographics to results. The API supports single and batch requests (up to 10,000 addresses per batch), spreadsheet-based list processing with job management, a distance calculation feature for measuring driving or straight-line distance between geocoded results and destination points, and US/Canada-specific address parsing across 16 endpoints.

## For AI agents

Geocode addresses and reverse geocode coordinates with US/Canada data appends including congressional districts, census tracts, school districts, timezone, and ACS demographics. Supports batch processing up to 10,000 per request.

## Scope

Does not handle map rendering, routing, POI search, or international addresses outside US/Canada - use for North American geocoding and data appends only.

## Capabilities

- Geocode single addresses or batches of up to 10,000 addresses per request with structured or free-form queries
- Reverse geocode coordinate pairs to full street-level addresses with configurable result limits
- Append congressional district, state legislative district, school district, census tract, and ACS demographic data to geocoded results
- Calculate driving distance and duration or straight-line distance between geocoded results and destination points
- Process spreadsheet uploads as asynchronous geocoding jobs with status tracking and download endpoints
- Resolve stable address keys directly to canonical address results without re-geocoding

## Use cases

### AI Agent Political District Lookup

AI agents resolve voter addresses to their congressional districts, state legislative districts, and unified school districts for civic tech applications. Through Jentic, agents search for 'geocode with congressional district' and receive the /geocode operation schema with the fields parameter. Pass fields=cd,stateleg,school and the address to get coordinates plus all district assignments in a single call. Supports the current and upcoming (118th/119th) Congress.

Example prompt: Geocode '1600 Pennsylvania Ave NW, Washington DC' with fields=cd,stateleg using the /geocode endpoint and return the latitude, longitude, and congressional district identifier

### Batch Geocoding for Real Estate Datasets

Real estate platforms geocode thousands of property listings in bulk to place them on maps and enrich them with census and school district data. The POST /geocode endpoint accepts up to 10,000 addresses per request as a JSON array, returning coordinates and optional field appends for each. For larger datasets, the /lists endpoint handles CSV/Excel uploads as asynchronous jobs with progress tracking.

Example prompt: Batch geocode three addresses ['1600 Pennsylvania Ave NW, Washington DC', '1 Apple Park Way, Cupertino CA', '350 5th Ave, New York NY'] via POST /geocode with fields=timezone and return coordinates and timezone for each

### Distance Calculation for Delivery Zones

Delivery and logistics platforms determine which destinations are reachable from a geocoded warehouse address within time or distance thresholds. The destinations[] parameter calculates driving or straight-line distance from each geocoded result to a list of destination points. Results include distance in miles or km and driving duration in seconds, with filtering by max distance and duration.

Example prompt: Geocode '350 5th Ave, New York NY' with destinations[]='40.7484,-73.9857' and distance_mode=driving using the /geocode endpoint and return the driving distance and duration

### Census Data Enrichment for Demographics

Market research and social science applications enrich address datasets with American Community Survey (ACS) demographics, census tract identifiers, and county FIPS codes. The fields parameter supports cd, stateleg, school, census, timezone, and acs-demographics among others. Results include tract codes, block group identifiers, and demographic statistics for the surrounding area.

Example prompt: Geocode '1109 Highland Ave, Austin TX' with fields=census,acs-demographics using the /geocode endpoint and return the census tract code and total population

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /geocode | Geocode a single address with optional data appends |
| POST | /geocode | Batch geocode up to 10,000 addresses |
| GET | /reverse | Reverse geocode coordinates to address |
| POST | /reverse | Batch reverse geocode multiple coordinate pairs |
| GET | /distance | Calculate distance between two locations |
| GET | /lists | List spreadsheet geocoding jobs |
| GET | /lists/{id} | Get status of a geocoding job |
| GET | /lists/{id}/download | Download completed geocoding results |

## Key resources

- **Geocode** — Forward geocoding with single and batch modes, structured queries, data field appends, and distance calculations
- **Reverse** — Reverse geocoding from coordinates to addresses with batch support and field appends
- **Distance** — Calculate driving or straight-line distance between locations with filtering and sorting
- **Lists** — Asynchronous spreadsheet-based geocoding jobs with upload, status, and download endpoints

## Why Jentic

- **Setup:** Wiring Geocodio by hand means registering your key, appending it as the api_key query parameter on every call, and choosing between the standard and enterprise hosts yourself. Through Jentic you install once, import Geocodio from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Geocodio puts the list id in the URL path (/lists/{id}), so a rule can pin your agent to one list: it can read and download that list and nothing else. You choose the operations it may call, so broader ones like forward or reverse geocoding are not included unless you add them.
- **Credential handling:** Your Geocodio API key is stored once, encrypted, by your own Jentic One instance and attached as the api_key query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'geocode with congressional district' or 'batch geocode addresses', and Jentic returns the matching Geocodio operation with its full input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HERE Geocoding & Search API** — Global geocoding with place search, autosuggest, and category browsing
- **LocationIQ API** — Global OSM-based geocoding with routing, timezone, and POI search
- **positionstack API** — Simple global geocoding with batch support and timezone/country modules

## FAQ

### What authentication does the Geocodio API use?

Geocodio authenticates requests using an API key passed as the `api_key` query parameter. Through Jentic, your Geocodio API key is stored encrypted in your Jentic One instance - agents receive scoped access without the raw key entering their context.

### Can I batch geocode thousands of addresses with Geocodio?

Yes. The POST /geocode endpoint accepts a JSON array of up to 10,000 addresses per request. For larger datasets, upload a CSV or Excel file via the /lists endpoint for asynchronous processing. Track job status with GET /lists/{id} and download results with GET /lists/{id}/download.

### What data fields can Geocodio append to geocoded results?

Pass the `fields` parameter with comma-separated values: cd (congressional district), stateleg (state legislative districts), school (school districts), census (tract/block/county FIPS), timezone, acs-demographics (ACS population data). Multiple fields can be combined in a single request.

### What are the rate limits for the Geocodio API?

Free tier allows 2,500 lookups per day and batch requests of up to 10,000 addresses. Paid plans remove daily limits and support the full feature set including HTTPS access and all data append fields. The API returns HTTP 422 for invalid requests and 403 for plan-restricted features.

### How do I get congressional district data for an address through Jentic?

Install the Jentic SDK with `pip install jentic` and search for 'geocode with congressional district'. Jentic returns the /geocode operation schema. Pass your address as the `q` parameter and set `fields=cd,stateleg`. Execute through Jentic to get coordinates plus the current congressional district number, representative info, and state legislative assignments.

### Does Geocodio support international addresses?

Geocodio focuses on the United States and Canada. The `country` parameter defaults to 'US' and accepts 'CA' for Canadian addresses. For global geocoding needs, consider alternatives like HERE, TomTom, or LocationIQ.

### Can I limit what my agent is allowed to do with the Geocodio API?

Yes. Because you run Jentic One yourself, your own rules decide which Geocodio operations and credentials your agent may use. Since Geocodio puts the list id in the URL path (/lists/{id}), a rule can pin the agent to a single list so it can only read that job's status and download its results. Broader operations like forward geocoding (GET /geocode) or reverse geocoding (GET /reverse) stay off limits unless you explicitly add them.