{ "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": "Paid API keys from $19/month (Starter: 60,000 calls a month); free tier 200 calls a day per IP with no key. Buy: https://ziplore.cybermaxtools.com/buy/starter?s=lead · all plans: https://ziplore.cybermaxtools.com/docs#pricing\n\nPricing: free tier 200 calls/day per IP, no key. Paid API keys: Starter $19/month = 60,000 calls/month; Pro $39/month = 250,000 calls/month; Pay as you go $5 = 12,000 calls (one-time pack); Starter yearly $190/year = 60,000 calls/month; Pro yearly $390/year = 250,000 calls/month. Get a key: https://ziplore.cybermaxtools.com/docs#pricing\n\nLook 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 tier: 200 calls a day per IP, no key; paid API keys from $19/month (or $5 pay-as-you-go) lift it. The whole ZIP table lives in memory at the edge, so calls take milliseconds. No key needed. Remote MCP server: https://ziplore.cybermaxtools.com/mcp", "contact": { "name": "CyberMax", "url": "https://cybermax-tools-cybermax.static.hf.space/" }, "license": { "name": "Proprietary (free tier + paid API keys)", "identifier": "LicenseRef-CyberMax" }, "x-x402": { "protocol": "x402", "versions": [ 1, 2 ], "scheme": "exact", "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": { "perCallUsd": 0.002 }, "payPerCallEndpoints": [ "/x402/api/zip", "/x402/api/radius", "/x402/api/city", "/x402/api/nearest", "/x402/api/distance" ], "alsoOn": "the plain endpoints answer 402 with the same terms once the free daily quota is used up (no key sent)", "headers": { "request": [ "X-PAYMENT (v1)", "PAYMENT-SIGNATURE (v2)" ], "response": [ "X-PAYMENT-RESPONSE", "PAYMENT-RESPONSE" ] } }, "x-pricing": { "api": "Ziplore API", "currency": "USD", "free": { "price": 0, "callsPerDayPerIp": 200, "perMinutePerIp": 20, "key": "none needed" }, "plans": [ { "id": "starter", "name": "Starter", "price": 19, "billing": "per month", "calls": 60000, "per": "calendar month (UTC)", "perMinute": 120, "buy": "https://ziplore.cybermaxtools.com/buy/starter?s=openapi" }, { "id": "pro", "name": "Pro", "price": 39, "billing": "per month", "calls": 250000, "per": "calendar month (UTC)", "perMinute": 300, "buy": "https://ziplore.cybermaxtools.com/buy/pro?s=openapi" }, { "id": "pack", "name": "Pay as you go", "price": 5, "billing": "one-time", "calls": 12000, "per": "until used", "perMinute": 120, "buy": "https://ziplore.cybermaxtools.com/buy/pack?s=openapi" }, { "id": "starter-yearly", "name": "Starter yearly", "price": 190, "billing": "per year", "calls": 60000, "per": "calendar month (UTC)", "perMinute": 120, "buy": "https://ziplore.cybermaxtools.com/buy/starter-yearly?s=openapi" }, { "id": "pro-yearly", "name": "Pro yearly", "price": 390, "billing": "per year", "calls": 250000, "per": "calendar month (UTC)", "perMinute": 300, "buy": "https://ziplore.cybermaxtools.com/buy/pro-yearly?s=openapi" } ], "unit": "calls", "howToUse": { "header": "x-api-key: YOUR_KEY", "alt": [ "Authorization: Bearer YOUR_KEY", "?key=YOUR_KEY" ], "mcp": "send the key as Authorization: Bearer YOUR_KEY", "usage": "https://ziplore.cybermaxtools.com/key" }, "manageKey": "https://ziplore.cybermaxtools.com/manage", "payments": "Stripe Checkout: card, Apple Pay, Google Pay, Link; sales tax/VAT handled by Stripe. Cancel any time at https://ziplore.cybermaxtools.com/manage." } }, "servers": [ { "url": "https://ziplore.cybermaxtools.com" }, { "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (200/day per IP) or rate/plan limit reached; the body has an upgrade link.", "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" } } } } } } }, "/x402/api/zip": { "get": { "tags": [ "Ziplore" ], "summary": "Look up up to 10 US ZIP codes (pay per call in USDC via x402, no key)", "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).\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "lookupZipsGetPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Ziplore" ], "summary": "Look up up to 10 US ZIP codes (pay per call in USDC via x402, no key)", "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).\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "lookupZipsPostPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } }, "/x402/api/radius": { "get": { "tags": [ "Ziplore" ], "summary": "Every ZIP within N miles of a ZIP or point (pay per call in USDC via x402, no key)", "description": "Closest first, with distance in miles. Radius up to 25 miles and 50 results on the free API.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "zipsInRadiusGetPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Ziplore" ], "summary": "Every ZIP within N miles of a ZIP or point (pay per call in USDC via x402, no key)", "description": "Closest first, with distance in miles. Radius up to 25 miles and 50 results on the free API.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "zipsInRadiusPostPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } }, "/x402/api/city": { "get": { "tags": [ "Ziplore" ], "summary": "Every ZIP of a city, largest first (pay per call in USDC via x402, no key)", "description": "All ZIP codes of a city and state, sorted by population.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "cityZipsGetPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Ziplore" ], "summary": "Every ZIP of a city, largest first (pay per call in USDC via x402, no key)", "description": "All ZIP codes of a city and state, sorted by population.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "cityZipsPostPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } }, "/x402/api/nearest": { "get": { "tags": [ "Ziplore" ], "summary": "Nearest ZIP to a point (reverse geocode) (pay per call in USDC via x402, no key)", "description": "The closest residential ZIP (or up to 10) to a latitude/longitude, with distance.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "nearestZipGetPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Ziplore" ], "summary": "Nearest ZIP to a point (reverse geocode) (pay per call in USDC via x402, no key)", "description": "The closest residential ZIP (or up to 10) to a latitude/longitude, with distance.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "nearestZipPostPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } }, "/x402/api/distance": { "get": { "tags": [ "Ziplore" ], "summary": "Distance between two ZIPs (pay per call in USDC via x402, no key)", "description": "Great-circle distance in miles and kilometers between two ZIP centroids.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "zipDistanceGetPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Ziplore" ], "summary": "Distance between two ZIPs (pay per call in USDC via x402, no key)", "description": "Great-circle distance in miles and kilometers between two ZIP centroids.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "zipDistancePostPayPerCall", "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" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": "integer" }, "limits": { "type": "object" } }, "required": [ "error", "message" ] } }, "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Optional. Paid plan key from https://ziplore.cybermaxtools.com/docs#pricing; leave out for the free tier." }, "BearerKey": { "type": "http", "scheme": "bearer", "description": "Same key as a Bearer token." } } }, "x-mcp-server": "https://ziplore.cybermaxtools.com/mcp", "externalDocs": { "description": "Get an API key (pricing)", "url": "https://ziplore.cybermaxtools.com/docs#pricing" }, "security": [ {}, { "ApiKeyHeader": [] }, { "BearerKey": [] } ] }