# Forward Geocoding API (OpenStreetMap Nominatim)

> Forward Geocoding API (OpenStreetMap Nominatim) is a paid API for AI agents from x402.donnyautomation.com, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-15).

Converts a street address, city, or place name into latitude/longitude coordinates with structured address parts, bounding box, and confidence score via OpenStreetMap Nominatim.

## Facts

- Endpoint: GET https://x402.donnyautomation.com/geocode
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/forward-geocoding-api-openstreetmap-nominatim-18f62956
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_2sLHjiaQvYB8GKGQ-4CT5

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 forward-geocoding-api-openstreetmap-nominatim-18f62956
```

Example prompt: What are the latitude and longitude coordinates for 1600 Amphitheatre Parkway, Mountain View, California?

## When to prefer this

Choose this endpoint when you need worldwide forward geocoding without maintaining your own geocoding infrastructure, especially when confidence scoring and structured address decomposition are important. Prefer this over reverse geocoding services when you have a human-readable address or place name as input. The OpenStreetMap Nominatim backend provides broad global coverage suitable for mapping, logistics, travel, and location-aware agents. The 404-on-no-match behavior makes it safe for automated pipelines that need to detect lookup failures explicitly.

## Known failure modes

- 404 returned when no matching location is found for the query
- Ambiguous place names may return multiple ranked results requiring the caller to select the best match
- Very long or malformed query strings (over 300 chars) may be rejected
- Rare or highly localized addresses with no OpenStreetMap coverage may not resolve

## How this service works

Forward geocoding: street address or place name to latitude/longitude, worldwide, via OpenStreetMap Nominatim. Returns best {lat, lon, displayName, type, importance}, count and attribution. Requires ?q=<address or place name>, max 300 chars. Errors: 400 missing_query|query_too_long, 404 no_match - a coordinate is never guessed, 502 geocoder_unavailable|geocoder_failed. The OPPOSITE direction (coordinates to an address) is /reverse-geocode. /weather needs lat+lon, so call this first.

## Output

Returns a ranked list of matches, each containing latitude, longitude, a human-readable display name, structured address components (road, city, country, postcode, etc.), a bounding box, and an importance score indicating match confidence. Returns 404 if no match is found — never a silently wrong guessed coordinate.

## 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": [
      "q"
     ],
     "properties": {
      "q": {
       "type": "string",
       "description": "Street address or place name, e.g. \"1600 Amphitheatre Parkway, Mountain View\" or \"Eiffel Tower, Paris\". Max 300 chars."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "ts": "2026-08-01T00:00:00.000Z",
  "best": {
   "lat": 48.8583,
   "lon": 2.2945,
   "type": "attraction",
   "importance": 0.71,
   "displayName": "Tour Eiffel, Avenue Gustave Eiffel, Paris, France"
  },
  "count": 1,
  "query": "Eiffel Tower, Paris",
  "attribution": "Data © OpenStreetMap contributors, ODbL. Geocoding via Nominatim."
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/forward-geocoding-api-openstreetmap-nominatim-18f62956/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402.donnyautomation.com](https://www.zero.xyz/host/x402.donnyautomation.com/llms.txt)