# OpenWeather Geocoding via Locus x402

> OpenWeather Geocoding via Locus x402 is a paid API for AI agents from openweather.x402.paywithlocus.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-15).

Converts city names (optionally with state/country codes) into geographic coordinates and location metadata using OpenWeather's geocoding API, billed per-call via x402 micropayment.

## Facts

- Endpoint: POST https://openweather.x402.paywithlocus.com/openweather/geocode
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/openweather-geocoding-via-locus-x402-b5927d02
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_hlfUhc3_6AvLry8ztKyCL

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 openweather-geocoding-via-locus-x402-b5927d02 -d '<json body>'
```

Example prompt: Can you find the geographic coordinates for Austin, Texas — I need the lat/lon to pass into a weather lookup?

## When to prefer this

Use this endpoint when you need to resolve a human-readable city name into geographic coordinates before making downstream weather or geospatial API calls, especially when already using the OpenWeather via Locus x402 suite for weather data. Prefer this over generic geocoding services when you want a single x402-billed, micropayment-friendly pipeline that stays within the same provider ecosystem.

## Known failure modes

- Unrecognized city name returns empty results array
- Missing or malformed country/state code may return ambiguous matches
- Exceeding limit parameter bounds (outside 1–5) may cause validation error
- Payment failure via x402 protocol prevents request from being processed
- Network timeout to upstream OpenWeatherMap API

## How this service works

Global weather data — current conditions, 5-day forecasts, hourly forecasts, air quality index with pollutants, geocoding, and One Call 3.0 with full weather suite and government alerts.

## Output

Returns a JSON object containing an array of matching location results (up to the specified limit), each including city name, country, state, latitude, and longitude. Also includes x402 payment settlement details (USDC amount settled and authorized) and a request tracking ID with status URL.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "q": {
   "type": "string"
  },
  "limit": {
   "type": "number"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": {},
  "payment": {
   "scheme": "exact",
   "settledUsdc": "0.001000",
   "authorizedMaxUsdc": "0.001000"
  },
  "request": {
   "id": "00000000-0000-4000-8000-000000000000",
   "statusUrl": "/requests/00000000-0000-4000-8000-000000000000"
  },
  "success": true
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/openweather-geocoding-via-locus-x402-b5927d02/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from openweather.x402.paywithlocus.com](https://www.zero.xyz/host/openweather.x402.paywithlocus.com/llms.txt)