Geocoding API: place names to coordinates for agents

Geocoding API for AI agents and apps: convert a place name or address to latitude and longitude for $0.001 USDC per call through x402 on Base. Cached results, no signup, no API key.

Endpoint

POST https://apisphere.us.ci/api/v1/geocode converts a place name or address into latitude/longitude results backed by OpenStreetMap data. A plain GET only advertises the x402 payment challenge - send data over POST.

  • Price: $0.001 USDC per call, settled on Base through x402.
  • Freshness: results are fresh for one hour, then served stale for up to 30 minutes while fresh data is refetched.

Request fields

Send a JSON body. Pass either query or its alias address. Invalid bodies return 400 with field-level details.

  • query (required unless address is set): 1 to 200 characters - e.g. "Monas, Jakarta".
  • address (alias): accepted as a synonym for query.
  • limit (optional): integer from 1 to 10, defaults to 1.
Paid request
curl -X POST https://apisphere.us.ci/api/v1/geocode \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <signed-payment-payload>" \
  -d '{"query": "Monas, Jakarta"}'

Response

A 200 response returns a results array with coordinates, a formatted display name, and the match type, plus a meta block with the cache state and request id.

  • 400 - invalid query or limit (details in the response).
  • 402 - missing or invalid payment.
  • 429 - rate limited; honor Retry-After.
  • 500 - internal error; every response carries X-Request-Id for support.
  • 502 - upstream provider error; the same request is safe to retry.
Example 200 body
{
  "results": [
    {
      "query": "Monas, Jakarta",
      "latitude": -6.1754024,
      "longitude": 106.8271692,
      "displayName": "Monumen Nasional, Jakarta, Indonesia",
      "type": "monument",
      "importance": 0.42
    }
  ],
  "meta": {
    "cache": "miss",
    "request_id": "7f3a9c2e-1b4d-4f6a-8c2e-9d1f5a3b7c4e"
  }
}