---
canonical_url: "https://docs.composio.dev/toolkits/postal_data_api"
markdown_url: "https://docs.composio.dev/toolkits/postal_data_api.md"
product: "platform"
version: null
last_updated: null
---

# Postal Data API

Postal Data API validates and looks up postal codes, locations, coordinates, and regional metadata across more than 240 countries and territories.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 6
- **Triggers:** 0
- **Slug:** `POSTAL_DATA_API`
- **Version:** 00000000_00

## Tools

### Get API Information

**Slug:** `POSTAL_DATA_API_GET_API_INFORMATION`

Return Postal Data API version, coverage, usage guidance, current balance, and configured rate-limit status when returned, for connectivity or service discovery. The provider does not document this endpoint as unbilled, so assume it may consume one query.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Postal Code Metadata

**Slug:** `POSTAL_DATA_API_GET_POSTAL_CODE_METADATA`

Return all available country-specific metadata for a postal code, such as coordinates, timezone, county, elevation, and administrative levels. The metadata fields vary by country and availability. Each successful call consumes one Postal Data API query.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postal_code` | string | Yes | Postal code whose full metadata should be returned; pass it as a string to preserve leading zeros. |
| `country_code` | string | No | Two-letter ISO 3166-1 alpha-2 country code. Defaults to US. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look Up Postal Code

**Slug:** `POSTAL_DATA_API_LOOKUP_POSTAL_CODE`

Look up the city, region, and coordinates for a postal code. Use this for a concise location result; use Get Postal Code Metadata for country-specific administrative details. Each successful call consumes one query.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postal_code` | string | Yes | Postal code to look up. Pass it as a string to preserve leading zeros. |
| `country_code` | string | No | Two-letter ISO 3166-1 alpha-2 country code. Defaults to US. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Postal Codes by City

**Slug:** `POSTAL_DATA_API_SEARCH_POSTAL_CODES_BY_CITY`

Return all postal codes matching a city and optional region, including fuzzy-match details. For US searches, provide a state name or state code. Each successful call consumes one Postal Data API query.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | Yes | City name to search for. |
| `state` | string | No | Full state or region name. For US searches, provide this or state_code. |
| `state_code` | string | No | Two-letter US state abbreviation. For US searches, provide this or state. |
| `country_code` | string | No | Two-letter ISO 3166-1 alpha-2 country code. Defaults to US. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Postal Code

**Slug:** `POSTAL_DATA_API_VALIDATE_POSTAL_CODE`

Check whether one postal code exists without treating a nonexistent code as an execution error. Inspect valid in the response. Each successful call consumes one Postal Data API query.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postal_code` | string | Yes | Postal code to validate. Pass it as a string to preserve leading zeros. |
| `country_code` | string | No | Two-letter ISO 3166-1 alpha-2 country code. Defaults to US. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Postal Codes in Bulk

**Slug:** `POSTAL_DATA_API_VALIDATE_POSTAL_CODES_BULK`

Validate 1 to 1,000 postal codes synchronously, including mixed-country batches. Results preserve input order and report per-record failures. A batch of N records consumes N queries and is rejected atomically if balance or rate-limit budget is insufficient.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `records` | array | Yes | Between 1 and 1,000 postal-code records to validate synchronously. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |