openapi: 3.2.0
info:
title: Apifreaks Api Hub For Developers ZIP Code APIs API
version: 1.0.0
contact:
name: APIFreaks Support
url: https://apifreaks.com/contact
email: support@apifreaks.com
description: 'Operations tagged ZIP Code APIs across 7 of this provider''s published API definitions: apifreaks-api-hub-for-developers-bulk-zip-code-lookup-openapi.json, apifreaks-api-hub-for-developers-zip-code-api-openapi.json, apifreaks-api-hub-for-developers-zip-code-distance-match-openapi.json, apifreaks-api-hub-for-developers-zip-code-distance-openapi.json, apifreaks-api-hub-for-developers-zip-codes-by-city-openapi.json, apifreaks-api-hub-for-developers-zip-codes-by-region-openapi.json, apifreaks-api-hub-for-developers-zip-codes-radius-search-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0
description: Bulk ZIP Code Lookup API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: ZIP Code APIs
paths:
/zipcode/lookup:
servers:
- url: https://api.apifreaks.com/v1.0
description: Bulk ZIP Code Lookup API Server
post:
tags:
- ZIP Code APIs
summary: Look up multiple ZIP/postal codes in one request
operationId: bulkLookupZipCodes
description: Looks up up to 100 ZIP/postal codes in a single request and returns matching location data for each code that resolves.
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkZipRequest'
examples:
typicalRequest:
summary: Typical bulk lookup request
value:
codes:
- '10001'
- '90210'
country: US
responses:
'200':
description: Successful response. `results` contains one entry per code that matched, in match order — codes with no match are omitted rather than represented as error entries, so the array can be shorter than the requested `codes` list.
content:
application/json:
schema:
$ref: '#/components/schemas/ZipcodeLookupResponse'
examples:
typicalSuccess:
summary: All requested codes matched
value:
results:
- code: '10001'
country_code: US
region: New York
region_code: NY
city: New York County
locality: Manhattan
latitude: 40.748436
longitude: -73.99402
- code: '90210'
country_code: US
region: California
region_code: CA
city: Los Angeles
locality: Beverly Hills (Beverly Hills)
latitude: 34.10313
longitude: -118.41625
partialMatch:
summary: One of two requested codes matched — the unmatched code is simply absent
value:
results:
- code: '10001'
country_code: US
region: New York
region_code: NY
city: New York County
locality: Manhattan
latitude: 40.748436
longitude: -73.99402
'400':
description: Bad Request — Malformed body, invalid country code, or over the 100-code limit
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidBody:
summary: codes field missing or malformed
value:
timestamp: '2026-07-27T11:18:38.639Z'
path: /v1.0/zipcode/lookup
status: 400
error: Request Body Invalid
message: Request body is missing required fields or is not in the expected format. Please refer to the API documentation.
InvalidCountryCode:
summary: country is not a valid ISO 3166-1 alpha-2 code
value:
timestamp: '2026-07-27T11:18:39.139Z'
path: /v1.0/zipcode/lookup
status: 400
error: Invalid Country Code Provided
message: Only ISO 3166-1 alpha-2 codes country codes are supported.
BulkLimitExceeded:
summary: More than 100 codes submitted
value:
timestamp: '2026-07-27T11:18:48.850Z'
path: /v1.0/zipcode/lookup
status: 400
error: Maximum Postal/Zip Code Limit Exceeded
message: A maximum of 100 postal/zip codes can be processed per request.
'404':
description: Not Found — None of the submitted codes matched anything
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ZipNotFound:
summary: No codes matched
value:
timestamp: '2026-07-27T11:18:39.650Z'
path: /v1.0/zipcode/lookup
status: 404
error: Postal/Zip Codes Not Found
message: None of the provided postal/zip codes were found in our database.
get:
tags:
- ZIP Code APIs
summary: Look up a ZIP/postal code
description: Returns every location worldwide that matches the given postal/ZIP code, optionally narrowed to one country.
operationId: lookupZipCode
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
- name: code
in: query
required: true
schema:
type: string
description: The postal/ZIP code to look up. Only one code is accepted per request.
- name: country
in: query
required: false
schema:
type: string
description: Country code in ISO 3166-1 alpha-2 format. Limits results to that country. If not provided, matching locations from all countries are returned.
responses:
'200':
description: Successful response with matching ZIP code locations
content:
application/json:
schema:
$ref: '#/components/schemas/ZipcodeLookupResponse_2'
examples:
success:
summary: Code matched in one country
value:
results:
- code: '90210'
country_code: US
region: California
region_code: CA
city: Los Angeles
locality: Beverly Hills (Beverly Hills)
latitude: 34.10313
longitude: -118.41625
multipleCountryMatches:
summary: Same code matched across multiple countries (no country filter)
value:
results:
- code: '90210'
country_code: US
region: California
region_code: CA
city: Los Angeles
locality: Beverly Hills (Beverly Hills)
latitude: 34.10313
longitude: -118.41625
- code: '90210'
country_code: UA
region: Zakarpattia Oblast
region_code: '21'
city: Batovo Settlement Hromada
locality: Svoboda
latitude: 48.35717
longitude: 22.367962
- code: '90210'
country_code: KE
region: Kitui
region_code: '18'
city: Matinyani
locality: Kalia
latitude: -1.310763
longitude: 37.969997
'400':
description: Bad Request — Missing code or invalid country code
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
MissingCode:
summary: Missing required code parameter
value:
error: Invalid Param Exception
message: please pass correct parameters
path: /v1.0/zipcode/lookup
status: 400
timestamp: '2026-07-27T11:17:13.351Z'
InvalidCountryCode:
summary: country is not a valid ISO 3166-1 alpha-2 code
value:
timestamp: '2026-07-27T11:17:13.872Z'
path: /v1.0/zipcode/lookup
status: 400
error: Invalid Country Code Provided
message: Only ISO 3166-1 alpha-2 codes country codes are supported.
'404':
description: Not Found — No location matches the given code
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ZipNotFound:
summary: Postal/ZIP code not found
value:
timestamp: '2026-07-27T11:17:14.474Z'
path: /v1.0/zipcode/lookup
status: 404
error: Postal/Zip Code Not Found
message: Provided postal/zip code was not found in our database.
/zipcode/distance/match:
servers:
- url: https://api.apifreaks.com/v1.0
description: ZIP Code Distance Match API Server
post:
tags:
- ZIP Code APIs
summary: Get matching ZIP/postal code pairs within a distance
operationId: getZipcodeDistanceMatch
description: Returns every pair of the requested ZIP/postal codes whose distance from each other is at or below the given threshold.
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
requestBody:
required: true
description: The list of codes, their country, and an optional distance threshold and unit.
content:
application/json:
schema:
$ref: '#/components/schemas/DistanceMatchRequest'
examples:
typicalRequest:
summary: Find pairs within 5km
value:
codes:
- '90210'
- '90211'
- '90212'
- '10001'
country: US
distance: 5
responses:
'200':
description: Successful response with matching ZIP code pairs. If none of the codes are within the distance threshold of each other, results is an empty array — this is not a 404.
content:
application/json:
schema:
$ref: '#/components/schemas/ZipcodeDistanceMatchResponse'
examples:
success:
summary: Pairs within threshold
value:
result_count: 2
results:
- code_1: '90211'
code_2: '90212'
distance: 1.958
- code_1: '90210'
code_2: '90212'
distance: 4.704
noPairsWithinThreshold:
summary: No pairs within the threshold
value:
result_count: 0
results: []
'400':
description: Bad Request — Missing/invalid body, country, or unit, or over the 100-code limit
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidBody:
summary: codes field missing or malformed
value:
timestamp: '2026-07-27T11:21:58.473Z'
path: /v1.0/zipcode/distance/match
status: 400
error: Request Body Invalid
message: Request body is missing required fields or is not in the expected format. Please refer to the API documentation.
MissingCountry:
summary: Missing required country field
value:
timestamp: '2026-07-27T11:21:42.483Z'
path: /v1.0/zipcode/distance/match
status: 400
error: Country Code Missing
message: Provide a valid ISO 3166-1 alpha-2 country code.
BadCountry:
summary: country is not a valid ISO 3166-1 alpha-2 code
value:
timestamp: '2026-07-27T11:21:57.332Z'
path: /v1.0/zipcode/distance/match
status: 400
error: Invalid Country Code Provided
message: Only ISO 3166-1 alpha-2 codes country codes are supported.
InvalidUnit:
summary: unit is not one of the supported symbols
value:
timestamp: '2026-07-27T11:21:56.749Z'
path: /v1.0/zipcode/distance/match
status: 400
error: Invalid Unit Symbol
message: The provided unit symbol is invalid. Please refer to the documentation for supported units.
OverLimit:
summary: More than 100 codes submitted
value:
timestamp: '2026-07-27T11:21:57.961Z'
path: /v1.0/zipcode/distance/match
status: 400
error: Maximum Postal/Zip Code Limit Exceeded
message: A maximum of 100 postal/zip codes can be processed per request.
'404':
description: Not Found — None of the submitted codes matched anything
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
NotFound:
summary: No codes matched
value:
timestamp: '2026-07-27T11:21:59.589Z'
path: /v1.0/zipcode/distance/match
status: 404
error: Postal/Zip Codes Not Found
message: None of the provided postal/zip codes were found in our database.
/zipcode/distance:
servers:
- url: https://api.apifreaks.com/v1.0
description: ZIP Code Distance API Server
post:
tags:
- ZIP Code APIs
summary: Get distance between postal codes
operationId: getZipcodeDistance
description: Calculates the distance from a base ZIP/postal code or coordinate pair to up to 100 comparison postal codes.
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
requestBody:
required: true
description: Base point (code or coordinates), country, and the list of postal codes to compare against it.
content:
application/json:
schema:
$ref: '#/components/schemas/DistanceRequest'
examples:
typicalRequest:
summary: Base point by code
value:
code: '90210'
country: US
compare:
- '10001'
- '94103'
responses:
'200':
description: Successful response with distances. Comparison codes with no match are omitted from results rather than represented as error entries.
content:
application/json:
schema:
$ref: '#/components/schemas/ZipcodeDistanceResponse'
examples:
success:
summary: Distances to two comparison codes
value:
result_count: 2
results:
- code: '10001'
distance: 3948.696
- code: '94103'
distance: 544.134
'400':
description: Bad Request — Missing/invalid body, country, or unit, or over the 100-code limit
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidBody:
summary: compare field missing or malformed
value:
timestamp: '2026-07-27T11:20:46.922Z'
path: /v1.0/zipcode/distance
status: 400
error: Request Body Invalid
message: Request body is missing required fields or is not in the expected format. Please refer to the API documentation.
MissingCountry:
summary: country is required even when the base point is given as coordinates
value:
timestamp: '2026-07-27T11:20:36.514Z'
path: /v1.0/zipcode/distance
status: 400
error: Country Code Missing
message: Provide a valid ISO 3166-1 alpha-2 country code.
BadCountry:
summary: country is not a valid ISO 3166-1 alpha-2 code
value:
timestamp: '2026-07-27T11:20:48.768Z'
path: /v1.0/zipcode/distance
status: 400
error: Invalid Country Code Provided
message: Only ISO 3166-1 alpha-2 codes country codes are supported.
InvalidUnit:
summary: unit is not one of the supported symbols
value:
timestamp: '2026-07-27T11:20:48.196Z'
path: /v1.0/zipcode/distance
status: 400
error: Invalid Unit Symbol
message: The provided unit symbol is invalid. Please refer to the documentation for supported units.
OverLimit:
summary: More than 100 compare codes submitted
value:
timestamp: '2026-07-27T11:20:47.652Z'
path: /v1.0/zipcode/distance
status: 400
error: Maximum Postal/Zip Code Limit Exceeded
message: A maximum of 100 postal/zip codes can be processed per request.
'404':
description: Not Found — None of the compare codes matched anything
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
NotFound:
summary: No compare codes matched
value:
timestamp: '2026-07-27T11:20:49.310Z'
path: /v1.0/zipcode/distance
status: 404
error: Postal/Zip Codes Not Found
message: None of the provided postal/zip codes were found in our database.
/zipcode/search/city:
servers:
- url: https://api.apifreaks.com/v1.0
description: ZIP Codes by City API Server
get:
tags:
- ZIP Code APIs
summary: Search ZIP/postal codes by city
description: Returns every ZIP/postal code associated with the given city and country, optionally narrowed by state or province.
operationId: searchZipByCity
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
- name: city
in: query
required: true
schema:
type: string
description: Name of the city to find ZIP/postal codes for.
- name: country
in: query
required: true
schema:
type: string
description: Country code in ISO 3166-1 alpha-2 format.
- name: state_name
in: query
required: false
schema:
type: string
description: Name of the state or province associated with the country. Useful to disambiguate cities with the same name in different states.
- name: page
in: query
required: false
schema:
type: integer
default: 1
minimum: 1
description: Page number to retrieve paginated results.
responses:
'200':
description: ZIP/postal codes retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ZipcodeSearchCityResponse'
examples:
success:
summary: Codes for a city
value:
total_results: 368
total_pages: 1
current_page: 1
current_page_size: 368
codes:
- '90001'
- '90002'
- '90003'
- '90210'
- '90211'
- '90212'
'400':
description: Bad Request — Missing city, invalid country code, or invalid page number
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
MissingCity:
summary: Missing required city parameter
value:
error: Invalid Param Exception
message: please pass correct parameters
path: /v1.0/zipcode/search/city
status: 400
timestamp: '2026-07-27T11:22:48.293Z'
BadCountry:
summary: country is not a valid ISO 3166-1 alpha-2 code
value:
timestamp: '2026-07-27T11:22:59.112Z'
path: /v1.0/zipcode/search/city
status: 400
error: Invalid Country Code Provided
message: Only ISO 3166-1 alpha-2 codes country codes are supported.
BadPage:
summary: page is 0 or negative
value:
timestamp: '2026-07-27T11:22:59.742Z'
path: /v1.0/zipcode/search/city
status: 400
error: Invalid Page Number
message: The page number must be greater than 0.
'404':
description: Not Found — No codes for the city, or requested page is out of range
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
NotFound:
summary: No codes found for the given city/country
value:
timestamp: '2026-07-27T11:23:00.301Z'
path: /v1.0/zipcode/search/city
status: 404
error: Postal/Zip Codes Not Found
message: No postal/zip codes found for the provided city Nonexistentcityxyz123 in country US.
PageNotFound:
summary: Requested page exceeds total_pages
value:
timestamp: '2026-07-27T11:23:00.873Z'
path: /v1.0/zipcode/search/city
status: 404
error: Page Not Found
message: The requested page exceeds the available page range.
/zipcode/search/region:
servers:
- url: https://api.apifreaks.com/v1.0
description: ZIP Codes by Region API Server
get:
tags:
- ZIP Code APIs
summary: Search ZIP codes by region
description: Returns every ZIP/postal code within the given region, state, or province of a country.
operationId: searchZipByRegion
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
- name: country
in: query
required: true
schema:
type: string
description: Country code in ISO 3166-1 alpha-2 format.
- name: region
in: query
required: false
schema:
type: string
description: Name of the region, state, or province associated with the country. Either region or region_code is required.
- name: region_code
in: query
required: false
schema:
type: string
description: ISO code of the region, state, or province associated with the country. Either region or region_code is required. region_code takes priority if both are given.
- name: page
in: query
required: false
schema:
type: integer
default: 1
minimum: 1
description: Page number to retrieve. Each page returns up to 500 results.
responses:
'200':
description: ZIP/postal codes retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ZipcodeSearchRegionResponse'
examples:
success:
summary: Codes for a region
value:
total_results: 2591
total_pages: 6
current_page: 1
current_page_size: 500
codes:
- '90001'
- '90002'
- '90003'
- '90004'
- '90005'
'400':
description: Bad Request — Missing region/region_code, invalid country code, or invalid page number
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
MissingRegion:
summary: Neither region nor region_code was provided
value:
error: Invalid Param Exception
message: please pass correct parameters
path: /v1.0/zipcode/search/region
status: 400
timestamp: '2026-07-27T11:23:39.623Z'
BadCountry:
summary: country is not a valid ISO 3166-1 alpha-2 code
value:
timestamp: '2026-07-27T11:23:46.673Z'
path: /v1.0/zipcode/search/region
status: 400
error: Invalid Country Code Provided
message: Only ISO 3166-1 alpha-2 codes country codes are supported.
BadPage:
summary: page is 0 or negative
value:
timestamp: '2026-07-27T11:23:47.192Z'
path: /v1.0/zipcode/search/region
status: 400
error: Invalid Page Number
message: The page number must be greater than 0.
'404':
description: Not Found — No codes for the region, or requested page is out of range
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
NotFound:
summary: No codes found for the given region/country
value:
timestamp: '2026-07-27T11:23:47.785Z'
path: /v1.0/zipcode/search/region
status: 404
error: Postal/Zip Codes Not Found
message: No postal/zip codes found for the provided region Nonexistentregionxyz in country US.
PageNotFound:
summary: Requested page exceeds total_pages
value:
timestamp: '2026-07-27T11:23:48.312Z'
path: /v1.0/zipcode/search/region
status: 404
error: Page Not Found
message: The requested page exceeds the available page range.
/zipcode/search/radius:
servers:
- url: https://api.apifreaks.com/v1.0
description: ZIP Code Radius Search API Server
get:
tags:
- ZIP Code APIs
summary: Find ZIP/postal codes within a radius
description: Returns every ZIP/postal code within the given radius of a center point, specified either by code plus country or by latitude/longitude coordinates.
operationId: searchZipByRadius
parameters:
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- xml
default: json
description: 'Format of the response. Possible values: json, xml.'
- name: code
in: query
required: false
schema:
type: string
description: Postal/ZIP code to use as the center point for the search. Requires country to be set. Alternative to lat/long.
- name: lat
in: query
required: false
schema:
type: number
format: float
description: Latitude coordinate for the center point. Alternative to code/country.
- name: long
in: query
required: false
schema:
type: number
format: float
description: Longitude coordinate for the center point. Alternative to code/country.
- name: country
in: query
required: false
schema:
type: string
description: Country code in ISO 3166-1 alpha-2 format. Required only when using the code parameter.
- name: radius
in: query
required: true
schema:
type: number
format: float
description: 'Search radius for the query. The maximum allowed values are: 100 km, 100 mi, 109361 yd, 100000 m, 328084 ft, 3937007.75 in.'
- name: unit
in: query
required: false
schema:
type: string
default: km
enum:
- m
- km
- mi
- ft
- yd
- in
description: Unit for the radius and returned distance values. Supported distance units are m, km, mi, ft, yd, in.
- name: page
in: query
required: false
schema:
type: integer
default: 1
minimum: 1
description: Page number to retrieve. Each page returns up to 500 results.
responses:
'200':
description: ZIP/postal codes found within the specified radius
content:
application/js
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apifreaks-api-hub-for-developers/refs/heads/main/openapi/apifreaks-api-hub-for-developers-zip-code-apis-api-openapi.yml