# Geocoding API (Forward & Reverse) via x402

> Geocoding API (Forward & Reverse) via x402 is a paid API for AI agents from freetier-agent-api.pages.dev, paid per call via x402, $0.0015/call, status unknown (last checked 2026-10-30).

Converts addresses or place names to geographic coordinates (forward geocoding) or coordinates to addresses (reverse geocoding), returning structured location data powered by OpenStreetMap Nominatim, with per-call USDC micropayment via x402.

## Facts

- Endpoint: GET https://freetier-agent-api.pages.dev/api/geocode?utm_source=zero.xyz
- Price: $0.0015/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-30
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/geocoding-api-forward-reverse-via-x402-2507272a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_KBs_b4HxFlmgNsBSsjbxS

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 geocoding-api-forward-reverse-via-x402-2507272a
```

Example prompt: Can you find the latitude and longitude for 'Eiffel Tower, Paris' and give me the full structured address — limit results to 1 and return in English?

## When to prefer this

Choose this endpoint when you need geocoding without an API key or signup, want pay-per-call pricing (no subscription), or are building an agent pipeline that already uses x402/USDC micropayments on Base. It's backed by OpenStreetMap Nominatim so it has excellent global coverage for landmarks, addresses, and named places. Prefer alternatives (Google Maps Geocoding, HERE) if you need very high accuracy for ambiguous addresses, real-time POI updates, or SLA guarantees.

## Known failure modes

- Ambiguous or misspelled address returns zero results or a low-confidence match
- Missing required query parameter (q for forward, lat+lon for reverse) returns a 400 error
- Country code filter too restrictive — place exists but not in specified country, returning empty results
- Rate limit or payment failure via x402 returns a 402 Payment Required response
- Very remote or unofficial place names not indexed in OSM return no results
- Language code not supported defaults silently to English

## How this service works

Invoice-to-JSON, on-chain tools (transaction explainer + payment check, wallet profile, contract ABI, ERC-20 token risk), company contacts and web-to-RAG for AI agents. Pay per call with x402 (USDC on Base). No signup, no API key.

## Output

Returns a JSON object with the geocoding mode (forward/reverse), result count, the original query, and an array of result objects each containing lat/lon coordinates, OSM ID and type, bounding box, place name, place type, category, importance score, and a fully structured address (road, city, state, postcode, country, country code). Also includes attribution and source information (OpenStreetMap Nominatim, ODbL 1.0 license).

## 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": [],
     "properties": {
      "q": {
       "type": "string",
       "description": "address or place name (forward geocoding)"
      },
      "lat": {
       "type": "string",
       "description": "latitude for reverse geocoding (with lon)"
      },
      "lon": {
       "type": "string",
       "description": "longitude for reverse geocoding (with lat)"
      },
      "lang": {
       "type": "string",
       "description": "result language, default en"
      },
      "limit": {
       "type": "string",
       "description": "1-5 matches, default 1"
      },
      "country": {
       "type": "string",
       "description": "ISO 3166-1 alpha-2 filter, e.g. dk or us,ca"
      }
     }
    }
   }
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "mode": {
       "type": [
        "string",
        "null"
       ]
      },
      "count": {
       "type": [
        "number",
        "null"
       ]
      },
      "query": {
       "type": "object",
       "properties": {
        "q": {
         "type": [
          "string",
          "null"
         ]
        },
        "limit": {
         "type": [
          "number",
          "null"
         ]
        },
        "country": {}
       }
      },
      "results": {
       "type": "array",
       "items": {
        "type": [
         "object",
         "null"
        ]
       }
      },
      "sources": {
       "type": "array",
       "items": {
        "type": [
         "object",
         "null"
        ]
       }
      },
      "attribution": {
       "type": [
        "string",
        "null"
       ]
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "mode": "forward",
  "count": 1,
  "query": {
   "q": "Eiffel Tower, Paris",
   "limit": 1,
   "country": null
  },
  "results": [
   {
    "lat": 48.8582599,
    "lon": 2.2945006,
    "osm": {
     "id": 5013364,
     "type": "way"
    },
    "bbox": [
     48.8574753,
     48.8590453
    ],
    "name": "Eiffel Tower",
    "type": "tower",
    "address": {
     "city": "Paris",
     "road": "Avenue Anatole France",
     "state": "Ile-de-France",
     "county": null,
     "country": "France",
     "postcode": "75007",
     "country_code": "FR",
     "house_number": "5"
    },
    "category": "man_made",
    "importance": 0.621,
    "display_name": "Eiffel Tower, 5, Avenue Anatole France, Quartier du Gros-Caillou, 7th Arrondissement, Paris, Ile-de-France, Metropolitan France, 75007, France"
   }
  ],
  "sources": [
   {
    "url": "https://nominatim.org/",
    "name": "OpenStreetMap Nominatim",
    "license": "ODbL 1.0"
   }
  ],
  "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/geocoding-api-forward-reverse-via-x402-2507272a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from freetier-agent-api.pages.dev](https://www.zero.xyz/host/freetier-agent-api.pages.dev/llms.txt)