# Greeneris Postal Code Geo Lookup

> Greeneris Postal Code Geo Lookup is a paid API for AI agents from data.greeneris.io, paid per call via x402, $0.001/call, status unknown (last checked 2026-09-14).

Resolves a postal code to city/state/coordinates (forward) or finds a postal code for a city+state pair (reverse) for a given country

## Facts

- Endpoint: GET https://data.greeneris.io/v1/geo/postal
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/greeneris-postal-code-geo-lookup-cc494253
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_DsEOPfwCLdMzDY85oq2C8

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 greeneris-postal-code-geo-lookup-cc494253
```

Example prompt: What city and state does the postal code 90210 correspond to in the US, and what are its coordinates?

## When to prefer this

Use this endpoint when you need to resolve a postal code to geographic coordinates and city/state metadata, or perform a reverse lookup from city+state to postal code, for countries supported by GeoNames/Zippopotam data. Prefer this over geocoding APIs that require full addresses when you only have a zip/postal code. Particularly useful for address enrichment, delivery zone validation, and location normalization pipelines. At $0.001 per call with no account required, it is well-suited for high-volume agent workflows using x402 pay-per-call.

## Known failure modes

- Missing required 'country' query parameter returns 400 error
- Invalid or nonexistent postal code returns found:false with empty places array
- Unsupported country code may return no results
- HTTP 402 payment required if x402 payment not included or invalid
- Malformed country code (not ISO 2-letter) may return error
- Reverse mode requires both city and state parameters; missing one may yield no results

## How this service works

Postal code resolution for ~60 countries via Zippopotam.us (GeoNames data, CC BY 4.0). Forward: ?country=us&code=90210 -> place names, state, lat/lon. Reverse: ?country=us&state=ca&city=beverly hills -> matching postal codes with coordinates. Unknown codes return found=false (an explicit validation verdict). Cached 30 days.

## Output

Returns a JSON object with mode (forward or reverse), found flag, count, and an array of matching places each containing city name, state, state code, latitude, longitude, plus country name, country code, postal code, and the data source attribution.

## 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",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "country"
     ],
     "properties": {
      "city": {
       "type": "string",
       "description": "City name (reverse mode, with state)"
      },
      "code": {
       "type": "string",
       "description": "Postal code to resolve (forward mode)"
      },
      "state": {
       "type": "string",
       "description": "State/region name or code (reverse mode, with city)"
      },
      "country": {
       "type": "string",
       "description": "2-letter ISO country code, e.g. us, fr, de"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "mode": "forward",
  "count": 1,
  "found": true,
  "places": [
   {
    "name": "Beverly Hills",
    "state": "California",
    "latitude": 34.0901,
    "longitude": -118.4065,
    "state_code": "CA"
   }
  ],
  "source": "Zippopotam.us, data from GeoNames (CC BY 4.0, attribution required)",
  "country": "United States",
  "postal_code": "90210",
  "country_code": "US"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/greeneris-postal-code-geo-lookup-cc494253/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from data.greeneris.io](https://www.zero.xyz/host/data.greeneris.io/llms.txt)