This API provides accurate **postal and ZIP code validation** using **ISO-2 country codes** (US, GB, DE, FR, etc.). It strictly validates postal codes only — **no full address lookup, no POI search, and no false country matches**.

Getting Started

To begin using this API, follow these steps and make your first API call: **Subscribe to a plan:** Visit our Pricing page and subscribe to one of the plans. If you are just starting, you can subscribe to the free BASIC plan of the API (hard-limited and no credit card required). **Make your first API call:** Visit the RapidAPI Playground — the Postal Code Validation endpoint should be selected and displayed on the main panel view. Since there are default query parameter values, simply click the blue **“Test endpoint”** button to make your first API call. The JSON response will be displayed on the right panel. **Documentation and Resources:** Refer to the detailed endpoint descriptions, input parameters, and response examples provided in the Endpoints tab. Code snippets are available for popular programming languages including JavaScript, Python, Java, Shell, and more to help you quickly integrate the API. You should be good to go now!

Authentication

To authenticate with the API, send the **X-RapidAPI-Host** header along with the **X-RapidAPI-Key** header set to your RapidAPI App API Key (as shown in the endpoint Code Snippets).

Input Parameters

The following query parameters are supported by the API: **postal_code** (required) Postal or ZIP code to validate. Supports global formats including UK postcodes with spaces. Examples: `WC2E 9TB` `10001` `10115` **country_code** (required) ISO-2 country code for validation. The API strictly validates the postal code against this country. Examples: `US` `GB` `DE` `FR`

Response Structure

Here’s an example of a successful response: ``` { "success": true, "valid": true, "postal_code": "10001", "country": "United States", "country_code": "US", "state": "New York", "county": "New York County", "city": "New York", "latitude": "40.7485112", "longitude": "-73.9940398", "timestamp": "2026-01-19T12:53:00+01:00" } ``` Example of an invalid postal code: ``` { "success": true, "valid": false, "postal_code": "10001", "country_code": "DE", "message": "Invalid or unknown postal \/ ZIP code for this country", "timestamp": "2026-01-19T12:53:25+01:00" } ``` Please note that some errors might be returned by the RapidAPI gateway and will have a different structure. Please refer to the Error Handling / Error Response Structure section for more details. In addition, RapidAPI gateway adds several headers to each response. For more information, please refer to [https://docs.rapidapi.com/docs/response-headers](https://docs.rapidapi.com/docs/response-headers).

Endpoints

For detailed endpoint parameters, response fields, and live testing, please refer to the **Endpoints** section of this API.

Rate Limiting

Each subscription plan defines the maximum number of requests permitted per month, along with a rate limit expressed in RPS (Requests Per Second). All free plans (such as BASIC) are limited to **1000 requests per hour**, as required by RapidAPI.

Rate Limits Headers

All API responses include the following rate limit headers: **x-ratelimit-requests-limit:** Total number of requests allowed by your subscription. **x-ratelimit-requests-remaining:** Remaining requests before reaching the quota limit. **x-ratelimit-requests-reset:** Time in seconds until the quota resets.

Handling Limits

When rate limits are exceeded, the API will return a **429 Too Many Requests** error. ``` { "message": "Too many requests" } ``` Wait until the limit resets or upgrade your subscription plan for higher limits.

Code Examples

Code examples for JavaScript, Python, Java, Shell, and other popular languages are available in the **Endpoints** tab under **Code Snippets**.

Common HTTP Status Codes

**400 Bad Request:** Missing or invalid parameters **403 Forbidden:** Invalid API key or no active subscription **404 Not Found:** Invalid endpoint **429 Too Many Requests:** Rate limit exceeded **5XX Server Error:** Temporary server-side issue

Support

If you encounter any issues or need clarification, please contact us with the error code, message, and request context, and we will assist you promptly.

Contact Us

For custom plans, enterprise usage, or high-volume requests: **Email:** [alreadycoded@gmail.com](mailto:alreadycoded@gmail.com) **Website:** [https://www.alreadycoded.com](https://www.alreadycoded.com)