🗺️ZIP Code Database

Overview Explore Data Data Dictionary Build Package API Docs Pricing

Included with every purchase — 12 months access

API Documentation

Access your ZIP code data programmatically via REST API or MCP for AI assistants. Your API key is generated automatically when you purchase.

Quick Start

1. Get Your API Key

Your API key is emailed with your purchase confirmation and available on your account page. Keys start with gs_.

2. Make Your First Request

Terminal

curl -H "Authorization: Bearer gs_YOUR_KEY_HERE" \
  https://www.groundsmarts.com/api/v1/zipcodes/90210

Authentication & Limits

Authentication

Pass your key via header:

Authorization: Bearer gs_your_key

Or: X-API-Key: gs_your_key

Rate Limits

• 1,000 requests per day
• Standard rate limit headers included
• 429 returned when exceeded
• Batch endpoint counts as 1 request

Field Access

You only see fields from modules you purchased. A Base-only key returns ~60 fields; a full access key returns all 290+.

Key Lifecycle

Keys are valid for 12 months from purchase. Manage keys (regenerate, revoke) from your account page or via the /api/v1/keys endpoint.

Endpoints

Base URL: https://www.groundsmarts.com/api/v1

GET/zipcodes/:zipcodeLookup ZIP Code

Get all available data for a single ZIP code.

Parameters

Name	In	Required	Description
`zipcode`	path	✓	5-digit ZIP code (e.g., 90210)
`fields`	query	—	Comma-separated field names to return

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  /api/v1/zipcodes/90210

Response

{
  "data": {
    "zipcode": "90210",
    "state_abbr": "CA",
    "county_name": "Los Angeles",
    "total_population": 19442,
    "median_household_income": 131805,
    "urbanicity": "Urban"
  }
}

GET/zipcodesSearch & Filter

Find ZIP codes matching demographic, geographic, or economic criteria. At least one filter is required.

Parameters

Name	In	Required	Description
`state`	query	—	2-letter state code (e.g., CA, TX)
`county`	query	—	County name (partial match)
`urbanicity`	query	—	Urban, Suburban, or Rural
`min_population`	query	—	Minimum total population
`max_population`	query	—	Maximum total population
`min_income`	query	—	Minimum median household income
`max_income`	query	—	Maximum median household income
`sort`	query	—	Field name to sort by
`order`	query	—	asc or desc (default: asc)
`page`	query	—	Page number (default: 1)
`per_page`	query	—	Results per page (default: 25, max: 100)

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "/api/v1/zipcodes?state=TX&urbanicity=Urban&min_income=100000"

Response

{
  "data": [ { "zipcode": "75205", ... }, { "zipcode": "77005", ... } ],
  "meta": { "total": 142, "page": 1, "per_page": 25 }
}

POST/zipcodes/batchBatch Lookup

Look up data for up to 500 ZIP codes at once. Ideal for CRM enrichment workflows.

Parameters

Name	In	Required	Description
`zipcodes`	body	✓	Array of ZIP code strings (max 500)
`fields`	body	—	Array of field names to return

Example Request

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zipcodes": ["90210","10001","60614"]}' \
  /api/v1/zipcodes/batch

Response

{
  "data": [
    { "zipcode": "90210", "total_population": 19442, ... },
    { "zipcode": "10001", "total_population": 23594, ... },
    { "zipcode": "60614", "total_population": 64512, ... }
  ],
  "meta": { "total": 3 }
}

GET/compareCompare ZIP Codes

Side-by-side comparison of 2 to 25 ZIP codes.

Parameters

Name	In	Required	Description
`zipcodes`	query	✓	Comma-separated ZIP codes (2-25)
`fields`	query	—	Comma-separated field names

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "/api/v1/compare?zipcodes=90210,10001,60614"

Response

{
  "data": [
    { "zipcode": "90210", "median_household_income": 131805, ... },
    { "zipcode": "10001", "median_household_income": 105234, ... },
    { "zipcode": "60614", "median_household_income": 112456, ... }
  ]
}

GET/topTop Rankings

