# International Address Formats – Country Subdivisions Lookup

> International Address Formats – Country Subdivisions Lookup is a paid API for AI agents from address-formats.x402tookit.com, paid per call via x402, $0.02/call, status unknown (last checked 2026-11-02).

Returns administrative divisions (states, provinces, regions) for a given country, including ISO codes, names, and postal prefix patterns.

## Facts

- Endpoint: GET https://address-formats.x402tookit.com/subdivisions?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-02
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/international-address-formats-country-subdivisions-lookup-3a5763ad
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_K-RL5ObqDZaF9wOv6NFNe

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability international-address-formats-country-subdivisions-lookup-3a5763ad
```

Example prompt: Can you list all the provinces and territories of Canada with their ISO codes and postal prefix patterns?

## When to prefer this

Use this endpoint when you need a structured, machine-readable list of a country's administrative divisions with ISO codes and postal prefix patterns — especially useful for populating address form dropdowns, validating state/province inputs, or building postal code routing logic. Prefer this over general geocoding APIs when you specifically need subdivision codes and postal metadata rather than geographic coordinates.

## Known failure modes

- Missing or invalid country code returns an error or empty result
- Country code not in dataset returns no subdivisions
- Filter query 'q' with no matching code or name returns empty subdivisions array
- Limit out of range (below 1 or above 300) may cause validation error
- Some countries may have null postal prefix patterns where data is unavailable

## How this service works

Administrative divisions (states, provinces) of a country with codes, names and postal prefix patterns, from the dataset.

## Output

A structured list of administrative subdivisions for the requested country, each containing a subdivision code, name, optional Latin name, and postal prefix pattern (where available). The response also includes the subdivision label used by that country (e.g. 'State', 'Province', 'Prefecture'), total count, data source attribution, and snapshot date.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "country"
     ],
     "properties": {
      "q": {
       "type": "string",
       "description": "Optional filter on code or name"
      },
      "limit": {
       "type": "integer",
       "description": "Maximum rows (1-300, default 100)"
      },
      "country": {
       "type": "string",
       "description": "ISO 3166-1 alpha-2 code, e.g. CA"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "asOf": {
       "type": [
        "null",
        "string"
       ]
      },
      "total": {
       "type": [
        "null",
        "number"
       ]
      },
      "source": {
       "type": [
        "null",
        "string"
       ]
      },
      "country": {
       "type": [
        "null",
        "string"
       ]
      },
      "reasons": {
       "type": [
        "array",
        "null"
       ]
      },
      "summary": {
       "type": [
        "null",
        "string"
       ]
      },
      "verdict": {
       "type": [
        "null",
        "string"
       ]
      },
      "degraded": {
       "type": [
        "boolean",
        "null"
       ]
      },
      "returned": {
       "type": [
        "null",
        "number"
       ]
      },
      "dataSource": {
       "type": [
        "null",
        "string"
       ]
      },
      "disclaimer": {
       "type": [
        "null",
        "string"
       ]
      },
      "notChecked": {
       "type": [
        "array",
        "null"
       ],
       "items": {
        "type": "string"
       }
      },
      "attribution": {
       "type": [
        "null",
        "string"
       ]
      },
      "snapshotDate": {
       "type": [
        "null",
        "string"
       ]
      },
      "subdivisions": {
       "type": [
        "array",
        "null"
       ],
       "items": {
        "type": "object",
        "properties": {
         "cod
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/international-address-formats-country-subdivisions-lookup-3a5763ad/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from address-formats.x402tookit.com](https://www.zero.xyz/host/address-formats.x402tookit.com/llms.txt)