Postal Code

Look up postal codes, find nearby postal codes by coordinates, validate codes, and get supported countries

Overview

This endpoint provides comprehensive postal code data worldwide. You can look up postal codes by country and code, search by place name, find nearby postal codes by geographic coordinates, validate postal codes, and get a list of all supported countries.

The endpoint returns:

Postal code details with place names and administrative regions
Geographic coordinates (latitude/longitude)
Nearby postal codes based on coordinates with distance
Postal code validation
Supported countries with postal code counts

Pricing

📊 1 Credit per Request (2 Credits for coordinate-based search)

Each request costs 1 data credit except the /postal-code/find endpoint which costs 2 credits per request.

Endpoints

GET /postal-code
GET /postal-code/find
GET /postal-code/countries
GET /postal-code/validate

Postal Code Lookup

GET /postal-code

Look up postal codes by country, code, or place name.

Query Parameters

Parameter	Type	Required	Description
`country`	string	No	ISO 3166-1 alpha-2 country code (e.g., "US", "GB")
`code`	string	No	Postal code to look up (e.g., "10001")
`place`	string	No	Place name to search for
`limit`	number	No	Maximum results to return (default: 50, max: 1000)

Response Format

Single Result (specific country + code)

{
  "countryCode": "US",
  "postalCode": "10001",
  "placeName": "New York",
  "adminName1": "New York",
  "adminName2": "New York County",
  "adminName3": null,
  "coordinates": {
    "latitude": 40.7484,
    "longitude": -73.9967
  },
  "accuracy": 4
}

Multiple Results (search)

{
  "results": [
    {
      "countryCode": "US",
      "postalCode": "10001",
      "placeName": "New York",
      "adminName1": "New York",
      "adminName2": "New York County",
      "adminName3": null,
      "coordinates": {
        "latitude": 40.7484,
        "longitude": -73.9967
      },
      "accuracy": 4
    }
  ],
  "count": 15,
  "query": {
    "country": "US",
    "code": null,
    "place": null,
    "limit": 50
  }
}

Response Fields

Field	Type	Description
`countryCode`	string	ISO 3166-1 alpha-2 country code
`postalCode`	string	The postal/ZIP code
`placeName`	string	Name of the place/city
`adminName1`	string	Primary administrative division (state/province)
`adminName2`	string	Secondary administrative division (county/district)
`adminName3`	string \| null	Tertiary administrative division
`coordinates.latitude`	number	Latitude of the postal code area
`coordinates.longitude`	number	Longitude of the postal code area
`accuracy`	number	Accuracy level of the coordinates (1-6)

Example Requests

Look Up a Specific Postal Code

curl -X GET "https://api.boxapi.com/postal-code?country=US&code=10001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Search by Country

curl -X GET "https://api.boxapi.com/postal-code?country=GB&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Search by Place Name

curl -X GET "https://api.boxapi.com/postal-code?country=US&place=Manhattan" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Find Nearby Postal Codes

GET /postal-code/find

Find postal codes near a geographic coordinate. Costs 2 credits per request.

Query Parameters

Parameter	Type	Required	Description
`latitude`	number	Yes	Latitude (-90 to 90)
`longitude`	number	Yes	Longitude (-180 to 180)
`radius`	number	No	Search radius in kilometers (0-100, default: 10)
`limit`	number	No	Maximum results to return (default: 20, max: 100)

Response Format

