# Mapbox Forward Geocoding

> Mapbox Forward Geocoding is a paid API for AI agents from Mapbox at mapbox.mpp.paywithlocus.com, paid per call via MPP, $0.00375/call, status healthy (last checked 2026-10-11, last successful call 2026-09-12).

Converts a text address or place name into geographic coordinates (latitude/longitude) with contextual location metadata

## Facts

- Endpoint: POST https://mapbox.mpp.paywithlocus.com/mapbox/geocode-forward?utm_source=zero.xyz
- Price: $0.00375/call
- Payment: MPP
- Status: healthy
- Last checked: 2026-10-11
- Last successful call: 2026-09-12
- Success rate: 100% of calls made through Zero
- Rating: 5.0 / 5 from 1 review
- Activations on Zero: 3
- Provider: Mapbox
- Docs: https://docs.mapbox.com/api/
- Website: https://www.mapbox.com
- Tags: maps, geocoding, directions, routing, geospatial, data
- Canonical page: https://www.zero.xyz/c/mapbox-geocode-forward-7c2c84a6
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_E0cpvigwGq0BnkZ-MDR7h

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 mapbox-geocode-forward-7c2c84a6 -d '<json body>'
```

Example prompt: What are the coordinates for the Eiffel Tower in Paris? Search in France, return English results, and give me up to 3 matches.

## When to prefer this

Use this endpoint when you need to convert human-readable address or place name text into geographic coordinates, especially when you need rich administrative context (region, country, neighborhood). Prefer this over reverse geocoding when starting from text rather than coordinates. The Mapbox-specific output includes Wikidata IDs and multilingual translations, making it suitable for enriching location data pipelines or mapping applications.

## Known failure modes

- Empty results when query text is too vague or misspelled
- No features returned if country filter excludes the actual location
- Coordinates may be approximate for partial or ambiguous addresses
- Invalid bbox format returns an error
- Limit values outside 1-10 range may be rejected
- Unsupported language tags may fall back to default language

## How this service works

Convert an address or place name to geographic coordinates (longitude, latitude).

## Output

A GeoJSON FeatureCollection containing matched place features, each with Point geometry (lon/lat coordinates), a display name, Mapbox place ID, Wikidata ID, and nested administrative context (street, neighborhood, place, region, country) with translations.

## Example request

```json
{
 "q": "Eiffel Tower, Paris",
 "limit": 3,
 "country": "fr",
 "language": "en"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "q"
 ],
 "properties": {
  "q": {
   "type": "string",
   "description": "Search text (address, place name, etc.)"
  },
  "bbox": {
   "type": "string",
   "description": "Bounding box to limit results: \"minLon,minLat,maxLon,maxLat\""
  },
  "limit": {
   "type": "number",
   "description": "Maximum number of results (1-10, default 5)"
  },
  "types": {
   "type": "string",
   "description": "Filter by feature type: country, region, postcode, district, place, locality, neighborhood, address, street, block"
  },
  "country": {
   "type": "string",
   "description": "Comma-separated ISO 3166-1 alpha-2 country codes"
  },
  "language": {
   "type": "string",
   "description": "IETF language tag for results (e.g. \"en\", \"fr\")"
  },
  "proximity": {
   "type": "string",
   "description": "Bias results near a coordinate: \"lon,lat\" or \"ip\""
  },
  "worldview": {
   "type": "string",
   "description": "Worldview code (e.g. \"us\", \"cn\", \"jp\")"
  },
  "autocomplete": {
   "type": "boolean",
   "description": "Enable autocomplete for partial queries (default true)"
  }
 },
 "additionalProperties": true
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/mapbox-geocode-forward-7c2c84a6/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from mapbox.mpp.paywithlocus.com](https://www.zero.xyz/host/mapbox.mpp.paywithlocus.com/llms.txt)