{"openapi":"3.1.0","info":{"title":"zipcodes.pro API","version":"1.0.0","description":"US ZIP code data: lookup, radius search, distance and bulk append.\n\nEvery response carries the data `release` it came from, so you can pin your own cache to it.\n\n**A null value means the source did not publish that figure for that ZIP code. It never means zero.**\n\nFree keys are instant at https://zipcodes.pro/api/key: 1,000 requests a day, reset at 00:00 UTC. Exceeding your quota returns 429 with the reset time. Nothing is billed beyond your plan.","contact":{"url":"https://zipcodes.pro/api/docs"},"license":{"name":"See https://zipcodes.pro/license","url":"https://zipcodes.pro/license"}},"servers":[{"url":"https://zipcodes.pro"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key: `Authorization: Bearer zk_live_...`"}},"schemas":{"Zip":{"type":"object","properties":{"zip":{"type":"string","example":"95014"},"type":{"type":"string","enum":["standard","po_box","unique","military","unknown"]},"type_source":{"type":"string","enum":["usps_hud","inferred"],"description":"Where `type` came from. `inferred` means it was derived from public geography rather than USPS data."},"city":{"type":["string","null"]},"other_place_names":{"type":"array","items":{"type":"string"}},"state":{"type":"string","example":"CA"},"county":{"type":["object","null"]},"counties":{"type":"array","description":"Every county the ZIP code touches, with a weight and the measure that weight is based on. A ZIP code can span county lines."},"location":{"type":["object","null"]},"is_zcta":{"type":"boolean"},"demographics":{"type":"object","description":"Census estimates for the ZIP Code Tabulation Area. Every field is null for a ZIP code with no ZCTA (PO box, unique, military) — null means not measured, never zero."},"business":{"type":"object"},"release":{"type":"string","example":"2026-09-25"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string"},"docs":{"type":"string"},"upgrade":{"type":"string"},"retry_after_seconds":{"type":"integer"}},"required":["error","message"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Quota exhausted (`quota_exceeded`) or too many requests this minute (`rate_limited`). The two are different: one needs an upgrade, the other needs a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/zip/{zip}":{"get":{"summary":"One ZIP code","operationId":"getZip","parameters":[{"name":"zip","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{5}$"},"example":"95014"}],"responses":{"200":{"description":"The ZIP code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Zip"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No such ZIP code in this release."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/zips":{"get":{"summary":"Every ZIP code for a city","operationId":"getZipsByCity","parameters":[{"name":"city","in":"query","required":true,"schema":{"type":"string"},"example":"Cupertino"},{"name":"state","in":"query","required":true,"schema":{"type":"string"},"example":"CA"}],"responses":{"200":{"description":"Matching ZIP codes."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/radius":{"get":{"summary":"ZIP codes within a radius","description":"Great-circle distance between published centre points, nearest first. Not driving distance.","operationId":"getRadius","parameters":[{"name":"zip","in":"query","schema":{"type":"string"},"example":"95014"},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"miles","in":"query","schema":{"type":"number","maximum":500},"example":25}],"responses":{"200":{"description":"ZIP codes inside the radius."},"400":{"description":"Bad parameters."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/distance":{"get":{"summary":"Distance between two ZIP codes","operationId":"getDistance","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string"},"example":"95014"},{"name":"to","in":"query","required":true,"schema":{"type":"string"},"example":"10001"}],"responses":{"200":{"description":"Miles and kilometres."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/bulk":{"post":{"summary":"Up to 1,000 ZIP codes in one request","description":"Results are returned in the order requested, with nulls for ZIP codes that do not exist, so the array lines up with what you sent.","operationId":"postBulk","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zips":{"type":"array","items":{"type":"string"}}},"required":["zips"]}}}},"responses":{"200":{"description":"Results in request order."},"400":{"description":"Too many ZIP codes for your plan."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/county/{fips}/zips":{"get":{"summary":"Every ZIP code in a county","operationId":"getCountyZips","parameters":[{"name":"fips","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{5}$"},"example":"06085"}],"responses":{"200":{"description":"ZIP codes in the county."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/meta":{"get":{"summary":"Current release, sources and coverage","description":"What this data is, where it came from, and which fields are incomplete and why.","operationId":"getMeta","responses":{"200":{"description":"Release metadata."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/usage":{"get":{"summary":"Your usage this period","operationId":"getUsage","responses":{"200":{"description":"Requests used, remaining and per day."},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"x-plans":[{"id":"free","name":"Free","requests":1000,"quota_window":"day","requests_per_month":null,"requests_per_minute":60,"usd_monthly":0,"usd_yearly":0,"max_bulk":100,"browser_cors":true},{"id":"starter","name":"Starter","requests":100000,"quota_window":"month","requests_per_month":100000,"requests_per_minute":120,"usd_monthly":19,"usd_yearly":182,"max_bulk":1000,"browser_cors":true},{"id":"pro","name":"Pro","requests":500000,"quota_window":"month","requests_per_month":500000,"requests_per_minute":600,"usd_monthly":49,"usd_yearly":470,"max_bulk":1000,"browser_cors":false},{"id":"business","name":"Business","requests":3000000,"quota_window":"month","requests_per_month":3000000,"requests_per_minute":2000,"usd_monthly":149,"usd_yearly":1430,"max_bulk":1000,"browser_cors":false}]}