--- title: "ZIP Codes Search by City API: Find ZIP Codes for Any City or State/Province/Region" version: 1.0.0 description: Find all ZIP and postal codes for any city worldwide. Provide a city name and country code to retrieve the complete list of codes associated with that location. Supports an optional state_name filter for countries with administrative divisions. Results are paginated; each page returns the codes array plus total result count, total pages, current page, and current page size. An unrecognized city/country combination 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 Search by City API: Find ZIP Codes for Any City or State/Province/Region v1.0.0](#zip-codes-search-by-city-api-find-zip-codes-for-any-city-or-stateprovinceregion-v100) - [Authentication](#authentication) - [ZIP Code APIs](#zip-code-apis) - [searchZipByCity](#searchzipbycity) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [ZipcodeSearchCityResponse](#zipcodesearchcityresponse) - [PostalCode](#postalcode) - [ErrorResponse](#errorresponse) # ZIP Codes Search by City API: Find ZIP Codes for Any City or State/Province/Region v1.0.0 Find all ZIP and postal codes for any city worldwide. Provide a city name and country code to retrieve the complete list of codes associated with that location. Supports an optional state_name filter for countries with administrative divisions. Results are paginated; each page returns the codes array plus total result count, total pages, current page, and current page size. An unrecognized city/country combination 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 ### searchZipByCity `GET /zipcode/search/city` *Search ZIP/postal codes by city* Returns every ZIP/postal code associated with the given city and country, optionally narrowed by state or province. #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |format|query|string|false|Format of the response. Possible values: json, xml.| |city|query|string|true|Name of the city to find ZIP/postal codes for.| |country|query|string|true|Country code in ISO 3166-1 alpha-2 format.| |state_name|query|string|false|Name of the state or province associated with the country. Useful to disambiguate cities with the same name in different states.| |page|query|integer|false|Page number to retrieve paginated results.| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| |format|xml| > Example responses > ZIP/postal codes retrieved successfully ```json { "total_results": 368, "total_pages": 1, "current_page": 1, "current_page_size": 368, "codes": [ "90001", "90002", "90003", "90210", "90211", "90212" ] } ``` > Bad Request — Missing city, invalid country code, or invalid page number ```json { "error": "Invalid Param Exception", "message": "please pass correct parameters", "path": "/v1.0/zipcode/search/city", "status": 400, "timestamp": "2026-07-27T11:22:48.293Z" } ``` ```json { "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." } ``` ```json { "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." } ``` > Not Found — No codes for the city, or requested page is out of range ```json { "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." } ``` ```json { "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." } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|ZIP/postal codes retrieved successfully|[ZipcodeSearchCityResponse](#zipcodesearchcityresponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing city, 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 city, 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 ### ZipcodeSearchCityResponse ZIP/postal codes for the requested city, 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).|