Mapbox forward geocoding via MPP — convert addresses and place names to coordinates, pay-per-call with pathUSD on Tempo.
What it does
This endpoint provides Mapbox forward geocoding through the Locus MPP (Micropayment Protocol) gateway. It accepts a search query (address, place name, etc.) and returns geographic coordinates and structured location data. The endpoint is part of a broader Mapbox suite available through the same gateway, which also includes reverse geocoding, directions, matrix routing, isochrones, map matching, static images, and tile queries.
The forward geocode endpoint accepts POST requests with a JSON body. The only required field is `q` (the search text), but you can refine results with optional parameters including `proximity` (bias toward a coordinate or IP), `bbox` (bounding box filter), `country` (ISO 3166-1 alpha-2 codes), `language` (IETF tag), `limit` (1–10 results), `types` (feature type filter such as address, place, region, postcode), `autocomplete` (for partial queries), and `worldview`. Pricing is 3,750 base units of pathUSD (6 decimals), which works out to $0.00375 per request, settled on Tempo L2.
The endpoint is served at `https://mapbox.mpp.paywithlocus.com/mapbox/geocode-forward` and uses the MPP charge intent — meaning each call is a one-shot payment. The probe returned 404 on HEAD/GET, which is expected since this is a POST-only endpoint per the OpenAPI spec. The OpenAPI schema is well-documented with clear parameter descriptions and required fields.
Capabilities
Use cases
- —Converting user-entered addresses into latitude/longitude coordinates for mapping applications
- —Autocomplete-powered address search in forms or chatbots
- —Filtering location results by country or bounding box for region-specific applications
- —Batch geocoding of address lists for spatial analysis
- —Agent-driven location lookups where per-call crypto payment is preferred over API key management
Fit
Best for
- —AI agents needing geocoding without managing Mapbox API keys
- —Pay-per-call geocoding with no subscription or account required
- —Applications that settle payments on Tempo L2 with pathUSD
- —Developers wanting Mapbox-quality geocoding through a standardized micropayment protocol
Not for
- —High-volume batch geocoding where a direct Mapbox subscription would be cheaper
- —Applications requiring free-tier geocoding with zero cost per call
- —Use cases needing the full Mapbox Search v2 structured input or batch endpoints
Quick start
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/geocode-forward \
-H "Content-Type: application/json" \
-d '{"q": "1600 Pennsylvania Ave NW, Washington DC"}'Example
Request
{
"q": "1600 Pennsylvania Ave NW, Washington DC",
"limit": 3,
"types": "address",
"country": "US",
"language": "en"
}Endpoint
Quality
The OpenAPI schema is detailed with clear parameter descriptions, pricing info, and required fields. However, the probe returned 404 on HEAD/GET (expected for a POST-only endpoint), no example response is available, and crawled pages yielded no additional documentation. The endpoint is likely live but liveness could not be confirmed via the probe methods used.
Warnings
- —Probe returned 404 on HEAD and GET — endpoint is POST-only per OpenAPI spec, so liveness is not confirmed but plausible
- —No example response body available; response schema is not documented beyond '200: Successful response'
- —Currency address 0x20c000000000000000000000b9537d11c60e8b50 assumed to be pathUSD with 6 decimals based on Tempo L2 convention; if decimals differ, price would change
- —All crawled pages returned 404 JSON errors; no supplementary documentation was retrievable from the gateway itself
Citations
- —Forward geocode endpoint accepts POST with required field 'q' and optional parameters including proximity, bbox, country, language, limit, types, autocomplete, worldviewhttps://mapbox.mpp.paywithlocus.com
- —Pricing is 3750 base units settled via Tempo method with charge intenthttps://mapbox.mpp.paywithlocus.com
- —Part of a broader Mapbox suite including reverse geocoding, directions, matrix, isochrone, map matching, static images, and tilequeryhttps://mapbox.mpp.paywithlocus.com
- —Mapbox API reference available at docs.mapbox.com/api/https://docs.mapbox.com/api/Mapbox