GeoClear — API Docs

API Reference

198M US addresses. Census tract, FEMA flood zone, and timezone — one API call.

Base URL: https://geoclear.io · All responses are JSON · All timestamps UTC

Don't have an API key? Sign up free — 10,000 lookups/day, no credit card required.

Authentication

Pass your API key via header or query parameter on every request.

curl https://geoclear.io/api/address?street=Main+St&city=Austin&state=TX \
  -H "X-Api-Key: YOUR_API_KEY"

curl "https://geoclear.io/api/address?street=Main+St&city=Austin&state=TX&key=YOUR_API_KEY"

Quick start

Verify an address in under a minute.

curl "https://geoclear.io/api/address?number=1600&street=Pennsylvania+Ave&city=Washington&state=DC" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch(
  'https://geoclear.io/api/address?number=1600&street=Pennsylvania+Ave&city=Washington&state=DC',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);
const { data } = await res.json();
console.log(data[0].full_address, data[0].confidence);

import requests

r = requests.get(
    'https://geoclear.io/api/address',
    params={'number': '1600', 'street': 'Pennsylvania Ave', 'city': 'Washington', 'state': 'DC'},
    headers={'X-Api-Key': 'YOUR_API_KEY'}
)
data = r.json()['data']
print(data[0]['full_address'], data[0]['confidence'])

Response

{
  "ok": true,
  "data": [{
    "full_address": "1600 Pennsylvania Ave NW, Washington, DC 20500",
    "add_number":  "1600",
    "st_name":     "Pennsylvania",
    "st_pos_typ":  "Ave",
    "st_pre_dir":  "NW",
    "city":        "Washington",
    "state":       "DC",
    "zip_code":    "20500",
    "latitude":    38.8977,
    "longitude":   -77.0365,
    "county_fips": "11001",
    "timezone":    "America/New_York",
    "residential": false,
    "confidence":  98
  }]
}

Rate limits

Limits are enforced per API key. Exceeding either limit returns 429 Too Many Requests.

Tier	Price	Req / min	Req / day
Free	$0	10	10,000
Starter	$49/mo	100	50,000
Growth	$199/mo	500	150,000
Professional	$499/mo	1,000	500,000
Scale	$999/mo	9,999	5,000,000

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Errors

All errors return a JSON body with ok: false and an error string.

Status	Meaning
400	Bad request — missing or invalid parameters
401	Missing or invalid API key
402	Enrichment requires a Pro or higher tier
429	Rate limit exceeded (per-minute or per-day)
500	Internal server error

{
  "ok":    false,
  "error": "Invalid or revoked API key."
}

GET /api/address

Address lookup & verification

Verify a US address and return matching records with coordinates, county FIPS, timezone, residential flag, and a 0–100 confidence score. Use ?fuzzy=true for typo-tolerant matching — "Pensilvania Ave" finds "Pennsylvania Ave".

Parameter	Type		Description
number	string	optional	House/building number (e.g. `"1600"`)
street	string	optional	Street name (e.g. `"Pennsylvania Ave"`)
city	string	optional	City name
state	string	optional	2-letter state code (e.g. `"DC"`)
zip	string	optional	ZIP code
fuzzy	boolean	optional	Enable typo-tolerant matching. Default: `false`
limit	integer	optional	Max results. Default: `20`, max: `100`

curl "https://geoclear.io/api/address?number=1600&street=Pennsylvania+Ave&state=DC" \
  -H "X-Api-Key: YOUR_API_KEY"

# Fuzzy match
curl "https://geoclear.io/api/address?street=Pensilvania+Ave&state=DC&fuzzy=true" \
  -H "X-Api-Key: YOUR_API_KEY"

