---
title: Find All ZIP Codes within a Radius - ZIP Code Radius Search API
version: 1.0.0
description: Find all ZIP or postal codes within a given radius from a central ZIP code or GPS coordinates. Supports pagination with up to 500 results per page and multiple distance units (km, mi, yd, m, ft, in). The central point can be specified by ZIP code plus country, or by latitude/longitude coordinates. Returns code, region, city, district, and distance for each matching postal code within the radius, sorted nearest-first. Maximum radius is 100 km (or the equivalent in other units).
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [Find All ZIP Codes within a Radius - ZIP Code Radius Search API v1.0.0](#find-all-zip-codes-within-a-radius-zip-code-radius-search-api-v100)
  - [Authentication](#authentication)
  - [ZIP Code APIs](#zip-code-apis)
    - [searchZipByRadius](#searchzipbyradius)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [ZipcodeSearchRadiusResponse](#zipcodesearchradiusresponse)
    - [ZipRadiusResultItem](#zipradiusresultitem)
    - [ErrorResponse](#errorresponse)



# Find All ZIP Codes within a Radius - ZIP Code Radius Search API v1.0.0

Find all ZIP or postal codes within a given radius from a central ZIP code or GPS coordinates. Supports pagination with up to 500 results per page and multiple distance units (km, mi, yd, m, ft, in). The central point can be specified by ZIP code plus country, or by latitude/longitude coordinates. Returns code, region, city, district, and distance for each matching postal code within the radius, sorted nearest-first. Maximum radius is 100 km (or the equivalent in other units).

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

### searchZipByRadius

`GET /zipcode/search/radius`

*Find ZIP/postal codes within a radius*

Returns every ZIP/postal code within the given radius of a center point, specified either by code plus country or by latitude/longitude coordinates.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|code|query|string|false|Postal/ZIP code to use as the center point for the search. Requires country to be set. Alternative to lat/long.|
|lat|query|number(float)|false|Latitude coordinate for the center point. Alternative to code/country.|
|long|query|number(float)|false|Longitude coordinate for the center point. Alternative to code/country.|
|country|query|string|false|Country code in ISO 3166-1 alpha-2 format. Required only when using the code parameter.|
|radius|query|number(float)|true|Search radius for the query. The maximum allowed values are: 100 km, 100 mi, 109361 yd, 100000 m, 328084 ft, 3937007.75 in.|
|unit|query|string|false|Unit for the radius and returned distance values. Supported distance units are m, km, mi, ft, yd, in.|
|page|query|integer|false|Page number to retrieve. Each page returns up to 500 results.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|
|unit|m|
|unit|km|
|unit|mi|
|unit|ft|
|unit|yd|
|unit|in|

> Example responses

> ZIP/postal codes found within the specified radius

```json
{
  "total_results": 64,
  "total_pages": 1,
  "current_page": 1,
  "current_page_size": 64,
  "results": [
    {
      "code": "90077",
      "region": "California",
      "region_code": "CA",
      "city": "Los Angeles",
      "district": "Los Angeles (Los Angeles)",
      "distance": 3.335
    },
    {
      "code": "90069",
      "region": "California",
      "region_code": "CA",
      "city": "Los Angeles",
      "district": "West Hollywood (West Hollywood)",
      "distance": 3.403
    }
  ]
}
```

> Bad Request — Missing/invalid radius, coordinates, or country code

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

```json
{
  "timestamp": "2026-07-27T11:19:46.342Z",
  "path": "/v1.0/zipcode/search/radius",
  "status": 400,
  "error": "Invalid Radius Range",
  "message": "The specified radius is out of the acceptable range. Please check the documentation for valid radius limits."
}
```

```json
{
  "timestamp": "2026-07-27T11:19:46.876Z",
  "path": "/v1.0/zipcode/search/radius",
  "status": 400,
  "error": "Invalid Latitude",
  "message": "Latitude must be between -90 and 90."
}
```

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

> Not Found — Base ZIP/postal code does not exist

```json
{
  "timestamp": "2026-07-27T11:19:47.940Z",
  "path": "/v1.0/zipcode/search/radius",
  "status": 404,
  "error": "Base Postal/Zip Code Not Found",
  "message": "The provided base postal/zip code does not exist in our database."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|ZIP/postal codes found within the specified radius|[ZipcodeSearchRadiusResponse](#zipcodesearchradiusresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing/invalid radius, coordinates, or country code|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — Base ZIP/postal code does not exist|[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.|
|200|X-Concurrent-Threads|integer||Specifies the maximum number of concurrent requests allowed.|
|200|X-Concurrent-Threads-Active|integer||Indicates the number of active concurrent requests being processed.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-Concurrent-Threads|integer||Specifies the maximum number of concurrent requests allowed.|
|400|X-Concurrent-Threads-Active|integer||Indicates the number of active concurrent requests being processed.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-Concurrent-Threads|integer||Specifies the maximum number of concurrent requests allowed.|
|404|X-Concurrent-Threads-Active|integer||Indicates the number of active concurrent requests being processed.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### ZipcodeSearchRadiusResponse

ZIP code radius search result with pagination metadata and an array of matching codes within the specified radius.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_results|integer|true|none|Total number of ZIP/postal codes found within the radius, 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 returned on the current page (up to 500).|
|results|[[ZipRadiusResultItem](#zipradiusresultitem)]|true|none|Array of matching ZIP/postal codes for the current page, sorted nearest-first by distance.|

### ZipRadiusResultItem

A ZIP code result within the search radius, including distance from the center point.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code|string|true|none|Postal/ZIP code of the matched location.|
|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.|
|district|string|false|none|District or neighborhood associated with the postal code. Can be an empty string when no district-level data exists.|
|distance|number(float)|true|none|Distance from the center point to this postal code, in the unit specified by the unit parameter.|

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