AddressAPI

GET /v1/autocomplete

Returns address suggestions as the user types. Uses Census geocoder + OpenStreetMap for broad coverage. Google charges $2.83/1K for this — included in all AddressAPI plans.

Example Request

curl "https://addressapi.portofcams.com/v1/autocomplete?q=1600+Penn" \
  -H "x-api-key: addr_your_key_here"

Response

{
  "query": "1600 Penn",
  "count": 2,
  "suggestions": [
    {
      "formatted": "1600 Pennsylvania Avenue Northwest, Washington, DC, 20500",
      "coordinates": { "lat": 38.8976, "lon": -77.0365 },
      "_source": "openstreetmap"
    },
    {
      "formatted": "1600 PENN ST, HARRISBURG, PA, 17102",
      "coordinates": { "lat": 40.2697, "lon": -76.8867 },
      "_source": "census"
    }
  ]
}

GET /v1/reverse

Reverse geocode — convert lat/lon coordinates to an address. Uses Census Bureau + OpenStreetMap.

Example Request

curl "https://addressapi.portofcams.com/v1/reverse?lat=38.8977&lon=-77.0365" \
  -H "x-api-key: addr_your_key_here"

Response

{
  "coordinates": { "lat": 38.8977, "lon": -77.0365 },
  "location": {
    "city": "Washington",
    "county": "District of Columbia",
    "state": "District of Columbia",
    "state_abbr": "DC",
    "zip_code": "20006",
    "census_tract": "11001006202",
    "metro_area": "Washington-Arlington-Alexandria, DC-VA-MD-WV",
    "congressional_district": "Delegate District (at Large)",
    "school_district": "District of Columbia Public Schools"
  },
  "_source": "census"
}

GET /v1/enrich

Enrich a US address with property, flood, demographic, walkability, crime, school, hazard, and broadband data.

Example Request

curl "https://addressapi.portofcams.com/v1/enrich?address=1000+Ocean+Drive,+Miami+Beach,+FL+33139" \
  -H "x-api-key: addr_your_key_here"

Response Fields

Example Response

{
  "address": "1000 OCEAN DR, MIAMI BEACH, FL 33139",
  "coordinates": { "lat": 25.7781, "lon": -80.1304 },
  "location": {
    "county": "Miami-Dade",
    "state": "Florida",
    "state_abbr": "FL",
    "city": "Miami Beach",
    "zip_code": "33139",
    "census_tract": "12086004402",
    "metro_area": "Miami-Fort Lauderdale-Pompano Beach, FL",
    "school_district": "Dade County School District"
  },
  "flood": { "flood_zone": "AE", "flood_risk": "high", "in_sfha": true },
  "demographics": {
    "median_household_income": 26031,
    "median_home_value": 423000,
    "population": 6131,
    "median_rent": 1283
  },
  "property": {
    "median_property_tax": 2699,
    "effective_tax_rate_pct": 0.64,
    "vacancy_rate_pct": 26,
    "single_family_pct": 5,
    "multi_family_pct": 85,
    "median_year_built": 1969
  },
  "walkability": {
    "walk_commute_pct": 11,
    "transit_commute_pct": 8,
    "bike_commute_pct": 12,
    "zero_car_pct": 44,
    "walkability_score": 100
  },
  "crime": {
    "poverty_rate_pct": 35,
    "unemployment_rate_pct": 8.1,
    "safety_score": 56
  },
  "schools": {
    "bachelors_or_higher_pct": 42,
    "high_school_diploma_pct": 80
  },
  "broadband": { "internet_access_pct": 59, "broadband_pct": 52 },
  "hazards": ["hurricane_moderate"],
  "hazard_details": { "seismic_sds": 0.043 },
  "_usage": { "used": 1, "limit": 100, "tier": "free" }
}

GET /v1/validate

Verify, standardize, and geocode a US address. Fast — no enrichment pipeline, just validation + geocoding.

Example Request

curl "https://addressapi.portofcams.com/v1/validate?address=350+5th+ave+new+york" \
  -H "x-api-key: addr_your_key_here"

Response

{
  "status": "validated",
  "deliverability": "deliverable",
  "address_type": "street_address",
  "standardized": {
    "line1": "350 5TH AVE",
    "line2": null,
    "city": "NEW YORK",
    "state": "NY",
    "state_name": "New York",
    "zip_code": "10118",
    "formatted": "350 5TH AVE, NEW YORK, NY, 10118"
  },
  "components": {
    "number": "350", "street": "5TH", "suffix": "AVE",
    "city": "NEW YORK", "state": "NY", "zip_code": "10118", "county": "New York"
  },
  "coordinates": { "lat": 40.7478, "lon": -73.9850 },
  "metadata": { "census_fips": "36061007600", "corrected": false }
}

Status Values

POST /v1/validate

Verify using a freeform string or structured components.

Request Body (JSON) — structured

{
  "street": "350 5th Ave",
  "city": "New York",
  "state": "NY",
  "zip": "10118"
}

Request Body (JSON) — freeform

{ "address": "350 5th Ave, New York, NY 10118" }

POST /v1/validate/batch

Verify up to 1,000 addresses. Batches ≤50 return synchronously. Larger batches return a job ID for polling.

Request Body (JSON)

{
  "addresses": ["350 5th Ave, New York, NY", "1600 Pennsylvania Ave NW, DC"],
  "webhook_url": "https://your-server.com/callback"
}

Response (synchronous, ≤50)

{
  "total": 2, "successful": 2, "failed": 0,
  "results": [
    { "index": 0, "status": "validated", "standardized": { ... } },
    { "index": 1, "status": "validated", "standardized": { ... } }
  ]
}

Response (async, >50)

{
  "job_id": "job_abc123",
  "status": "pending",
  "poll_url": "/v1/validate/batch/job_abc123"
}

POST /v1/batch

Enrich up to 100 addresses in a single request. Processed in parallel (10 concurrent).

Request Body (JSON)

{
  "addresses": [
    "350 5th Ave, New York, NY 10118",
    "1600 Pennsylvania Ave NW, Washington, DC 20500",
    "1000 Ocean Drive, Miami Beach, FL 33139"
  ]
}

Example Request

curl -X POST "https://addressapi.portofcams.com/v1/batch" \
  -H "x-api-key: addr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["350 5th Ave, New York, NY","1600 Pennsylvania Ave, DC"]}'

Response

{
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    { "index": 0, "address": "350 5th Ave, New York, NY", "status": "ok", "data": { ... } },
    { "index": 1, "address": "1600 Pennsylvania Ave, DC", "status": "ok", "data": { ... } }
  ],
  "_usage": { "used": 27, "limit": 100, "tier": "free" }
}

GET /v1/dashboard

Get usage stats for your API key. Auth required.

Response

{
  "key": "addr_...",
  "email": "you@company.com",
  "tier": "free",
  "monthly_limit": 100,
  "monthly_used": 27,
  "monthly_remaining": 73,
  "all_time_lookups": 27,
  "daily_usage": [{ "day": "2026-03-07", "count": 27 }],
  "recent_lookups": [{ "address": "...", "status_code": 200, "latency_ms": 5463 }]
}

POST /v1/signup

Create a free API key. No auth required.

Request Body (JSON)

{ "email": "you@company.com" }

Response

{
  "message": "API key created.",
  "api_key": "addr_abc123...",
  "tier": "free",
  "monthly_limit": 100
}

GET /health

Health check. No auth required.

{ "status": "ok", "uptime": 3600.5 }