Forward geocode city names to lat/lon coordinates via OpenWeather, paid per-call with pathUSD on Tempo.
What it does
This endpoint provides forward geocoding powered by OpenWeather's geocoding API, accessible through the Locus MPP (Micropayment Protocol). Given a city name — optionally qualified with state and country code (e.g. "London,GB" or "Austin,TX,US") — it returns matching geographic coordinates. Results can be limited to 1–5 matches. Each call costs $0.005 (5,000 base units of pathUSD with 6 decimals), settled on Tempo L2.
The endpoint is part of a broader OpenWeather service suite hosted at openweather.mpp.paywithlocus.com that also includes current weather, 5-day forecasts, air quality, reverse geocoding, One Call 3.0, and weather overviews. The geocode endpoint accepts POST requests with a JSON body containing a required "q" field (city query string) and an optional "limit" field. Payment is handled via the MPP charge intent — each request triggers a one-shot micropayment.
Note: The probe did not capture a 402 challenge on HEAD/GET because this endpoint only responds to POST. The OpenAPI spec is well-defined with clear request schemas, payment metadata, and endpoint routing. No response schema is documented, so the exact shape of the returned geocoding data is not confirmed from the probe material, though it is expected to mirror OpenWeather's standard geocoding API response (array of location objects with name, lat, lon, country, state fields).
Capabilities
Use cases
- —Convert a city name into latitude/longitude before calling weather endpoints
- —Resolve ambiguous place names to specific coordinates for downstream location-based queries
- —Build location autocomplete or search features that resolve user-typed city names to coordinates
- —Agent workflows that need to chain geocoding into weather, air quality, or mapping calls
Fit
Best for
- —AI agents needing pay-per-call geocoding without API key management
- —Chaining city-name resolution into weather or air-quality lookups on the same MPP service
- —Low-volume or sporadic geocoding where per-call pricing ($0.005) is more economical than a subscription
Not for
- —High-volume batch geocoding (per-call cost adds up quickly)
- —Address-level or street-level geocoding (this resolves city-level queries only)
- —Free-tier usage — every call requires a micropayment
Quick start
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/geocode \
-H "Content-Type: application/json" \
-d '{"q": "London,GB", "limit": 3}'Example
Request
{
"q": "Austin,TX,US",
"limit": 3
}Endpoint
Quality
The OpenAPI spec provides a clear request schema and payment metadata for this endpoint. However, the probe did not capture a live 402 challenge (the endpoint is POST-only and was probed with HEAD/GET), no response schema is documented, and crawled pages returned only 404 JSON errors. The price and intent are well-specified in the OpenAPI x-payment-info block.
Warnings
- —Probe returned 404 on HEAD and GET — endpoint is POST-only; liveness not directly confirmed via 402 challenge
- —No response schema documented in OpenAPI; response shape is inferred from OpenWeather's public API docs
- —Currency address 0x20c000000000000000000000b9537d11c60e8b50 assumed to be pathUSD with 6 decimals based on Tempo L2 convention; not independently verified
Citations
- —Geocode endpoint accepts POST with q (required) and limit (optional) fields, costs 5000 base units via Tempo charge intenthttps://openweather.mpp.paywithlocus.com
- —Part of a broader OpenWeather service suite including current weather, forecasts, air quality, reverse geocoding, One Call 3.0, and weather overviewhttps://openweather.mpp.paywithlocus.com
- —OpenWeather API reference available at openweathermap.org/apihttps://openweathermap.org/api
- —LLM-oriented docs referenced at beta.paywithlocus.com/mpp/openweather.mdhttps://beta.paywithlocus.com/mpp/openweather.md