# AgentUtility Geocode

> AgentUtility Geocode is a paid API for AI agents from x402.agentutility.ai, paid per call via x402, $0.02/call, status unknown (last checked 2026-11-06).

Converts a free-form address, place name, or postal code into geographic coordinates (latitude/longitude) with display name, using OpenStreetMap Nominatim.

## Facts

- Endpoint: POST https://x402.agentutility.ai/geocode?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-06
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agentutility-geocode-bf21a3d8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_b5Bswn6b1U6LCpV1n3DSQ

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 agentutility-geocode-bf21a3d8 -d '<json body>'
```

Example prompt: Can you geocode '1600 Amphitheatre Parkway, Mountain View, CA' and give me the latitude and longitude?

## When to prefer this

Use this endpoint when you need quick, pay-per-call geocoding without managing API keys or subscriptions. It is ideal for AI agents that occasionally need to resolve addresses or place names to coordinates. The OpenStreetMap Nominatim backend provides broad global coverage. Prefer this over reverse geocoding endpoints when you have a text address and need coordinates, not the other way around.

## Known failure modes

- Ambiguous or misspelled address returns zero results (match_count: 0, empty results array)
- Very rural or non-standard addresses may return low-quality or unexpected matches
- Country code filter too restrictive combined with vague address yields no results
- Exceeding limit bounds (outside 1-10) may cause validation errors
- Rate limiting or upstream Nominatim unavailability could return 5xx errors

## How this service works

817 pay-per-call APIs for AI agents. Every endpoint is POST /<name> and is payable in USDC over x402 on Base and Solana — no signup, no API key, just pay-per-call. GET https://x402.agentutility.ai/ returns the same catalog as machine-readable JSON.

## Output

Returns a JSON object with the original query string, the data source attribution (OpenStreetMap Nominatim, ODbL license), an array of up to N result objects each containing latitude, longitude, and display_name, the best_match object (top result), and a match_count integer.

## 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",
    "bodyType",
    "body"
   ],
   "properties": {
    "body": {
     "required": [
      "address"
     ],
     "properties": {
      "limit": {
       "type": "number",
       "description": "Max results to return. 1-10. Default 5."
      },
      "address": {
       "type": "string",
       "description": "Free-form address, postal code, place name, or POI. Examples: '1600 Amphitheatre Parkway, Mountain View, CA', '10115 Berlin', 'Eiffel Tower'."
      },
      "country_codes": {
       "type": "array",
       "description": "Optional ISO 3166-1 alpha-2 country codes to restrict results, e.g. ['us', 'ca']."
      }
     }
    },
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "POST"
     ],
     "type": "string"
    },
    "bodyType": {
     "enum": [
      "json",
      "form-data",
      "text"
     ],
     "type": "string"
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "query": {
       "type": "string"
      },
      "source": {
       "type": "string"
      },
      "results": {
       "type": "array",
       "items": {
        "type": "object",
        "properties": {
         "latitude": {
          "type": "number"
         },
         "longitude": {
          "type": "number"
         },
         "display_name": {
          "type": "string"
         }
        }
       }
      },
      "best_match": {
       "type": "object",
       "properties": {
        "latitude": {
         "type": "number"
        },
        "longitude": {
         "type": "number"
        },
        "display_name": {
         "type": "string"
        }
       }
      },
      "match_count": {
       "type": "integer"
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "query": "Eiffel Tower",
  "source": "OpenStreetMap Nominatim (ODbL, attribution required)",
  "results": [
   {
    "latitude": 48.8582599,
    "longitude": 2.2945006,
    "display_name": "Tour Eiffel, Paris, Ile-de-France, France"
   }
  ],
  "best_match": {
   "latitude": 48.8582599,
   "longitude": 2.2945006,
   "display_name": "Tour Eiffel, Paris, Ile-de-France, France"
  },
  "match_count": 1
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agentutility-geocode-bf21a3d8/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402.agentutility.ai](https://www.zero.xyz/host/x402.agentutility.ai/llms.txt)