SearchCtrl+K

ZIP Code Distance API Reference

Calculate distances from a base point to a list of ZIP or postal codes. The base point can be a ZIP code + country or raw latitude/longitude coordinates. Supports up to 100 comparison codes per request.

POST

https://api.apifreaks.com/v1.0/zipcode/distance

Test

Six distance units are supported: km (default), mi, yd, m, ft, and in. Each result includes the postal code and its calculated distance from the base point.

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/zipcode/distance' \
  -H 'Content-Type: application/json' \
  -H 'X-apiKey: API-KEY' \
  -d '{
  "compare": [
    "90210",
    "10001"
  ],
  "code": "33101",
  "country": "US",
  "unit": "km"
}'

Response

{
  "result_count": 2,
  "results": [
    {
      "code": "90210",
      "distance": 3774.306
    },
    {
      "code": "10001",
      "distance": 1760.796
    }
  ]
}

API Request Parameters

Provide a postal code in code with country, or use lat/long as the base point. The compare array is required.

comparerequiredarray

List of ZIP or postal codes to calculate distance from the base point. All codes must exist in the same 'country'. Max 100.

codeoptionalstring

Base ZIP or postal code from which distances are calculated. Must be provided together with 'country'.

countryoptionalstring

Country of the ZIP/postal codes in ISO 3166-1 alpha-2 format. Required when using 'code' as base.

latoptionalfloat

Base latitude coordinate (-90 to 90). Must be provided together with 'long'.

longoptionalfloat

Base longitude coordinate (-180 to 180). Must be provided together with 'lat'.

unitoptionalstringdefault: km

Distance measuring unit. Allowed: 'km', 'mi', 'yd', 'm', 'ft', 'in'. Default: km.

Request Body

The request body must be a JSON object with a base location (via code + country or lat/long) and a required compare array of postal codes.

{
  "compare": [
    "90210",
    "10001"
  ],
  "code": "33101",
  "country": "US",
  "unit": "km"
}

API Response Schema

Returns 200 OK with result_count and a results array containing each compared code and its distance.

result_count

integermandatory

Number of ZIP code distance results returned.

results

Arraymandatory

Array of ZIP code distance result objects.

results[].code

stringmandatory

The postal code from the compare list.

results[].distance

floatmandatory

Distance from the base point to this code in the requested unit.

Error Status & Codes

The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.

400

The provided unit symbol is invalid. Please refer to the documentation for supported units.

400

Only ISO 3166-1 alpha-2 codes country codes are supported.

400

A maximum of 100 postal/zip codes can be processed per request.

404

None of the provided postal/zip codes were found in our database.