Reverse geocoding API (offline city data)

POST lat and lon to /v1/geocode to get the nearest city and its distance in kilometres. Send place instead for forward geocoding with up to 5 candidates. It uses an offline GeoNames table, with no street addresses.

Request

Give either lat with lon (reverse) or place such as "Manila, PH" (forward), not both.

curl, using the free tier

curl -s -X POST https://tanod.dev/v1/geocode \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"lat":14.5995,"lon":120.9842}'

Response

Response (a real call)

{
  "mode": "reverse",
  "query": {"lat": 14.5995, "lon": 120.9842},
  "results": [{
    "name": "Santa Cruz",
    "country_code": "PH",
    "admin1_code": "NCR",
    "lat": 14.6,
    "lon": 120.98333,
    "population": 126735,
    "timezone": "Asia/Manila",
    "distance_km": 0.11
  }],
  "attribution": {
    "places": "GeoNames (geonames.org), CC BY 4.0",
    "license": "https://creativecommons.org/licenses/by/4.0/"
  }
}

Limits and caveats

City level only. The data is the GeoNames cities15000 table: cities of 15,000 or more people. The result is the nearest such city, which can be some distance away; check distance_km. There are no street addresses.

Attribution. Place data is from GeoNames (geonames.org), licensed CC BY 4.0, reduced to selected columns. Credit GeoNames when you show or republish it.

No match for a forward query is a 404 place_not_found and is not charged.

Price and free allowance

USD 0.001 per call, paid in USDC on Base with x402. 10 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared with FX rates, QR and holidays. MCP tool: geocode at https://tanod.dev/mcp, where the free tier is automatic.

All endpoints →

Related guides: Weather forecast API without an API key, Public holidays API, How to generate a QR code via API. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.