# geo402 Geocoding

> geo402 Geocoding is a paid API for AI agents from geo402.alogos.xyz, paid per call via x402, $0.02/call, status unknown (last checked 2026-09-15).

Converts a place or city name into geographic coordinates (latitude/longitude) using a pay-per-call model with no API key required

## Facts

- Endpoint: GET https://geo402.alogos.xyz/v1/geocode
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/geo402-geocoding-ff24fcc6
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_qu_bKvPjcYYXQFY7A2YGY

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 geo402-geocoding-ff24fcc6
```

Example prompt: What are the latitude and longitude coordinates for Lisbon? Just give me the top result.

## When to prefer this

Choose this endpoint when you need forward geocoding (place name to coordinates) without an API key or subscription, especially in agent pipelines that can handle x402 micropayments on Base/USDC or MPP/pathUSD. Ideal for one-off or low-volume lookups where pay-per-call economics are preferable to a monthly plan.

## Known failure modes

- Place name not found — returns empty results or 404
- Ambiguous place name returns unexpected or irrelevant location
- Missing required `q` parameter returns 400 Bad Request
- Payment not provided or insufficient — returns 402 Payment Required
- Rate limiting or service unavailability returns 5xx error

## How this service works

Pay-per-call geolocation utility for AI agents: geocoding, reverse geocoding, timezone lookup, and great-circle distance. No API key, no subscription — agents pay per request via x402 (Base/USDC) or MPP (Tempo/pathUSD).

## Output

Returns one or more geocoded results for the queried place name, each containing latitude, longitude, and the resolved place name. The `limit` parameter controls how many results are returned.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "q"
 ],
 "properties": {
  "q": {
   "type": "string",
   "description": "Place, city, or region name to geocode, e.g. 'Lisbon' or 'New York'."
  },
  "limit": {
   "type": "integer",
   "description": "Maximum ranked matches to return."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "query",
  "results"
 ],
 "properties": {
  "query": {
   "type": "string"
  },
  "results": {
   "type": "array",
   "items": {
    "type": "object",
    "properties": {
     "lat": {
      "type": "number"
     },
     "lon": {
      "type": "number"
     },
     "name": {
      "type": "string"
     },
     "admin1": {
      "type": "string"
     },
     "timezone": {
      "type": "string"
     },
     "distanceKm": {
      "type": "number",
      "description": "Present on reverse geocoding responses."
     },
     "population": {
      "type": "number"
     },
     "countryCode": {
      "type": "string"
     },
     "countryName": {
      "type": "string"
     }
    },
    "additionalProperties": true
   }
  }
 },
 "additionalProperties": true
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/geo402-geocoding-ff24fcc6/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from geo402.alogos.xyz](https://www.zero.xyz/host/geo402.alogos.xyz/llms.txt)