--- title: Bulk ZIP Code Lookup API Reference version: 1.0.0 description: Look up multiple ZIP or postal codes in a single POST request, up to 100 codes per batch. Each matched code returns city, region, region code, locality, country code, latitude, and longitude. Accepts an optional `country` field in the request body to limit results to one country. Codes with no match are silently omitted from the `results` array instead of appearing as per-item error entries — the array can be shorter than the requested `codes` list. A malformed request body or invalid country code returns a 400; if none of the submitted codes match anything, the whole request returns a 404. openapi: 3.1.1 servers: - https://api.apifreaks.com/v1.0 paths: 1 operations: 1 schemas: 4 --- ## Table of Contents - [Bulk ZIP Code Lookup API Reference v1.0.0](#bulk-zip-code-lookup-api-reference-v100) - [Authentication](#authentication) - [ZIP Code APIs](#zip-code-apis) - [bulkLookupZipCodes](#bulklookupzipcodes) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [ZipcodeLookupResponse](#zipcodelookupresponse) - [ZipResultItem](#zipresultitem) - [BulkZipRequest](#bulkziprequest) - [ErrorResponse](#errorresponse) # Bulk ZIP Code Lookup API Reference v1.0.0 Look up multiple ZIP or postal codes in a single POST request, up to 100 codes per batch. Each matched code returns city, region, region code, locality, country code, latitude, and longitude. Accepts an optional `country` field in the request body to limit results to one country. Codes with no match are silently omitted from the `results` array instead of appearing as per-item error entries — the array can be shorter than the requested `codes` list. A malformed request body or invalid country code returns a 400; if none of the submitted codes match anything, the whole request returns a 404. 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 ### bulkLookupZipCodes `POST /zipcode/lookup` *Look up multiple ZIP/postal codes in one request* Looks up up to 100 ZIP/postal codes in a single request and returns matching location data for each code that resolves. > Body parameter ```json { "codes": [ "10001", "90210" ], "country": "US" } ``` #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |format|query|string|false|Format of the response. Possible values: json, xml.| |body|body|[BulkZipRequest](#bulkziprequest)|true|none| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| |format|xml| > Example responses > 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. ```json { "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 } ] } ``` ```json { "results": [ { "code": "10001", "country_code": "US", "region": "New York", "region_code": "NY", "city": "New York County", "locality": "Manhattan", "latitude": 40.748436, "longitude": -73.99402 } ] } ``` > Bad Request — Malformed body, invalid country code, or over the 100-code limit ```json { "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." } ``` ```json { "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." } ``` ```json { "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." } ``` > Not Found — None of the submitted codes matched anything ```json { "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." } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|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.|[ZipcodeLookupResponse](#zipcodelookupresponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Malformed body, invalid country code, or over the 100-code limit|[ErrorResponse](#errorresponse)| |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — None of the submitted codes matched anything|[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 ### ZipcodeLookupResponse ZIP code lookup result containing an array of matched postal codes with location details. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |results|[[ZipResultItem](#zipresultitem)]|true|none|Array of matched ZIP code results. Codes with no match are omitted, so this array can be shorter than the requested codes list.| ### ZipResultItem A ZIP code result containing location details. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |code|string|true|none|Postal/ZIP code of the location.| |country_code|string|true|none|Country code in ISO 3166-1 alpha-2 format.| |region|string|true|none|Region, state, or province associated with the postal code.| |region_code|string|true|none|Region code or abbreviation.| |city|string|true|none|City associated with the postal code.| |locality|string|false|none|Locality or neighborhood associated with the postal code. Can be an empty string when no locality-level data exists.| |latitude|number(float)|true|none|Latitude coordinate of the postal code location.| |longitude|number(float)|true|none|Longitude coordinate of the postal code location.| ### BulkZipRequest Request body for bulk ZIP/postal code lookup. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |codes|[string]|true|none|Array of ZIP or postal codes to look up. Maximum 100 codes per request.| |country|string|false|none|ISO 3166-1 alpha-2 country code to limit the search to. Applies to every code in the batch.| ### 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).|