# Locus x402 Forward Geocoding (Mapbox)

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

Converts a place name or address string into geographic coordinates and structured location data, billed per-call via x402 micropayments

## Facts

- Endpoint: POST https://mapbox.x402.paywithlocus.com/mapbox/geocode-forward
- Price: $0.00375/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/locus-x402-forward-geocoding-mapbox-58ff9da6
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_bBDBBgXdDEnmxJOrIw4_S

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 locus-x402-forward-geocoding-mapbox-58ff9da6 -d '<json body>'
```

Example prompt: Can you geocode '1600 Pennsylvania Avenue NW, Washington DC' and give me the coordinates? Limit results to 1 and filter to addresses only in the US.

## When to prefer this

Choose this endpoint when you need pay-per-use forward geocoding without a monthly subscription, especially in agentic or serverless workflows where usage is unpredictable. Prefer it over direct Mapbox API access when you want micropayment billing via x402 USDC with no API key management. It is well-suited for agents that geocode addresses on-demand, need autocomplete for partial queries, or require worldview-aware results for international use cases.

## Known failure modes

- Empty features array if no match found for the query string
- Rate limiting or payment failure if x402 USDC balance is insufficient
- Invalid bbox format returns a 400 error
- Unsupported language tag may fall back to English results
- Overly vague queries may return low-relevance or irrelevant results
- Country or type filters may reduce results to zero if too restrictive

## How this service works

Locus public pay-per-use API

## Output

Returns a GeoJSON FeatureCollection of matching places, each with geometry (coordinates), place_name (formatted address), text (short name), place_type, relevance score, and context array (country, region, postcode, etc.). Results are ranked by relevance and proximity bias.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "q": {
   "type": "string"
  },
  "bbox": {
   "type": "string"
  },
  "limit": {
   "type": "number"
  },
  "types": {
   "type": "string"
  },
  "country": {
   "type": "string"
  },
  "language": {
   "type": "string"
  },
  "proximity": {
   "type": "string"
  },
  "worldview": {
   "type": "string"
  },
  "autocomplete": {
   "type": "boolean"
  }
 }
}
```

## 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/locus-x402-forward-geocoding-mapbox-58ff9da6/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from mapbox.x402.paywithlocus.com](https://www.zero.xyz/host/mapbox.x402.paywithlocus.com/llms.txt)