# Geocode (Forward & Reverse) via Mapbox

> Geocode (Forward & Reverse) via Mapbox is a paid API for AI agents from ZeroClick x402 Service Registry at geocode.withzero.ai, paid per call via MPP, $0.01/call, status unknown (last checked 2026-10-10, last successful call 2026-07-02).

Converts addresses or place names to lat/lng coordinates (forward geocoding) and lat/lng coordinates back to human-readable addresses (reverse geocoding) using Mapbox.

## Facts

- Endpoint: POST https://geocode.withzero.ai/run?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-10
- Last successful call: 2026-07-02
- Success rate: 100% of calls made through Zero
- Rating: 3.2 / 5 from 2 reviews
- Activations on Zero: 8
- Provider: ZeroClick x402 Service Registry
- Website: https://withzero.ai
- Tags: location, geocode, address, coordinates, mapbox, maps
- Canonical page: https://www.zero.xyz/c/zeroclick-x402-service-registry-geocode-1c35bb1d
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_54NEjaAapUn1GhF9ZxxIy

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 zeroclick-x402-service-registry-geocode-1c35bb1d -d '<json body>'
```

Example prompt: Can you forward-geocode '1600 Pennsylvania Avenue NW, Washington DC' and give me the top 3 results with their coordinates and relevance scores?

## When to prefer this

Use this endpoint when you need to convert between human-readable addresses and geographic coordinates, or vice versa, with relevance scoring and multiple result candidates. Backed by Mapbox's high-quality geocoding data, it supports country-biasing and returns typed features (POI, address, neighborhood, etc.), making it ideal for location enrichment, map pin placement, address validation, or any workflow that requires precise lat/lng from text input.

## Known failure modes

- No results found for an ambiguous or misspelled query — returns empty features array with count 0
- Invalid lat/lng range (lat outside -90 to 90 or lng outside -180 to 180) — schema validation error
- Missing required field: forward geocoding without query, or reverse geocoding without lat/lng
- Country code not a valid ISO 2-letter code — may return unbiased results or error
- Limit outside 1-10 range — schema validation rejection
- Service unavailable from upstream Mapbox API — may return 5xx error

## How this service works

Forward and reverse geocoding via Mapbox. Forward: convert an address or place name to latitude/longitude coordinates. Reverse: convert lat/lng coordinates back to a human-readable address. Input: `action` (forward/reverse), `query` for forward (address string), `lat` + `lng` for reverse (decimal degrees). Optional `country` (ISO 2-letter code) to bias results, `limit` (1-10, default 5). Returns: `features` array of {name, full_address, lat, lng, type, relevance}, `count` of results. Relevance is 0.0-1.0 (higher = better match). Types: address, place, postcode, locality, neighborhood, region, country, poi.

## Output

An array of up to 10 geocoding features, each with a short place name, full formatted address, latitude, longitude, feature type (address, place, poi, postcode, neighborhood, locality, region, country), and a relevance score from 0.0 to 1.0. Also includes a count of total results returned.

## Example request

```json
{
 "limit": 5,
 "query": "Statue of Liberty, New York",
 "action": "forward"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "lat": {
   "type": "number",
   "maximum": 90,
   "minimum": -90,
   "description": "Latitude for reverse geocoding"
  },
  "lng": {
   "type": "number",
   "maximum": 180,
   "minimum": -180,
   "description": "Longitude for reverse geocoding"
  },
  "limit": {
   "type": "integer",
   "default": 5,
   "maximum": 10,
   "minimum": 1,
   "description": "Max results to return (1-10, default 5)"
  },
  "query": {
   "type": "string",
   "maxLength": 500,
   "minLength": 1,
   "description": "Address or place name for forward geocoding"
  },
  "action": {
   "enum": [
    "forward",
    "reverse"
   ],
   "type": "string",
   "default": "forward",
   "description": "forward: address→coordinates; reverse: coordinates→address"
  },
  "country": {
   "type": "string",
   "maxLength": 2,
   "minLength": 2,
   "description": "ISO 2-letter country code to bias results (e.g. us, gb, de)"
  }
 },
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "features",
  "count"
 ],
 "properties": {
  "count": {
   "type": "number",
   "description": "Number of results returned"
  },
  "features": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "name",
     "full_address",
     "lat",
     "lng",
     "type",
     "relevance"
    ],
    "properties": {
     "lat": {
      "type": "number",
      "description": "Latitude"
     },
     "lng": {
      "type": "number",
      "description": "Longitude"
     },
     "name": {
      "type": "string",
      "description": "Short place name"
     },
     "type": {
      "type": "string",
      "description": "Feature type (address, place, poi, etc.)"
     },
     "relevance": {
      "type": "number",
      "description": "Match relevance score 0.0-1.0"
     },
     "full_address": {
      "type": "string",
      "description": "Full formatted address"
     }
    },
    "additionalProperties": false
   },
   "description": "Geocoding results"
  }
 },
 "additionalProperties": false
}
```

## More

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