Find the top N ZIP codes ranked by any numeric metric.

Parameters

Name	In	Required	Description
`metric`	query	✓	Field name to rank by
`n`	query	—	Number of results (default: 10, max: 50)
`order`	query	—	desc (highest first) or asc (lowest first)
`state`	query	—	Filter to a specific state

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "/api/v1/top?metric=median_household_income&n=5&state=CA"

Response

{
  "data": [
    { "rank": 1, "zipcode": "94027", "median_household_income": 250001 },
    { "rank": 2, "zipcode": "94022", "median_household_income": 237500 },
    ...
  ]
}

GET/nearbyProximity Search

Find ZIP codes within a radius of a given point using Haversine distance.

Parameters

Name	In	Required	Description
`zipcode`	query	—	Center ZIP code (use this OR lat/lon)
`lat`	query	—	Center latitude
`lon`	query	—	Center longitude
`radius`	query	—	Radius in miles (default: 25, max: 100)
`limit`	query	—	Max results (default: 50, max: 200)
`min_population`	query	—	Min population filter

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "/api/v1/nearby?zipcode=90210&radius=10&limit=5"

Response

{
  "data": [
    { "zipcode": "90212", "distance_miles": 0.84, ... },
    { "zipcode": "90211", "distance_miles": 1.23, ... }
  ]
}

GET/aggregateAggregate Statistics

Compute aggregated statistics across ZIP codes. Automatically uses the correct method: SUM for counts, weighted average for rates/percentages, simple average for measurements.

Parameters

Name	In	Required	Description
`metrics`	query	✓	Comma-separated field names to aggregate
`group_by`	query	—	state, county, cbsa, urbanicity, or political_lean
`state`	query	—	Filter to a state
`min_population`	query	—	Minimum population filter

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "/api/v1/aggregate?metrics=total_population,vacancy_rate&state=FL&group_by=urbanicity"

Response

{
  "data": {
    "metrics_info": [
      { "field": "total_population", "method": "sum" },
      { "field": "vacancy_rate", "method": "weighted_avg", "weight_field": "total_housing_units" }
    ],
    "groups": [
      { "urbanicity": "Urban", "zipcode_count": 312, "total_population": 14523000, "vacancy_rate": 8.2 },
      { "urbanicity": "Suburban", "zipcode_count": 445, "total_population": 6234000, "vacancy_rate": 12.1 }
    ]
  }
}

GET/schemaData SchemaPublic

Browse all available fields, their types, modules, and descriptions. No authentication required.

Example Request

curl /api/v1/schema

Response

{
  "data": {
    "total_fields": 290,
    "fields": [
      { "name": "zipcode", "type": "Text", "module": "base", "description": "5-digit ZIP code" },
      ...
    ]
  }
}

GET/modulesAvailable ModulesPublic

List all data modules and pricing. No authentication required.

Example Request

curl /api/v1/modules

Response

{
  "data": {
    "modules": [
      { "id": "base", "name": "Base Database", "fieldCount": 60, "price": 99 },
      { "id": "climate", "name": "Climate & Environment", "fieldCount": 55, "price": 49 },
      ...
    ]
  }
}

MCP Server for AI Assistants

Connect your AI assistant (Claude, Cursor, etc.) directly to GroundSmarts data via the Model Context Protocol. Add this to your MCP config:

claude_desktop_config.json / .cursor/mcp.json

{
  "mcpServers": {
    "groundsmarts": {
      "url": "https://www.groundsmarts.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available Tools:

• lookup — Get data for a ZIP code
• search — Find ZIPs matching criteria
• compare — Compare multiple ZIPs
• find_top — Rank ZIPs by any metric
• schema — Browse available fields

Error Codes

Code	Meaning
`200`	Success
`400`	Bad request — missing required params or invalid filters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — requested field not in your subscription
`404`	ZIP code not found
`429`	Rate limit exceeded — wait and retry
`500`	Server error — contact support

Ready to integrate?

API access is included free for 12 months with every purchase.

Get Your API Key Browse Data Dictionary