---
title: ZIP Code Distance API - Straight-Line Distance Between ZIP & Postal Codes Worldwide
version: 1.0.0
description: "Calculate straight-line distances from a base point to up to 100 comparison postal codes in one request. The base point can be specified by a postal code or by exact latitude/longitude coordinates, but a `country` code is required either way. Supports six distance units: kilometers, miles, yards, meters, feet, and inches. Comparison codes with no match are silently omitted from the results array rather than returned as per-item errors — the array can be shorter than the requested compare list."
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 5
---

## Table of Contents

- [ZIP Code Distance API - Straight-Line Distance Between ZIP & Postal Codes Worldwide v1.0.0](#zip-code-distance-api-straight-line-distance-between-zip-postal-codes-worldwide-v100)
  - [Authentication](#authentication)
  - [ZIP Code APIs](#zip-code-apis)
    - [getZipcodeDistance](#getzipcodedistance)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [ZipcodeDistanceResponse](#zipcodedistanceresponse)
    - [ZipcodeDistanceItem](#zipcodedistanceitem)
    - [DistanceRequest](#distancerequest)
    - [DistanceCompareCode](#distancecomparecode)
    - [ErrorResponse](#errorresponse)



# ZIP Code Distance API - Straight-Line Distance Between ZIP & Postal Codes Worldwide v1.0.0

Calculate straight-line distances from a base point to up to 100 comparison postal codes in one request. The base point can be specified by a postal code or by exact latitude/longitude coordinates, but a `country` code is required either way. Supports six distance units: kilometers, miles, yards, meters, feet, and inches. Comparison codes with no match are silently omitted from the results array rather than returned as per-item errors — the array can be shorter than the requested compare list.

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

### getZipcodeDistance

`POST /zipcode/distance`

*Get distance between postal codes*

Calculates the distance from a base ZIP/postal code or coordinate pair to up to 100 comparison postal codes.

> Body parameter

```json
{
  "code": "90210",
  "country": "US",
  "compare": [
    "10001",
    "94103"
  ]
}
```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|body|body|[DistanceRequest](#distancerequest)|true|Base point (code or coordinates), country, and the list of postal codes to compare against it.|

##### Enumerated Values

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

> Example responses

> Successful response with distances. Comparison codes with no match are omitted from results rather than represented as error entries.

```json
{
  "result_count": 2,
  "results": [
    {
      "code": "10001",
      "distance": 3948.696
    },
    {
      "code": "94103",
      "distance": 544.134
    }
  ]
}
```

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

```json
{
  "timestamp": "2026-07-27T11:20:46.922Z",
  "path": "/v1.0/zipcode/distance",
  "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:20:36.514Z",
  "path": "/v1.0/zipcode/distance",
  "status": 400,
  "error": "Country Code Missing",
  "message": "Provide a valid ISO 3166-1 alpha-2 country code."
}
```

```json
{
  "timestamp": "2026-07-27T11:20:48.768Z",
  "path": "/v1.0/zipcode/distance",
  "status": 400,
  "error": "Invalid Country Code Provided",
  "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
}
```

```json
{
  "timestamp": "2026-07-27T11:20:48.196Z",
  "path": "/v1.0/zipcode/distance",
  "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:20:47.652Z",
  "path": "/v1.0/zipcode/distance",
  "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 compare codes matched anything

```json
{
  "timestamp": "2026-07-27T11:20:49.310Z",
  "path": "/v1.0/zipcode/distance",
  "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 distances. Comparison codes with no match are omitted from results rather than represented as error entries.|[ZipcodeDistanceResponse](#zipcodedistanceresponse)|
|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 compare 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

### ZipcodeDistanceResponse

Distance calculation results for each comparison code that matched.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|result_count|integer|true|none|Number of distance results returned (may be less than the number of requested compare codes).|
|results|[[ZipcodeDistanceItem](#zipcodedistanceitem)]|true|none|Array of distance results, one per matched comparison code. Codes with no match are omitted.|

### ZipcodeDistanceItem

Distance from the base point to one matched comparison code.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code|string|true|none|The matched comparison ZIP/postal code.|
|distance|number(float)|true|none|Distance from the base point to this code, in the unit specified by the unit field (default km).|

### DistanceRequest

Request body specifying the base point, country, and comparison codes for distance calculation.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|compare|[[DistanceCompareCode](#distancecomparecode)]|true|none|List of ZIP or postal codes to calculate distance from the base point. Maximum 100 codes.|
|code|string|false|none|Base ZIP or postal code from which distances are calculated. Alternative to lat/long.|
|country|string|true|none|ISO 3166-1 alpha-2 country code for the base point. Required even when the base point is given as lat/long coordinates.|
|lat|number(float)|false|none|Base latitude coordinate (-90 to 90). Alternative to code.|
|long|number(float)|false|none|Base longitude coordinate (-180 to 180). Alternative to code.|
|unit|string|false|none|Distance unit for the returned values. Default: km.|

##### Enumerated Values

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

### DistanceCompareCode

A ZIP or postal code to compare against the base point.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|A ZIP or postal code to compare against the base point.|

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