{ "openapi": "3.0.4", "info": { "title": "ZIP Codes API", "description": "Comprehensive US ZIP code and Canadian postal code lookup API with enrichments including census data, ACS demographics, timezone, school districts, and radius search.", "termsOfService": "https://www.zip-codes.com/zip-code-api-tos.asp", "contact": { "name": "ZIP Codes API Support", "url": "https://www.zip-codes.com", "email": "info@zip-codes.com" }, "version": "2.0.0" }, "paths": { "/v2/address": { "get": { "tags": [ "Address" ], "operationId": "Address", "parameters": [ { "name": "address", "in": "query", "schema": { "type": "string" } }, { "name": "include", "in": "query", "schema": { "type": "string" } }, { "name": "debug", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResultApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResultApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } }, "post": { "tags": [ "Address" ], "operationId": "AddressPost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResultApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResultApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/address/batch": { "post": { "tags": [ "Address" ], "operationId": "AddressBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBatchItemResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBatchItemResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/distance": { "get": { "tags": [ "Distance" ], "operationId": "Distance", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } }, "post": { "tags": [ "Distance" ], "operationId": "DistancePost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistancePostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/distance/batch": { "post": { "tags": [ "Distance" ], "operationId": "DistanceBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistanceResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/quick-zip": { "get": { "tags": [ "Quick ZIP" ], "operationId": "QuickZip", "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "include", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } }, "post": { "tags": [ "Quick ZIP" ], "operationId": "QuickZipPost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/quick-zip/batch": { "post": { "tags": [ "Quick ZIP" ], "operationId": "QuickZipBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickZipResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/radius": { "get": { "tags": [ "Radius Search" ], "operationId": "Radius", "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "max", "in": "query", "schema": { "type": "string" } }, { "name": "min", "in": "query", "schema": { "type": "string" } }, { "name": "include", "in": "query", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } }, "post": { "tags": [ "Radius Search" ], "operationId": "RadiusPost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/radius/batch": { "post": { "tags": [ "Radius Search" ], "operationId": "RadiusBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/suggest": { "get": { "tags": [ "Suggest" ], "operationId": "Suggest", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "include", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "proximity", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } }, "post": { "tags": [ "Suggest" ], "operationId": "SuggestPost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/health": { "get": { "tags": [ "System" ], "operationId": "Health", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResultApiResponse" } } } } } } }, "/v2/zip": { "get": { "tags": [ "ZIP Lookup" ], "operationId": "Zip", "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "include", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } }, "post": { "tags": [ "ZIP Lookup" ], "operationId": "ZipPost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } }, "/v2/zip/batch": { "post": { "tags": [ "ZIP Lookup" ], "operationId": "ZipBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipResultBatchItemApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipResultBatchItemApiResponse" } } } }, "429": { "description": "Rate limit exceeded. Check Retry-After header for when to retry." } } } } }, "components": { "schemas": { "AddressBatchItemResult": { "type": "object", "properties": { "matched": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/AddressMatchData" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/AddressNotice" }, "nullable": true } }, "additionalProperties": false }, "AddressBatchItemResultBatchItem": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true } }, "additionalProperties": false, "description": "Batch result item. On success, AddressBatchItemResult properties are merged inline (not nested under 'data'). On failure, only success, input, and error are present." }, "AddressBatchItemResultBatchItemApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AddressBatchItemResultBatchItem" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "AddressBatchRequest": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "nullable": true }, "include": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AddressComponents": { "type": "object", "properties": { "number": { "type": "string", "nullable": true }, "pre_directional": { "type": "string", "nullable": true }, "street": { "type": "string", "nullable": true }, "street_pre_type": { "type": "string", "nullable": true }, "suffix": { "type": "string", "nullable": true }, "post_directional": { "type": "string", "nullable": true }, "secondary_type": { "type": "string", "nullable": true }, "secondary_number": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "plus4": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AddressLocation": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } }, "additionalProperties": false }, "AddressMatchData": { "type": "object", "properties": { "confidence": { "type": "string", "nullable": true }, "formatted_address": { "type": "string", "nullable": true }, "address_line1": { "type": "string", "nullable": true }, "address_line2": { "type": "string", "nullable": true }, "recipient_name": { "type": "string", "nullable": true }, "attention_line": { "type": "string", "nullable": true }, "address_components": { "$ref": "#/components/schemas/AddressComponents" }, "location": { "$ref": "#/components/schemas/AddressLocation" }, "details": { "$ref": "#/components/schemas/MatchDetails" }, "pbsa_indicator": { "type": "boolean" } }, "additionalProperties": false }, "AddressNotice": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "class": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AddressPostRequest": { "type": "object", "properties": { "address": { "type": "string", "nullable": true }, "include": { "type": "string", "nullable": true }, "debug_key": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AddressResult": { "type": "object", "properties": { "input": { "type": "string", "nullable": true }, "success": { "type": "boolean" }, "error": { "$ref": "#/components/schemas/AddressResultError" }, "data": { "$ref": "#/components/schemas/AddressMatchData" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/AddressNotice" }, "nullable": true } }, "additionalProperties": false }, "AddressResultApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AddressResult" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "AddressResultError": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AgeInfo": { "type": "object", "properties": { "median": { "type": "number", "format": "double", "nullable": true }, "median_male": { "type": "number", "format": "double", "nullable": true }, "median_female": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false }, "ApiError": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "retryable": { "type": "boolean", "nullable": true } }, "additionalProperties": false }, "ApiMeta": { "type": "object", "properties": { "request_id": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true }, "timing_ms": { "type": "integer", "format": "int64" }, "credits": { "$ref": "#/components/schemas/CreditsMeta" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true }, "batch": { "$ref": "#/components/schemas/BatchMeta" }, "rate_limit": { "$ref": "#/components/schemas/RateLimitMeta" }, "debug": { "nullable": true } }, "additionalProperties": false }, "ApiNotice": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "class": { "type": "string", "nullable": true } }, "additionalProperties": false }, "BatchMeta": { "type": "object", "properties": { "requested": { "type": "integer", "format": "int32" }, "succeeded": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "BboxResult": { "type": "object", "properties": { "min_lat": { "type": "number", "format": "double" }, "max_lat": { "type": "number", "format": "double" }, "min_lon": { "type": "number", "format": "double" }, "max_lon": { "type": "number", "format": "double" } }, "additionalProperties": false }, "BusinessInfo": { "type": "object", "properties": { "establishments": { "type": "integer", "format": "int32", "nullable": true }, "employees": { "type": "integer", "format": "int32", "nullable": true }, "payroll_q1": { "type": "integer", "format": "int64", "nullable": true }, "payroll_annual": { "type": "integer", "format": "int64", "nullable": true }, "employment_flag": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CityAlias": { "type": "object", "properties": { "city": { "type": "string", "nullable": true }, "mailing_name": { "type": "string", "nullable": true }, "intro_date": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CodeDescription": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CountyInfo": { "type": "object", "properties": { "fips": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreditBreakdown": { "type": "object", "properties": { "base": { "type": "integer", "format": "int32" }, "enrichments": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "nullable": true }, "calculation": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreditsMeta": { "type": "object", "properties": { "used": { "type": "integer", "format": "int32" }, "source": { "type": "string", "nullable": true }, "remaining": { "type": "integer", "format": "int32", "nullable": true }, "breakdown": { "$ref": "#/components/schemas/CreditBreakdown" } }, "additionalProperties": false }, "DatabaseHealth": { "type": "object", "properties": { "connected": { "type": "boolean" }, "latencyMs": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "DeliveryPoints": { "type": "object", "properties": { "total_active": { "type": "integer", "format": "int32", "nullable": true }, "business": { "type": "integer", "format": "int32", "nullable": true }, "residential": { "type": "integer", "format": "int32", "nullable": true }, "po_box": { "type": "integer", "format": "int32", "nullable": true }, "single_family": { "type": "integer", "format": "int32", "nullable": true }, "multi_family": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "DistanceBatchRequest": { "type": "object", "properties": { "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/DistancePair" }, "nullable": true } }, "additionalProperties": false }, "DistanceMeasure": { "type": "object", "properties": { "miles": { "type": "number", "format": "double" }, "km": { "type": "number", "format": "double" } }, "additionalProperties": false }, "DistancePair": { "type": "object", "properties": { "from": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true } }, "additionalProperties": false }, "DistancePoint": { "type": "object", "properties": { "country": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "code_type": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "location": { "$ref": "#/components/schemas/LocationResult" }, "timezone": { "$ref": "#/components/schemas/TimezoneResult" }, "input_type": { "type": "string", "nullable": true } }, "additionalProperties": false }, "DistancePostRequest": { "type": "object", "properties": { "from": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true } }, "additionalProperties": false }, "DistanceResult": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/DistancePoint" }, "to": { "$ref": "#/components/schemas/DistancePoint" }, "distance": { "$ref": "#/components/schemas/DistanceMeasure" }, "bearing": { "type": "number", "format": "double" } }, "additionalProperties": false }, "DistanceResultBatchItem": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true } }, "additionalProperties": false, "description": "Batch result item. On success, DistanceResult properties are merged inline (not nested under 'data'). On failure, only success, input, and error are present." }, "DistanceResultBatchItemApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DistanceResultBatchItem" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "HealthResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "database": { "$ref": "#/components/schemas/DatabaseHealth" }, "version": { "type": "string", "nullable": true }, "coordObfuscatorReady": { "type": "boolean" } }, "additionalProperties": false }, "HealthResultApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/HealthResult" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "HouseholdInfo": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "nullable": true }, "persons_per_household": { "type": "number", "format": "double", "nullable": true }, "average_family_size": { "type": "number", "format": "double", "nullable": true }, "median_income": { "type": "integer", "format": "int32", "nullable": true }, "average_home_value": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "LocationResult": { "type": "object", "properties": { "lat": { "type": "number", "format": "double", "nullable": true }, "lon": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false }, "MatchDetails": { "type": "object", "properties": { "record_type": { "$ref": "#/components/schemas/CodeDescription" }, "carrier_route": { "$ref": "#/components/schemas/CodeDescription" }, "facility": { "$ref": "#/components/schemas/CodeDescription" }, "county": { "$ref": "#/components/schemas/CountyInfo" }, "congressional_district": { "type": "string", "nullable": true }, "location_block_group": { "type": "string", "nullable": true }, "finance_number": { "type": "string", "nullable": true }, "building_name": { "type": "string", "nullable": true }, "government_building": { "type": "boolean" }, "base_alternate_code": { "type": "string", "nullable": true }, "lacs_status": { "type": "string", "nullable": true }, "municipality_key": { "type": "string", "nullable": true }, "urbanization_key": { "type": "string", "nullable": true }, "preferred_last_line_key": { "type": "string", "nullable": true } }, "additionalProperties": false }, "MedicareInfo": { "type": "object", "properties": { "cbsa_code": { "type": "string", "nullable": true }, "cbsa_name": { "type": "string", "nullable": true }, "cbsa_type": { "type": "string", "nullable": true }, "rating_area_id": { "type": "string", "nullable": true }, "ssa_state_county_code": { "type": "string", "nullable": true }, "multi_county_notice": { "type": "string", "nullable": true } }, "additionalProperties": false }, "MetroStatisticalInfo": { "type": "object", "properties": { "region": { "type": "string", "nullable": true }, "division": { "type": "string", "nullable": true }, "csa": { "type": "string", "nullable": true }, "csa_name": { "type": "string", "nullable": true }, "msa": { "type": "string", "nullable": true }, "msa_name": { "type": "string", "nullable": true }, "pmsa": { "type": "string", "nullable": true }, "pmsa_name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PopulationInfo": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "nullable": true }, "estimate": { "type": "integer", "format": "int32", "nullable": true }, "male": { "type": "integer", "format": "int32", "nullable": true }, "female": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "PostalInfo": { "type": "object", "properties": { "record_type": { "type": "string", "nullable": true }, "address_type": { "type": "string", "nullable": true }, "fsa": { "type": "string", "nullable": true }, "delivery_postal_code": { "type": "string", "nullable": true }, "fsa_population": { "type": "integer", "format": "int32", "nullable": true }, "fsa_dwellings": { "type": "integer", "format": "int32", "nullable": true }, "fsa_dwellings_occupied": { "type": "integer", "format": "int32", "nullable": true }, "fsa_postal_code_count": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "QuickZipBatchRequest": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "include": { "type": "string", "nullable": true } }, "additionalProperties": false }, "QuickZipDetail": { "type": "object", "properties": { "valid": { "type": "boolean" }, "zip4": { "type": "string", "nullable": true }, "record_type": { "type": "string", "nullable": true }, "address_type": { "type": "string", "nullable": true }, "delivery_postal_code": { "type": "string", "nullable": true }, "street": { "type": "array", "items": { "$ref": "#/components/schemas/StreetDetail" }, "nullable": true }, "fallback": { "type": "boolean" }, "input": { "type": "string", "nullable": true } }, "additionalProperties": false }, "QuickZipPostRequest": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "include": { "type": "string", "nullable": true } }, "additionalProperties": false }, "QuickZipResult": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "code_type": { "type": "string", "nullable": true }, "parent_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "state_name": { "type": "string", "nullable": true }, "state_fips": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "county_fips": { "type": "string", "nullable": true }, "multi_county": { "type": "boolean", "nullable": true }, "classification": { "type": "string", "nullable": true }, "classification_name": { "type": "string", "nullable": true }, "municipality": { "type": "string", "nullable": true }, "location": { "$ref": "#/components/schemas/LocationResult" }, "detail": { "$ref": "#/components/schemas/QuickZipDetail" }, "timezone": { "$ref": "#/components/schemas/TimezoneResult" } }, "additionalProperties": false }, "QuickZipResultBatchItem": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true } }, "additionalProperties": false, "description": "Batch result item. On success, QuickZipResult properties are merged inline (not nested under 'data'). On failure, only success, input, and error are present." }, "QuickZipResultBatchItemApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QuickZipResultBatchItem" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "RaceInfo": { "type": "object", "properties": { "white": { "type": "integer", "format": "int32", "nullable": true }, "black": { "type": "integer", "format": "int32", "nullable": true }, "hispanic": { "type": "integer", "format": "int32", "nullable": true }, "asian": { "type": "integer", "format": "int32", "nullable": true }, "american_indian": { "type": "integer", "format": "int32", "nullable": true }, "hawaiian_pacific_islander": { "type": "integer", "format": "int32", "nullable": true }, "other": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "RadiusBatchRequest": { "type": "object", "properties": { "searches": { "type": "array", "items": { "$ref": "#/components/schemas/RadiusSearchItem" }, "nullable": true }, "include": { "type": "string", "nullable": true }, "max": { "nullable": true }, "min": { "type": "number", "format": "double", "nullable": true }, "mode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "RadiusCenter": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "code_type": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "location": { "$ref": "#/components/schemas/LocationResult" } }, "additionalProperties": false }, "RadiusMatch": { "type": "object", "properties": { "country": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "code_type": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "county_fips": { "type": "string", "nullable": true }, "classification": { "type": "string", "nullable": true }, "classification_name": { "type": "string", "nullable": true }, "location": { "$ref": "#/components/schemas/LocationResult" }, "distance_miles": { "type": "number", "format": "double" }, "pct_inside": { "type": "number", "format": "double", "nullable": true }, "area_sq_mi": { "type": "number", "format": "double", "nullable": true }, "timezone": { "$ref": "#/components/schemas/TimezoneResult" } }, "additionalProperties": false }, "RadiusPostRequest": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "max": { "nullable": true }, "min": { "type": "number", "format": "double", "nullable": true }, "include": { "type": "string", "nullable": true }, "mode": { "type": "string", "nullable": true }, "limit": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "RadiusResult": { "type": "object", "properties": { "search": { "$ref": "#/components/schemas/RadiusSearchInfo" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/RadiusMatch" }, "nullable": true }, "summary": { "$ref": "#/components/schemas/RadiusSummary" }, "stats": { "$ref": "#/components/schemas/RadiusStats" }, "census": { "$ref": "#/components/schemas/ZipCensusWrapper" }, "school_district": { "$ref": "#/components/schemas/ZipSchoolDistrictSection" } }, "additionalProperties": false }, "RadiusResultBatchItem": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true } }, "additionalProperties": false, "description": "Batch result item. On success, RadiusResult properties are merged inline (not nested under 'data'). On failure, only success, input, and error are present." }, "RadiusResultBatchItemApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RadiusResultBatchItem" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "RadiusSearchInfo": { "type": "object", "properties": { "center": { "$ref": "#/components/schemas/RadiusCenter" }, "max": { "type": "number", "format": "double" }, "min": { "type": "number", "format": "double" }, "mode": { "type": "string", "nullable": true }, "auto_mode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "RadiusSearchItem": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "max": { "nullable": true }, "min": { "type": "number", "format": "double", "nullable": true }, "include": { "type": "string", "nullable": true }, "limit": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "RadiusStats": { "type": "object", "properties": { "acs": { "type": "object", "additionalProperties": { "nullable": true }, "nullable": true } }, "additionalProperties": false }, "RadiusSummary": { "type": "object", "properties": { "total_count": { "type": "integer", "format": "int32" }, "us_zip_count": { "type": "integer", "format": "int32" }, "ca_fsa_count": { "type": "integer", "format": "int32" }, "ca_postal_count": { "type": "integer", "format": "int32" }, "total_available": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "RateLimitMeta": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int32" }, "window": { "type": "string", "nullable": true }, "retry_after": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "StreetDetail": { "type": "object", "properties": { "addr_low": { "type": "string", "nullable": true }, "addr_high": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "suffix": { "type": "string", "nullable": true }, "postfix": { "type": "string", "nullable": true }, "odd_even": { "type": "string", "nullable": true }, "sec_addr_abbr": { "type": "string", "nullable": true }, "sec_addr_low": { "type": "string", "nullable": true }, "sec_addr_high": { "type": "string", "nullable": true }, "sec_addr_odd_even": { "type": "string", "nullable": true }, "building_name": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "record_type": { "type": "string", "nullable": true }, "carrier_route": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SuggestMatch": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "province": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "classification": { "type": "string", "nullable": true }, "fips": { "type": "string", "nullable": true }, "geoid": { "type": "string", "nullable": true }, "associated_zips": { "type": "array", "items": { "type": "string" }, "nullable": true }, "cbsa_code": { "type": "string", "nullable": true }, "metro_micro": { "type": "string", "nullable": true }, "postal_code_count": { "type": "integer", "format": "int32", "nullable": true }, "area": { "type": "string", "nullable": true }, "grade_low": { "type": "string", "nullable": true }, "grade_high": { "type": "string", "nullable": true }, "district_type": { "type": "string", "nullable": true }, "population": { "type": "integer", "format": "int32", "nullable": true }, "location": { "$ref": "#/components/schemas/LocationResult" }, "bbox": { "$ref": "#/components/schemas/BboxResult" }, "highlight": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SuggestPostRequest": { "type": "object", "properties": { "q": { "type": "string", "nullable": true }, "limit": { "type": "integer", "format": "int32", "nullable": true }, "include": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "proximity": { "type": "string", "nullable": true }, "debug_key": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SuggestResult": { "type": "object", "properties": { "total_matched": { "type": "integer", "format": "int32" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestMatch" }, "nullable": true } }, "additionalProperties": false }, "SuggestResultBatchItem": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true } }, "additionalProperties": false, "description": "Batch result item. On success, SuggestResult properties are merged inline (not nested under 'data'). On failure, only success, input, and error are present." }, "SuggestResultBatchItemApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestResultBatchItem" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TimezoneResult": { "type": "object", "properties": { "source": { "type": "string", "nullable": true }, "iana_name": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "abbreviation": { "type": "string", "nullable": true }, "abbreviation_dst": { "type": "string", "nullable": true }, "utc_offset": { "type": "number", "format": "double" }, "utc_offset_dst": { "type": "number", "format": "double", "nullable": true }, "observes_dst": { "type": "boolean" } }, "additionalProperties": false }, "ZipBatchRequest": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "include": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ZipCensusWrapper": { "type": "object", "properties": { "current": { "type": "object", "additionalProperties": { "nullable": true }, "nullable": true } }, "additionalProperties": false }, "ZipDemographics": { "type": "object", "properties": { "population": { "$ref": "#/components/schemas/PopulationInfo" }, "race": { "$ref": "#/components/schemas/RaceInfo" }, "age": { "$ref": "#/components/schemas/AgeInfo" }, "households": { "$ref": "#/components/schemas/HouseholdInfo" }, "business": { "$ref": "#/components/schemas/BusinessInfo" } }, "additionalProperties": false }, "ZipElevation": { "type": "object", "properties": { "ft": { "type": "integer", "format": "int32", "nullable": true }, "m": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "ZipInfo": { "type": "object", "properties": { "classification": { "type": "string", "nullable": true }, "classification_name": { "type": "string", "nullable": true }, "facility_code": { "type": "string", "nullable": true }, "city_delivery_indicator": { "type": "string", "nullable": true }, "intro_date": { "type": "string", "nullable": true }, "land_area_sq_mi": { "type": "number", "format": "double", "nullable": true }, "water_area_sq_mi": { "type": "number", "format": "double", "nullable": true }, "zip4_count": { "type": "integer", "format": "int32", "nullable": true }, "delivery_points": { "$ref": "#/components/schemas/DeliveryPoints" } }, "additionalProperties": false }, "ZipPostRequest": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "include": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ZipResult": { "type": "object", "properties": { "country": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "code_type": { "type": "string", "nullable": true }, "parent_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "state_name": { "type": "string", "nullable": true }, "state_fips": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "county_fips": { "type": "string", "nullable": true }, "multi_county": { "type": "boolean", "nullable": true }, "municipality": { "type": "string", "nullable": true }, "location": { "$ref": "#/components/schemas/LocationResult" }, "area_codes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "elevation": { "$ref": "#/components/schemas/ZipElevation" }, "metro": { "$ref": "#/components/schemas/MetroStatisticalInfo" }, "zip_info": { "$ref": "#/components/schemas/ZipInfo" }, "postal_info": { "$ref": "#/components/schemas/PostalInfo" }, "detail": { "$ref": "#/components/schemas/QuickZipDetail" }, "city_aliases": { "type": "array", "items": { "$ref": "#/components/schemas/CityAlias" }, "nullable": true }, "demographics": { "$ref": "#/components/schemas/ZipDemographics" }, "medicare": { "$ref": "#/components/schemas/MedicareInfo" }, "census": { "$ref": "#/components/schemas/ZipCensusWrapper" }, "school_district": { "$ref": "#/components/schemas/ZipSchoolDistrictSection" }, "timezone": { "$ref": "#/components/schemas/ZipTimezoneSection" }, "acs": { "type": "object", "additionalProperties": { "nullable": true }, "nullable": true } }, "additionalProperties": false }, "ZipResultBatchItem": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNotice" }, "nullable": true } }, "additionalProperties": false, "description": "Batch result item. On success, ZipResult properties are merged inline (not nested under 'data'). On failure, only success, input, and error are present." }, "ZipResultBatchItemApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "nullable": true }, "error": { "$ref": "#/components/schemas/ApiError" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ZipResultBatchItem" }, "nullable": true }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ZipSchoolDistrictSection": { "type": "object", "properties": { "source": { "type": "string", "nullable": true }, "school_year": { "type": "string", "nullable": true }, "districts": { "type": "array", "items": { "type": "object", "additionalProperties": { } }, "nullable": true } }, "additionalProperties": false }, "ZipTimezoneSection": { "type": "object", "properties": { "source": { "type": "string", "nullable": true }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/ZipTimezoneZone" }, "nullable": true } }, "additionalProperties": false }, "ZipTimezoneZone": { "type": "object", "properties": { "iana_name": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "abbreviation": { "type": "string", "nullable": true }, "abbreviation_dst": { "type": "string", "nullable": true }, "utc_offset": { "type": "number", "format": "double" }, "utc_offset_dst": { "type": "number", "format": "double", "nullable": true }, "observes_dst": { "type": "boolean" }, "pct_of_zip": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "description": "API key passed via X-Api-Key header", "name": "X-Api-Key", "in": "header" }, "ApiKeyQuery": { "type": "apiKey", "description": "API key passed via ?key= query parameter", "name": "key", "in": "query" } } }, "security": [ { "ApiKeyHeader": [ ], "ApiKeyQuery": [ ] } ], "tags": [ { "name": "Address", "description": "Address matching and validation with ZIP+4 append, standardization, and optional coordinate lookup" }, { "name": "Suggest", "description": "Typeahead search for ZIP codes, cities, counties, metro areas, states, and Canadian FSAs" }, { "name": "Radius Search", "description": "Find ZIP codes and postal codes within a radius of a center point, with optional ACS aggregation" }, { "name": "ZIP Lookup", "description": "Full ZIP/postal code lookups with census boundaries, ACS demographics, school districts, and more" }, { "name": "Quick ZIP", "description": "Fast ZIP/postal code lookups with basic info, timezone, and reverse geocoding" }, { "name": "Distance", "description": "Calculate distance and bearing between two points (ZIP codes, postal codes, or coordinates)" }, { "name": "System", "description": "Health checks and system status" } ], "externalDocs": { "description": "Service Level Agreement (SLA)", "url": "https://www.zip-codes.com/zip-code-api-sla.asp" } }