[ INTRODUCTION ]

The Atlasblock API

A neighborhood API that returns a single, scored view of any place in the United States. Send an address or zip code and get back normalized ratings across walkability, safety, schools, affordability, and more, the raw metrics behind each score, an objective climate facts block, and an optional written profile.

Need to work closer to the source? Granular endpoints return individual schools, block-group walkability, county crime, and climate on their own, drawn from the Census Bureau, FBI, NCES, EPA, and NOAA. Every response is JSON and versioned under /v1.

[ QUICKSTART ]

Your first request

[ CURL ]

curl "https://atlasblock.dev/api/v1/neighborhood?zip=28203" \
  -H "Authorization: Bearer ab_live_9f2c..."

[ AUTHENTICATION ]

Live and test keys

Every request must carry an API key as a bearer token in the Authorization header. Create and manage keys from your dashboard. The secret is shown once, so store it somewhere safe.

[ REQUEST ]

GET /v1/neighborhood?zip=28203
Authorization: Bearer ab_live_9f2c...

Live keys are prefixed ab_live_ and test keys ab_test_. Live calls count toward your plan's monthly quota (shared across all of your live keys). Test keys hit the same data on a separate free bucket. Use them in CI and local development; test calls are never billed and never count toward your plan. A missing or invalid key returns 401 UNAUTHORIZED.

Each key has a per-minute burst limit (set by your plan), and your account has an account-wide monthly quota shared across live keys. Every request counts: cache hits, client errors, and server errors alike. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding the burst limit or the monthly quota returns 429 with a Retry-After header.

[ REFERENCE ]

Endpoints

Every endpoint is versioned under /v1 and grouped into 14 domains. Open a domain for its endpoints, each with its own options, example request, and example response.

Regions

[ 3 ]

The broadest tier: the four US Census regions and their divisions.

[ VIEW ENDPOINTS → ]

States

[ 4 ]

Every state with metadata, its counties, rollups, and lookup.

[ VIEW ENDPOINTS → ]

Counties

[ 4 ]

County list, rollups, the schools within a county, and lookup.

[ VIEW ENDPOINTS → ]

Zips

[ 7 ]

Zip location, demographics, lookup, verify, and geocoding.

[ VIEW ENDPOINTS → ]

Neighborhoods

[ 8 ]

Scored profiles for a zip or address, plus discovery: search, rankings, recommend, and look-alikes.

[ VIEW ENDPOINTS → ]

Demographics

[ 2 ]

Who lives here: age, race/ethnicity, education, households, poverty, employment, and income (ACS).

[ VIEW ENDPOINTS → ]

Housing

[ 2 ]

Housing stock: value, rent, tenure, vacancy, structure type, age, and affordability (ACS).

[ VIEW ENDPOINTS → ]

Schools

[ 9 ]

Individual schools, districts, colleges, search, and verify.

[ VIEW ENDPOINTS → ]

Points of Interest

[ 5 ]

Individual venues, category counts, and density, live from OpenStreetMap.

[ VIEW ENDPOINTS → ]

Crime

[ 3 ]

County crime rates, national benchmarks, and comparison.

[ VIEW ENDPOINTS → ]

Mobility

[ 3 ]

Getting around: walkability, transit, bike, and commute for a zip.

[ VIEW ENDPOINTS → ]

Environment

[ 6 ]

Objective climate facts (stations, comparison, comfort) and FEMA natural-hazard risk.

[ VIEW ENDPOINTS → ]

Health

[ 1 ]

Community-health outcomes for a zip (CDC PLACES).

[ VIEW ENDPOINTS → ]

System

[ 1 ]

Operational status.

[ VIEW ENDPOINTS → ]

[ RESPONSE SCHEMA ]

The full profile response

[ 200 OK ]

{
  "status": "success",
  "data": {
    "location": {
      "zip": "28203",
      "city": "Charlotte",
      "state": "NC",
      "county": "Mecklenburg",
      "county_fips": "37119",
      "latitude": 35.21,
      "longitude": -80.85
    },
    "ratings": {
      "overall": 7.4,
      "walkability": 8.3,
      "bikeability": 7.2,
      "safety": 6.1,
      "schools": 6.8,
      "family_friendly": 7,
      "population_density": 6.8,
      "affordability": 5.9,
      "nightlife": 6.2
    },
    "climate": {
      "avg_temp_f": 61.2,
      "summer_high_f": 88.5,
      "winter_low_f": 32.1,
      "precip_inches": 43.5,
      "snow_inches": 2.3,
      "hot_days_over_90f": 32,
      "freezing_days_under_32f": 55,
      "station": "USW00013881",
      "source": "noaa_normals_1991_2020"
    },
    "raw_data": {
      "walkability_index": 15.4,
      "violent_crime_per_100k": 643,
      "student_teacher_ratio": 15.5
    },
    "ai_summary": "A walkable, family-friendly neighborhood ...",
    "metadata": {
      "last_updated": "2026-07-26",
      "cache_hit": false
    }
  }
}

[ RATING FIELDS ]

What each rating means

Eight components plus an overall. Climate is not a rating; it is returned as an objective facts block (see /v1/climate).

overallWeighted blend of the categories below.[ COMPOSITE ]

walkabilityErrand density and intersection connectivity.[ EPA WALKABILITY INDEX ]

bikeabilityProtected lane coverage per square kilometer.[ OSM LANE DENSITY ]

safetyInverse of the county violent crime rate.[ FBI VIOLENT CRIME ]

schoolsPublic K-12 student-teacher ratio and Title I share.[ NCES COMMON CORE OF DATA ]

family_friendlySafety, schools, parks, and walkability combined.[ COMPOSITE ]

population_densityPersons per square mile against the national median.[ CENSUS / ZIP AREA ]

affordabilityMedian household income against local rent.[ CENSUS ACS ]

nightlifeBars, venues, and restaurants within range.[ OSM VENUE COUNTS ]

[ STATUS CODES ]

Errors

200OKProfile returned.

400Bad requestMissing or malformed parameters.

401UnauthorizedMissing or invalid API key.

404Not foundZip or address could not be resolved.

429Rate limitedBurst limit or monthly quota exceeded. Retry after the reset window.

[ RATE LIMITS ]

Throughput

A per-key burst limit and an account-wide monthly quota, both set by your plan. Past your quota, requests return 429 until the next cycle. Upgrade any time for a higher allowance.

Plan	Burst	Monthly quota
Free	30 / min	1,000 / mo
Standard	60 / min	25,000 / mo
Growth	200 / min	150,000 / mo
Business	600 / min	1,000,000 / mo

See full pricing for what each plan includes.

[ CACHING ]

Every request counts

Every profile is cached per zip, so a cache hit returns in tens of milliseconds (look for X-Cache: HIT). Caching is a latency optimization, not a billing one. Every request counts toward your quota, cache hit or miss, success or error.

[ VERSIONING ]

API versioning

The API is versioned in the URL under /v1. Breaking changes ship as a new prefix (/v2) so existing integrations keep working. Each response also reports its underlying dataset vintages in metadata.data_sources (e.g. “FBI UCR 2023”, “NOAA Normals 1991–2020”).

[ GET API KEY ]