{
  "coordinates": {
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "searchRadius": 10,
  "results": [
    {
      "countryCode": "US",
      "postalCode": "10001",
      "placeName": "New York",
      "adminName1": "New York",
      "adminName2": "New York County",
      "adminName3": null,
      "coordinates": {
        "latitude": 40.7484,
        "longitude": -73.9967
      },
      "distance": 5.2,
      "accuracy": 4
    }
  ],
  "count": 12,
  "query": {
    "lat": 40.7128,
    "lng": -74.0060,
    "radius": 10,
    "limit": 20
  }
}

Example Request

curl -X GET "https://api.boxapi.com/postal-code/find?latitude=40.7128&longitude=-74.0060&radius=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Supported Countries

GET /postal-code/countries

Get a list of all countries with postal code data and counts.

Response Format

{
  "countries": [
    {
      "countryCode": "US",
      "postalCodeCount": 42345
    },
    {
      "countryCode": "GB",
      "postalCodeCount": 28452
    }
  ],
  "totalCountries": 245,
  "totalPostalCodes": 5234567
}

Example Request

curl -X GET "https://api.boxapi.com/postal-code/countries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Validate Postal Code

GET /postal-code/validate

Check whether a postal code is valid for a given country.

Query Parameters

Parameter	Type	Required	Description
`country`	string	Yes	ISO 3166-1 alpha-2 country code
`code`	string	Yes	Postal code to validate

Response Format

{
  "valid": true,
  "country": "US",
  "code": "10001"
}

Example Request

curl -X GET "https://api.boxapi.com/postal-code/validate?country=US&code=10001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Usage Examples

JavaScript/Node.js

// Look up a postal code
const response = await fetch('https://api.boxapi.com/postal-code?country=US&code=10001', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(`${data.postalCode} - ${data.placeName}, ${data.adminName1}`);

// Find nearby postal codes
const nearbyResponse = await fetch(
  'https://api.boxapi.com/postal-code/find?latitude=40.7128&longitude=-74.0060&radius=5',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const nearbyData = await nearbyResponse.json();
nearbyData.results.forEach(result => {
  console.log(`${result.postalCode} - ${result.placeName} (${result.distance} km)`);
});

// Validate a postal code
const validateResponse = await fetch(
  'https://api.boxapi.com/postal-code/validate?country=US&code=10001',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const validateData = await validateResponse.json();
console.log(`Postal code is ${validateData.valid ? 'valid' : 'invalid'}`);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Look up a postal code
response = requests.get(
    'https://api.boxapi.com/postal-code?country=US&code=10001',
    headers=headers
)
data = response.json()
print(f"{data['postalCode']} - {data['placeName']}, {data['adminName1']}")

# Find nearby postal codes
nearby_response = requests.get(
    'https://api.boxapi.com/postal-code/find?latitude=40.7128&longitude=-74.0060&radius=5',
    headers=headers
)
nearby_data = nearby_response.json()
for result in nearby_data['results']:
    print(f"{result['postalCode']} - {result['placeName']} ({result['distance']} km)")

# Validate a postal code
validate_response = requests.get(
    'https://api.boxapi.com/postal-code/validate?country=US&code=10001',
    headers=headers
)
validate_data = validate_response.json()
print(f"Postal code is {'valid' if validate_data['valid'] else 'invalid'}")

PHP

<?php
$apiKey = 'YOUR_API_KEY';

// Look up a postal code
$ch = curl_init('https://api.boxapi.com/postal-code?country=US&code=10001');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

echo "{$data['postalCode']} - {$data['placeName']}, {$data['adminName1']}\n";

// Find nearby postal codes
$ch = curl_init('https://api.boxapi.com/postal-code/find?latitude=40.7128&longitude=-74.0060&radius=5');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$nearbyData = json_decode($response, true);

foreach ($nearbyData['results'] as $result) {
    echo "{$result['postalCode']} - {$result['placeName']} ({$result['distance']} km)\n";
}
?>

Error Responses

Missing Parameters

{
  "error": "Missing required parameters: country and code"
}

HTTP Status: 400 Bad Request

Postal Code Not Found

{
  "error": "Postal code not found"
}

HTTP Status: 404 Not Found

Invalid Coordinates

{
  "error": "Invalid coordinates: latitude must be between -90 and 90"
}

HTTP Status: 400 Bad Request

Authentication Error

{
  "error": "Unauthorized"
}

HTTP Status: 401 Unauthorized

Rate Limit Exceeded

{
  "error": "IP blocked",
  "statusCode": 429
}

HTTP Status: 429 Too Many Requests

Rate Limits

The following rate limits apply per IP address:

10,000 requests per minute for successful responses (2xx status codes)
60 requests per minute for client errors (4xx status codes)
60 requests per minute for server errors (5xx status codes)

⚠️ If you exceed these limits, your IP will be temporarily blocked and you'll receive a 429 status code.

Use Cases

The Postal Code API is ideal for:

📦 E-commerce auto-completing shipping addresses
🏠 Real estate platforms showing area information
📍 Location services finding nearby areas
✅ Form validation verifying postal codes at input
🗺️ Mapping applications geocoding postal code areas
📊 Data enrichment adding geographic metadata to records

PreviousLanguage

NextEmail Validation

Getting Started

API

GEO

Postal Code

Overview

Pricing

Endpoints

Postal Code Lookup

GET /postal-code

Query Parameters

Response Format

Single Result (specific country + code)

Multiple Results (search)

Response Fields

Example Requests

Look Up a Specific Postal Code

Search by Country

Search by Place Name

Find Nearby Postal Codes

GET /postal-code/find

Query Parameters

Response Format

Example Request

Supported Countries

GET /postal-code/countries

Response Format

Example Request

Validate Postal Code

GET /postal-code/validate

Query Parameters

Response Format

Example Request

Usage Examples

JavaScript/Node.js

Python

PHP

Error Responses

Missing Parameters

Postal Code Not Found

Invalid Coordinates

Authentication Error

Rate Limit Exceeded

Rate Limits

Use Cases

On this page