# Global Postal Code Geocoder (Zippopotam.us)

> Global Postal Code Geocoder (Zippopotam.us) is a paid API for AI agents from api.fadeandco.workers.dev, paid per call via x402, $0.002/call, status unknown (last checked 2026-10-29).

Resolves a postal code and ISO country code to place names, state/province, and lat/lng coordinates using Zippopotam.us data.

## Facts

- Endpoint: GET https://api.fadeandco.workers.dev/api/agent-intel/global-postal-geocode-resolver?utm_source=zero.xyz
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-29
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/global-postal-code-geocoder-zippopotam-us-9c017875
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_PwUuSiICwfAVXrSRwRBNi

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 global-postal-code-geocoder-zippopotam-us-9c017875
```

Example prompt: What city and coordinates does postal code 90210 in the US correspond to?

## When to prefer this

Use this endpoint when you need a quick, free-tier geocode of a postal code to place name and coordinates for any of the countries covered by Zippopotam.us. It is ideal for enriching address data, validating shipping regions, or plotting locations on a map when you already have a postal code and country. Prefer alternatives if you need time zone data, full administrative municipality hierarchies, or coverage of countries not in Zippopotam.us.

## Known failure modes

- Postal code not found in Zippopotam.us data — returns empty or error response
- Country code not supported by Zippopotam.us — service covers only a subset of countries
- Malformed postal code (too short, too long, wrong format) — may return no results
- Zippopotam.us upstream unavailable — worker may return a 5xx error
- Country code provided in wrong format (e.g. 3-letter instead of 2-letter ISO) — invalid query

## How this service works

Resolves a postal code in one country (ISO 2-letter code, e.g. US, DE, TR, GB) to its place names, state or province, and latitude and longitude, from Zippopotam.us. Covers only the countries that service publishes. No time zone or administrative municipality is returned, since no free source for them was used.

## Output

Returns a JSON object containing an array of matching places (each with name, state, state code, latitude, and longitude), the full country name, the country code, the original postal code, the upstream Zippopotam.us source URL, and a timestamp of when the lookup was performed.

## 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",
      "postalCode"
     ],
     "properties": {
      "country": {
       "type": "string",
       "description": "Two-letter ISO country code, e.g. US, DE, TR, GB"
      },
      "postalCode": {
       "type": "string",
       "description": "Postal code as written for that country, 2 to 12 characters"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "places": [
   {
    "name": "Beverly Hills",
    "state": "California",
    "latitude": 34.0901,
    "longitude": -118.4065,
    "stateCode": "CA"
   }
  ],
  "source": "https://api.zippopotam.us/us/90210",
  "country": "United States",
  "checkedAt": "2026-10-23T09:35:23.604Z",
  "postalCode": "90210",
  "countryCode": "US"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/global-postal-code-geocoder-zippopotam-us-9c017875/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.fadeandco.workers.dev](https://www.zero.xyz/host/api.fadeandco.workers.dev/llms.txt)