--- title: ZIP Codes by Region API Reference version: 1.0.0 description: Find all ZIP and postal codes for any state, province, or region worldwide. Provide a country code and either a region name or region ISO code to retrieve all codes in that administrative division; region_code takes priority when both are supplied. Results are paginated with up to 500 codes per page, and the response includes total result count, total pages, current page, and current page size. An unrecognized region returns a 404, as does requesting a page beyond the available range. openapi: 3.1.1 servers: - https://api.apifreaks.com/v1.0 paths: 1 operations: 1 schemas: 3 --- ## Table of Contents - [ZIP Codes by Region API Reference v1.0.0](#zip-codes-by-region-api-reference-v100) - [Authentication](#authentication) - [ZIP Code APIs](#zip-code-apis) - [searchZipByRegion](#searchzipbyregion) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [ZipcodeSearchRegionResponse](#zipcodesearchregionresponse) - [PostalCode](#postalcode) - [ErrorResponse](#errorresponse) # ZIP Codes by Region API Reference v1.0.0 Find all ZIP and postal codes for any state, province, or region worldwide. Provide a country code and either a region name or region ISO code to retrieve all codes in that administrative division; region_code takes priority when both are supplied. Results are paginated with up to 500 codes per page, and the response includes total result count, total pages, current page, and current page size. An unrecognized region returns a 404, as does requesting a page beyond the available range. Base URLs: * [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0) ## Authentication * API Key (ApiKeyAuthHeader) - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header. * API Key (ApiKeyAuthQuery) - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter. ## ZIP Code APIs ### searchZipByRegion `GET /zipcode/search/region` *Search ZIP codes by region* Returns every ZIP/postal code within the given region, state, or province of a country. #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |format|query|string|false|Format of the response. Possible values: json, xml.| |country|query|string|true|Country code in ISO 3166-1 alpha-2 format.| |region|query|string|false|Name of the region, state, or province associated with the country. Either region or region_code is required.| |region_code|query|string|false|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.| |page|query|integer|false|Page number to retrieve. Each page returns up to 500 results.| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| |format|xml| > Example responses > ZIP/postal codes retrieved successfully ```json { "total_results": 2591, "total_pages": 6, "current_page": 1, "current_page_size": 500, "codes": [ "90001", "90002", "90003", "90004", "90005" ] } ``` > Bad Request — Missing region/region_code, invalid country code, or invalid page number ```json { "error": "Invalid Param Exception", "message": "please pass correct parameters", "path": "/v1.0/zipcode/search/region", "status": 400, "timestamp": "2026-07-27T11:23:39.623Z" } ``` ```json { "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." } ``` ```json { "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." } ``` > Not Found — No codes for the region, or requested page is out of range ```json { "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." } ``` ```json { "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." } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|ZIP/postal codes retrieved successfully|[ZipcodeSearchRegionResponse](#zipcodesearchregionresponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing region/region_code, invalid country code, or invalid page number|[ErrorResponse](#errorresponse)| |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — No codes for the region, or requested page is out of range|[ErrorResponse](#errorresponse)| #### Response Headers |Status|Header|Type|Format|Description| |---|---|---|---|---| |200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| To perform this operation, you must be authenticated by means of one of the following methods: ApiKeyAuthHeader, ApiKeyAuthQuery ## Schemas ### ZipcodeSearchRegionResponse ZIP/postal codes for the requested region, with pagination metadata. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |total_results|integer|true|none|Total number of ZIP/postal codes found, across all pages.| |total_pages|integer|true|none|Total number of pages available.| |current_page|integer|true|none|Current page number.| |current_page_size|integer|true|none|Number of ZIP/postal codes in the current page.| |codes|[[PostalCode](#postalcode)]|true|none|List of ZIP/postal codes for the current page.| ### PostalCode A single ZIP or postal code. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |*anonymous*|string|false|none|A single ZIP or postal code.| ### ErrorResponse Standard error envelope returned by the API on failed requests. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |error|string|false|none|Short error category or exception type.| |message|string|true|none|Human-readable error message describing the failure.| |path|string|false|none|API endpoint path that produced the error.| |status|integer|false|none|HTTP status code returned with the error.| |timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|