---
title: ZIP Code Distance Match API Reference
version: 1.0.0
description: "Find all pairs of postal codes within a specified distance threshold from a list of up to 100 input codes. Specify a maximum distance and receive every pair of codes whose separation is at or below that value; if no pairs fall within the threshold, a 200 with an empty results array is returned rather than a 404. Supports six distance units: kilometers, miles, yards, meters, feet, and inches. A `country` code is always required. Results include each matched pair with its calculated distance."
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 5
---

## Table of Contents

- [ZIP Code Distance Match API Reference v1.0.0](#zip-code-distance-match-api-reference-v100)
  - [Authentication](#authentication)
  - [ZIP Code APIs](#zip-code-apis)
    - [getZipcodeDistanceMatch](#getzipcodedistancematch)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [ZipcodeDistanceMatchResponse](#zipcodedistancematchresponse)
    - [ZipcodeDistanceMatchItem](#zipcodedistancematchitem)
    - [DistanceMatchRequest](#distancematchrequest)
    - [DistanceMatchInputCode](#distancematchinputcode)
    - [ErrorResponse](#errorresponse)



# ZIP Code Distance Match API Reference v1.0.0

Find all pairs of postal codes within a specified distance threshold from a list of up to 100 input codes. Specify a maximum distance and receive every pair of codes whose separation is at or below that value; if no pairs fall within the threshold, a 200 with an empty results array is returned rather than a 404. Supports six distance units: kilometers, miles, yards, meters, feet, and inches. A `country` code is always required. Results include each matched pair with its calculated distance.

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

### getZipcodeDistanceMatch

`POST /zipcode/distance/match`

*Get matching ZIP/postal code pairs within a distance*

Returns every pair of the requested ZIP/postal codes whose distance from each other is at or below the given threshold.

> Body parameter

```json
{
  "codes": [
    "90210",
    "90211",
    "90212",
    "10001"
  ],
  "country": "US",
  "distance": 5
}
```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|body|body|[DistanceMatchRequest](#distancematchrequest)|true|The list of codes, their country, and an optional distance threshold and unit.|

##### Enumerated Values

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

> Example responses

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

```json
{
  "result_count": 2,
  "results": [
    {
      "code_1": "90211",
      "code_2": "90212",
      "distance": 1.958
    },
    {
      "code_1": "90210",
      "code_2": "90212",
      "distance": 4.704
    }
  ]
}
```

```json
{
  "result_count": 0,
  "results": []
}
```

> Bad Request — Missing/invalid body, country, or unit, or over the 100-code limit

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

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

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

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

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

> Not Found — None of the submitted codes matched anything

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

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|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.|[ZipcodeDistanceMatchResponse](#zipcodedistancematchresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing/invalid body, country, or unit, 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

### ZipcodeDistanceMatchResponse

Matching ZIP/postal code pairs within the requested distance threshold.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|result_count|integer|true|none|Number of matching ZIP/postal code pairs returned. Zero when no pairs fall within the threshold.|
|results|[[ZipcodeDistanceMatchItem](#zipcodedistancematchitem)]|true|none|Array of matching code pairs within the requested distance threshold.|

### ZipcodeDistanceMatchItem

A single matched pair of ZIP/postal codes with the distance between them.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code_1|string|true|none|First ZIP/postal code in the pair.|
|code_2|string|true|none|Second ZIP/postal code in the pair.|
|distance|number(float)|true|none|Distance between the ZIP/postal code pair, in the unit specified by the unit field (default km).|

### DistanceMatchRequest

Request body specifying the codes, country, and distance threshold to match pairs within.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|codes|[[DistanceMatchInputCode](#distancematchinputcode)]|true|none|List of ZIP or postal codes to find pairs within the specified distance. Maximum 100 codes.|
|country|string|true|none|Country of the codes in ISO 3166-1 alpha-2 format. Required.|
|distance|number(float)|false|none|Maximum distance threshold. All pairs within this distance are returned. If omitted, the API applies a default threshold.|
|unit|string|false|none|Distance unit. Default: km.|

##### Enumerated Values

|Property|Value|
|---|---|
|unit|km|
|unit|mi|
|unit|yd|
|unit|m|
|unit|ft|
|unit|in|

### DistanceMatchInputCode

A ZIP or postal code to find distance matches for.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|A ZIP or postal code to find distance matches for.|

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