{ "openapi": "3.1.0", "info": { "title": "Ziplore API", "version": "1.0.0", "summary": "Free US ZIP code API and MCP server: ZIP to city, county, FIPS, coordinates, time zone and Census demographics, plus radius search, city ZIPs, reverse lookup and distance. 41,682 ZIPs.", "description": "Look up any US ZIP and get one clean record: city, state, county and FIPS, coordinates, time zone with today's UTC offset, and Census demographics. Also every ZIP within N miles, every ZIP of a city, the nearest ZIP to a point and ZIP-to-ZIP distance.\n\nFree tier: 20 calls per minute per IP address. Up to 10 ZIPs per lookup call. Radius up to 25 miles, up to 50 results per call. Free, no key, no sign-up. The whole ZIP table lives in memory at the edge, so calls take milliseconds. No key needed. Remote MCP server: https://ziplore.cybermax-tools.workers.dev/mcp", "contact": { "name": "CyberMax", "url": "https://cybermax-tools-cybermax.static.hf.space/" }, "license": { "name": "Proprietary (free to call)", "identifier": "LicenseRef-CyberMax" } }, "servers": [ { "url": "https://ziplore.cybermax-tools.workers.dev" } ], "paths": { "/api/zip": { "get": { "tags": [ "Ziplore" ], "summary": "Look up up to 10 US ZIP codes", "description": "City, state, county + FIPS, coordinates, IANA time zone with today's UTC offset, ZIP kind, and Census ACS demographics (population, density, median age, household and per-capita income, median home value and rent, owner-occupied share).", "operationId": "lookupZipsGet", "parameters": [ { "name": "zip", "in": "query", "required": true, "description": "Up to 10 ZIPs, comma separated", "schema": { "type": "string" }, "example": "10001,90210,7102" }, { "name": "demographics", "in": "query", "required": false, "description": "Include Census demographics (default true)", "schema": { "type": "boolean", "default": true } }, { "name": "nearby", "in": "query", "required": false, "description": "Also list the N closest ZIPs per record (0-5)", "schema": { "type": "integer", "minimum": 0, "maximum": 5, "default": 0 } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "query": "10001", "zip": "10001", "city": "New York", "state": "NY", "stateName": "New York", "county": "New York County", "countyFips": "36061", "stateFips": "36", "latitude": 40.7484, "longitude": -73.9967, "timezone": "America/New_York", "utcOffset": "-04:00", "observesDst": true, "zipKind": "area", "population": 30511, "populationDensity": 48895.8, "medianAge": 35.8, "medianHouseholdIncome": 129852, "perCapitaIncome": 120099, "medianHomeValue": 561100, "medianGrossRent": 3361, "housingUnits": 18356, "ownerOccupiedPct": 24.1, "landSqMi": 0.624, "waterSqMi": 0, "counties": [ { "fips": "36061", "landShare": 1 } ] }, { "query": "90210", "zip": "90210", "city": "Beverly Hills", "state": "CA", "stateName": "California", "county": "Los Angeles County", "countyFips": "06037", "stateFips": "06", "latitude": 34.0901, "longitude": -118.4065, "timezone": "America/Los_Angeles", "utcOffset": "-07:00", "observesDst": true, "zipKind": "area", "population": 19004, "populationDensity": 1768.1, "medianAge": 51.9, "medianHouseholdIncome": 187801, "perCapitaIncome": 147098, "medianHomeValue": 2000000, "medianGrossRent": 3251, "housingUnits": 9531, "ownerOccupiedPct": 70.7, "landSqMi": 10.748, "waterSqMi": 0.054, "topCoded": [ "medianHomeValue" ], "counties": [ { "fips": "06037", "landShare": 1 } ] }, { "query": "7102", "zip": "07102", "city": "Newark", "state": "NJ", "stateName": "New Jersey", "county": "Essex County", "countyFips": "34013", "stateFips": "34", "latitude": 40.732, "longitude": -74.1765, "timezone": "America/New_York", "utcOffset": "-04:00", "observesDst": true, "zipKind": "area", "population": 12358, "populationDensity": 10926.6, "medianAge": 33.7, "medianHouseholdIncome": 38864, "perCapitaIncome": 33907, "medianHomeValue": 431500, "medianGrossRent": 1265, "housingUnits": 6683, "ownerOccupiedPct": 6, "landSqMi": 1.131, "waterSqMi": 0.021, "counties": [ { "fips": "34013", "landShare": 1 } ] } ], "count": 3, "notFound": [], "meta": { "sources": { "zipCodes": "GeoNames postal codes (2026-09-24)", "areas": "US Census 2024 Gazetteer (ZCTA)", "demographics": "American Community Survey 2020–2024 5-year estimates", "counties": "US Census 2020 ZCTA-to-county relationship file" }, "attribution": "ZIP data: GeoNames (CC BY 4.0), US Census Bureau; time zones: timezone-boundary-builder (ODbL, © OpenStreetMap contributors).", "dataBuiltAt": "2026-09-26T00:23:52.950Z", "version": "1.0.0" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Ziplore" ], "summary": "Look up up to 10 US ZIP codes", "description": "City, state, county + FIPS, coordinates, IANA time zone with today's UTC offset, ZIP kind, and Census ACS demographics (population, density, median age, household and per-capita income, median home value and rent, owner-occupied share).", "operationId": "lookupZipsPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "zips": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10, "description": "US ZIP codes (ZIP+4, addresses and ZIPs that lost their leading zero are accepted). Up to 10." }, "demographics": { "type": "boolean" }, "nearby": { "type": "integer", "minimum": 0, "maximum": 5 } }, "required": [ "zips" ] }, "example": { "zips": [ "10001", "90210", "7102" ] } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "query": "10001", "zip": "10001", "city": "New York", "state": "NY", "stateName": "New York", "county": "New York County", "countyFips": "36061", "stateFips": "36", "latitude": 40.7484, "longitude": -73.9967, "timezone": "America/New_York", "utcOffset": "-04:00", "observesDst": true, "zipKind": "area", "population": 30511, "populationDensity": 48895.8, "medianAge": 35.8, "medianHouseholdIncome": 129852, "perCapitaIncome": 120099, "medianHomeValue": 561100, "medianGrossRent": 3361, "housingUnits": 18356, "ownerOccupiedPct": 24.1, "landSqMi": 0.624, "waterSqMi": 0, "counties": [ { "fips": "36061", "landShare": 1 } ] }, { "query": "90210", "zip": "90210", "city": "Beverly Hills", "state": "CA", "stateName": "California", "county": "Los Angeles County", "countyFips": "06037", "stateFips": "06", "latitude": 34.0901, "longitude": -118.4065, "timezone": "America/Los_Angeles", "utcOffset": "-07:00", "observesDst": true, "zipKind": "area", "population": 19004, "populationDensity": 1768.1, "medianAge": 51.9, "medianHouseholdIncome": 187801, "perCapitaIncome": 147098, "medianHomeValue": 2000000, "medianGrossRent": 3251, "housingUnits": 9531, "ownerOccupiedPct": 70.7, "landSqMi": 10.748, "waterSqMi": 0.054, "topCoded": [ "medianHomeValue" ], "counties": [ { "fips": "06037", "landShare": 1 } ] }, { "query": "7102", "zip": "07102", "city": "Newark", "state": "NJ", "stateName": "New Jersey", "county": "Essex County", "countyFips": "34013", "stateFips": "34", "latitude": 40.732, "longitude": -74.1765, "timezone": "America/New_York", "utcOffset": "-04:00", "observesDst": true, "zipKind": "area", "population": 12358, "populationDensity": 10926.6, "medianAge": 33.7, "medianHouseholdIncome": 38864, "perCapitaIncome": 33907, "medianHomeValue": 431500, "medianGrossRent": 1265, "housingUnits": 6683, "ownerOccupiedPct": 6, "landSqMi": 1.131, "waterSqMi": 0.021, "counties": [ { "fips": "34013", "landShare": 1 } ] } ], "count": 3, "notFound": [], "meta": { "sources": { "zipCodes": "GeoNames postal codes (2026-09-24)", "areas": "US Census 2024 Gazetteer (ZCTA)", "demographics": "American Community Survey 2020–2024 5-year estimates", "counties": "US Census 2020 ZCTA-to-county relationship file" }, "attribution": "ZIP data: GeoNames (CC BY 4.0), US Census Bureau; time zones: timezone-boundary-builder (ODbL, © OpenStreetMap contributors).", "dataBuiltAt": "2026-09-26T00:23:52.950Z", "version": "1.0.0" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/radius": { "get": { "tags": [ "Ziplore" ], "summary": "Every ZIP within N miles of a ZIP or point", "description": "Closest first, with distance in miles. Radius up to 25 miles and 50 results on the free API.", "operationId": "zipsInRadiusGet", "parameters": [ { "name": "zip", "in": "query", "required": false, "description": "Center ZIP (or give lat + lon)", "schema": { "type": "string" }, "example": "60614" }, { "name": "lat", "in": "query", "required": false, "description": "Center latitude", "schema": { "type": "number" } }, { "name": "lon", "in": "query", "required": false, "description": "Center longitude", "schema": { "type": "number" } }, { "name": "miles", "in": "query", "required": true, "description": "Radius in miles (0.1-25)", "schema": { "type": "number", "minimum": 0.1, "maximum": 25 }, "example": 3 }, { "name": "limit", "in": "query", "required": false, "description": "Max results (1-50, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "minPopulation", "in": "query", "required": false, "description": "Skip ZIPs with fewer residents", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Ziplore" ], "summary": "Every ZIP within N miles of a ZIP or point", "description": "Closest first, with distance in miles. Radius up to 25 miles and 50 results on the free API.", "operationId": "zipsInRadiusPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "zip": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "miles": { "type": "number", "minimum": 0.1, "maximum": 25 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "miles" ] }, "example": { "zip": "60614", "miles": 3 } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/city": { "get": { "tags": [ "Ziplore" ], "summary": "Every ZIP of a city, largest first", "description": "All ZIP codes of a city and state, sorted by population.", "operationId": "cityZipsGet", "parameters": [ { "name": "city", "in": "query", "required": true, "description": "City name", "schema": { "type": "string" }, "example": "Austin" }, { "name": "state", "in": "query", "required": false, "description": "2-letter state code or name", "schema": { "type": "string" }, "example": "TX" }, { "name": "limit", "in": "query", "required": false, "description": "Max results (1-50, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Ziplore" ], "summary": "Every ZIP of a city, largest first", "description": "All ZIP codes of a city and state, sorted by population.", "operationId": "cityZipsPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "city" ] }, "example": { "city": "Austin", "state": "TX" } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/nearest": { "get": { "tags": [ "Ziplore" ], "summary": "Nearest ZIP to a point (reverse geocode)", "description": "The closest residential ZIP (or up to 10) to a latitude/longitude, with distance.", "operationId": "nearestZipGet", "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude", "schema": { "type": "number" }, "example": 40.7484 }, { "name": "lon", "in": "query", "required": true, "description": "Longitude", "schema": { "type": "number" }, "example": -73.9967 }, { "name": "count", "in": "query", "required": false, "description": "How many ZIPs (1-10)", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Ziplore" ], "summary": "Nearest ZIP to a point (reverse geocode)", "description": "The closest residential ZIP (or up to 10) to a latitude/longitude, with distance.", "operationId": "nearestZipPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "count": { "type": "integer" } }, "required": [ "lat", "lon" ] }, "example": { "lat": 40.7484, "lon": -73.9967 } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/distance": { "get": { "tags": [ "Ziplore" ], "summary": "Distance between two ZIPs", "description": "Great-circle distance in miles and kilometers between two ZIP centroids.", "operationId": "zipDistanceGet", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First ZIP", "schema": { "type": "string" }, "example": "10001" }, { "name": "to", "in": "query", "required": true, "description": "Second ZIP", "schema": { "type": "string" }, "example": "90210" } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Ziplore" ], "summary": "Distance between two ZIPs", "description": "Great-circle distance in miles and kilometers between two ZIP centroids.", "operationId": "zipDistancePost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "example": { "from": "10001", "to": "90210" } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": "integer" }, "limits": { "type": "object" } }, "required": [ "error", "message" ] } } }, "x-mcp-server": "https://ziplore.cybermax-tools.workers.dev/mcp" }