---
title: ZIP Code API - Global ZIP & Postal Code Lookup and Validation
version: 1.0.0
description: Look up and validate a single ZIP or postal code worldwide, returning every location that uses it. Returns city, region, region code, locality, country code, latitude, and longitude for each matching location. A postal code can map to multiple locations across different countries (e.g. "90210" matches places in the US, Ukraine, Kenya, Mexico, and Pakistan) unless the optional `country` parameter narrows the search to one country. Only one code is accepted per request — for multiple codes in one call, use the Bulk ZIP Code Lookup API instead. Invalid country codes return a 400, and codes with no match return a 404.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [ZIP Code API - Global ZIP & Postal Code Lookup and Validation v1.0.0](#zip-code-api-global-zip-postal-code-lookup-and-validation-v100)
  - [Authentication](#authentication)
  - [ZIP Code APIs](#zip-code-apis)
    - [lookupZipCode](#lookupzipcode)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [ZipcodeLookupResponse](#zipcodelookupresponse)
    - [ZipResultItem](#zipresultitem)
    - [ErrorResponse](#errorresponse)



# ZIP Code API - Global ZIP & Postal Code Lookup and Validation v1.0.0

Look up and validate a single ZIP or postal code worldwide, returning every location that uses it. Returns city, region, region code, locality, country code, latitude, and longitude for each matching location. A postal code can map to multiple locations across different countries (e.g. "90210" matches places in the US, Ukraine, Kenya, Mexico, and Pakistan) unless the optional `country` parameter narrows the search to one country. Only one code is accepted per request — for multiple codes in one call, use the Bulk ZIP Code Lookup API instead. Invalid country codes return a 400, and codes with no match return 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

### lookupZipCode

`GET /zipcode/lookup`

*Look up a ZIP/postal code*

Returns every location worldwide that matches the given postal/ZIP code, optionally narrowed to one country.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|code|query|string|true|The postal/ZIP code to look up. Only one code is accepted per request.|
|country|query|string|false|Country code in ISO 3166-1 alpha-2 format. Limits results to that country. If not provided, matching locations from all countries are returned.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful response with matching ZIP code locations

```json
{
  "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
    }
  ]
}
```

```json
{
  "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
    }
  ]
}
```

> Bad Request — Missing code or invalid country code

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/zipcode/lookup",
  "status": 400,
  "timestamp": "2026-07-27T11:17:13.351Z"
}
```

```json
{
  "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."
}
```

> Not Found — No location matches the given code

```json
{
  "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."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with matching ZIP code locations|[ZipcodeLookupResponse](#zipcodelookupresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing code or invalid country code|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — No location matches the given code|[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 matching postal codes with location details.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|results|[[ZipResultItem](#zipresultitem)]|true|none|Array of ZIP code results matching the requested code. When multiple locations worldwide share the same postal code, each appears as a separate entry.|

### 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.|

### 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).|