const params = new URLSearchParams({ number: '1600', street: 'Pennsylvania Ave', state: 'DC' });
const res = await fetch(`https://geoclear.io/api/address?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json();

Response fields

full_address

Formatted full address string

latitude / longitude

Rooftop or parcel-level coordinates

county_fips

5-digit county FIPS code (state + county)

timezone

IANA timezone string (e.g. America/New_York)

residential

Boolean — residential vs commercial

confidence

Match quality score 0–100

nad_uuid

Stable USDOT NAD record identifier

placement

Coordinate method: Rooftop, Parcel, etc.

GET /api/suggest

Address autocomplete

Returns up to 20 address suggestions matching a partial query. Built for live-as-you-type UX — responses cached 5 minutes.

Parameter	Type		Description
q	string	required	Address prefix, min 2 characters
state	string	optional	Scope to a state (2-letter code)
zip	string	optional	Scope to a ZIP code
limit	integer	optional	Max results. Default: `10`, max: `20`

curl "https://geoclear.io/api/suggest?q=1600+Penn&state=DC&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://geoclear.io/api/suggest?q=1600+Penn&state=DC', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json(); // array of address objects

POST /api/address/bulk

Bulk address verification

Verify and enrich up to 1,000 addresses in a single synchronous request. Each address in the request maps to one result in the response array (same order).

curl -X POST https://geoclear.io/api/address/bulk \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      { "number": "1600", "street": "Pennsylvania Ave", "state": "DC" },
      { "number": "350",  "street": "Fifth Ave",        "state": "NY" }
    ]
  }'

const res = await fetch('https://geoclear.io/api/address/bulk', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    addresses: [
      { number: '1600', street: 'Pennsylvania Ave', state: 'DC' },
      { number: '350',  street: 'Fifth Ave',        state: 'NY' }
    ]
  })
});
const { results } = await res.json();

Response

{
  "ok": true,
  "results": [
    { "full_address": "1600 Pennsylvania Ave NW, Washington, DC 20500", "confidence": 98, "...": "..." },
    { "full_address": "350 Fifth Ave, New York, NY 10118", "confidence": 97, "...": "..." }
  ]
}

GET /api/near

Proximity search

Returns addresses within a given radius of a lat/lon coordinate. Useful for reverse geocoding, delivery routing, or finding nearby points of interest.

Parameter	Type		Description
lat	number	required	Latitude (decimal degrees)
lon	number	required	Longitude (decimal degrees)
radius_km	number	optional	Search radius in km. Default: `1.0`
limit	integer	optional	Max results. Default: `20`, max: `500`

curl "https://geoclear.io/api/near?lat=38.8977&lon=-77.0365&radius_km=0.5&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://geoclear.io/api/near?lat=38.8977&lon=-77.0365&radius_km=0.5', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json();

GET /api/enrich

Point enrichment

Returns census tract, block group, and FEMA flood zone for a lat/lon coordinate or NAD UUID. Pulls live data from the US Census Bureau Geocoder API and FEMA NFHL — no separate subscriptions needed. Results are cached in-process (~10K LRU entries).

Parameter	Type		Description
lat	number	optional*	Latitude (use with `lon`)
lon	number	optional*	Longitude (use with `lat`)
nad_uuid	string	optional*	NAD UUID from an address lookup result (alternative to lat/lon)

* Either lat+lon or nad_uuid is required.

curl "https://geoclear.io/api/enrich?lat=38.8977&lon=-77.0365" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://geoclear.io/api/enrich?lat=38.8977&lon=-77.0365', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json();

Response

{
  "ok": true,
  "data": {
    "census": {
      "tract":       "010100",
      "block_group": "1",
      "geoid":       "110010101001"
    },
    "fema": {
      "flood_zone": "X",
      "sfha":       false,
      "panel":      "1100010001B"
    },
    "coordinates": {
      "latitude":  38.8977,
      "longitude": -77.0365
    }
  }
}

FEMA flood zone codes: X = minimal risk · AE / A = high risk (SFHA) · VE = coastal high risk

GET /api/zip/:zip

ZIP code lookup

Returns address count and metadata for a ZIP code.

curl "https://geoclear.io/api/zip/20500" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://geoclear.io/api/zip/20500', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json();

GET /api/state/:code

State summary

Returns address count, county count, city count, and ZIP count for a US state.

curl "https://geoclear.io/api/state/TX" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://geoclear.io/api/state/TX', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json();

GET /v1/me

API key status

Returns your key's tier, rate limits, and usage counters.

curl "https://geoclear.io/v1/me" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://geoclear.io/v1/me', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const { data } = await res.json();

Response

{
  "ok": true,
  "data": {
    "tier":        "starter",
    "req_per_min": 100,
    "req_per_day": 50000,
    "usage_today": 1243,
    "usage_total": 87241,
    "is_active":   true
  }
}

POST /v1/signup

Free tier signup

Issue a free API key with 10,000 lookups/day. No credit card required. Key is emailed to the address provided and returned in the response. Rate limited to 5 signups per hour per IP.

curl -X POST https://geoclear.io/v1/signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

const res = await fetch('https://geoclear.io/v1/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]' })
});
const { key } = await res.json();

Response

{
  "ok":  true,
  "key": "gc_free_a1b2c3d4..."
}

GET /api/health

Health check

Returns service status and total address count. No authentication required.

curl https://geoclear.io/api/health

Response

{
  "status":    "ok",
  "addresses": 198657535,
  "version":   "1.0.0"
}

Why GeoClear vs SmartyStreets

The two most common alternatives — and what's different.

	GeoClear	SmartyStreets
FEMA flood zone	✓ Included free	✗ Not available
Census tract (HMDA)	✓ Included free	✗ Not available
Address validation	✓	✓
Free tier	10,000 / month	250 / month
Starting price	$49 / month (Starter)	$299 / month
Data sources	USDOT NAD + FEMA NFHL + Census Bureau	USPS + proprietary

Migration from SmartyStreets: Replace smartystreets.com/street-address calls with geoclear.io/api/address?street=&city=&state=. Response shape is similar — see address lookup docs above. FEMA flood zone and census tract are included on all paid plans.

Ready to start?

Free tier — 10,000 lookups/day. No credit card.

Get free API key →