agentsvc.io

services / geocode

utilityoperational · 35 ms

Geocoding

Geocoding and reverse geocoding from GeoNames: city, town or postal code to lat/lon, and lat/lon to the nearest place and postal code. Covers 170,000 places with 1000+ inhabitants and 1.8 million postal codes worldwide, answered from our own database in milliseconds. Not street level: house numbers and streets are skipped and reported in ignored_parts. Provide address (e.g. 'Paris, Texas', '10115 Berlin') or lat + lon.

Run free trial ↗3 free calls per day with the example input. Paid: $0.003 USDC, no limit.

Call it

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agentsvc.io/api/v1/proxy/geocode", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"address":"Brandenburger Tor, Berlin"}),
});
const { data, payment } = await res.json();  // payment.status "settling"; header X-Payment-Settle: sync returns payment.transaction

Input

FieldTypeDescription

Output

FieldTypeDescription
modeforward | reverse'forward' if address was geocoded, 'reverse' if coordinates were looked up
resultsarray
ignored_partsarrayParts of the address that are not places (e.g. street and house number)
sourcestringAlways: 'GeoNames'
attributionstring

Example response (data)

{
  "mode": "forward",
  "results": [
    {
      "display_name": "Paris, Île-de-France, France",
      "lat": 48.85341,
      "lon": 2.3488,
      "type": "city",
      "precision": "locality",
      "address": {
        "city": "Paris",
        "state": "Île-de-France",
        "postcode": null,
        "country": "France",
        "country_code": "fr"
      },
      "population": 2138551,
      "timezone": "Europe/Paris",
      "geonames_id": 2988507
    }
  ],
  "ignored_parts": [
    "Avenue Anatole France 5"
  ],
  "source": "GeoNames",
  "attribution": "Place data from GeoNames (geonames.org), CC BY 4.0"
}