Skip to content

Place lookup (worldwide)

$0.001 per callUSDC via x402GET /api/place-lookupCached 1d

Resolve a city, town, region or postal-code name to coordinates worldwide: latitude and longitude, country, region, timezone, population, elevation and postcodes, best match first. Send GET /api/place-lookup with the required field q and pay $0.001 per call over x402 or MPP (there is no free tier). It returns a JSON object with query, found, count, results, source and 1 more.

Add a qualifier after a comma ("Austin, TX", "Paris, France") or a two-letter country filter. It finds places (cities, towns, regions and postal codes), not street addresses: a street address answers found: false. ?q=Pittsburgh&country=US. Place data from GeoNames (CC BY 4.0).

Category: Live public dataTags: place geocode city coordinates timezone location

Try in playground →

Parameters

NameTypeRequiredDescription
qstringyesPlace name, optionally with a qualifier after a comma: "Pittsburgh", "Austin, TX", "Paris, France" Also accepted as query, search, term, keyword.
countnumbernoResults to return, 1-10 (default 5)
countrystringnoTwo-letter ISO 3166-1 country code to search within, for example US
languagestringnoTwo-letter language code for names (default en)

Example request

curl -i "https://agent402.tools/api/place-lookup?q=Pittsburgh&country=US"

Without payment this returns HTTP 402 Payment Required with the exact price for place-lookup; any x402 v2 or MPP client pays it and retries.

Example response

{
  "query": "Pittsburgh",
  "found": true,
  "count": 1,
  "results": [
    {
      "name": "Pittsburgh",
      "lat": 40.44062,
      "lon": -79.99589,
      "country": "United States",
      "countryCode": "US",
      "region": "Pennsylvania",
      "district": "Allegheny County",
      "timezone": "America/New_York",
      "population": 304391,
      "elevation": 233,
      "featureCode": "PPLA2",
      "postcodeCount": 73,
      "postcodes": [
        "15201",
        "15202",
        "15203"
      ]
    }
  ],
  "source": "geocoding-api.open-meteo.com (GeoNames, CC BY 4.0)",
  "credit": "Place data from GeoNames (CC BY 4.0)."
}
FieldTypeAlways presentIn the example
querystringyesPittsburgh
foundbooleanyestrue
countnumberyes1
resultsarray of objectsyes1 item in the example
sourcestringyesgeocoding-api.open-meteo.com (GeoNames, CC BY 4.0)
creditstringyesPlace data from GeoNames (CC BY 4.0).

From an MCP client

catalog.call {
  "slug": "place-lookup",
  "params": {
    "q": "Pittsburgh",
    "country": "US"
  }
}

The hosted connector at https://agent402.tools/mcp needs a payment for place-lookup; the stdio package pays it from a wallet or from an AGENT402_CREDITS_KEY issued earlier. Local install: npx -y agent402-mcp@0.13.32.

Errors and behavior

Paid call (JavaScript agent)

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

const client = new x402Client();
client.setSpendControls?.({ maxAmountPerPayment: "$0.001" }); // refuse any quote above this tool's price
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agent402.tools/api/place-lookup?q=Pittsburgh&country=US");

Part of these workflows

Place lookup (worldwide) is one step in these 2 skill packs, each sold as a single call:

Related tools

Country info

FREE w/ computeor $0.001GET /api/country-info

Country facts by name or ISO code: official name, capital, region, currencies, languages, timezones, dialing code, TLD.

US location lookup (lat/lon)

$0.003GET /api/geo-lookup

Resolve a US latitude/longitude to its county, state, and census block FIPS via the US Census Bureau geocoder.

Timezone convert

FREE w/ computeor $0.001GET /api/timezone-convert

Convert a datetime from one IANA timezone to another.

A2A Agent Card validate

FREE w/ computeor $0.002POST /api/a2a-card-validate

Validate an A2A (Agent2Agent protocol) Agent Card: required fields, skill shape, transport names, capability flags.

Amortization schedule

FREE w/ computeor $0.001POST /api/amortization

Build the full per-period amortization schedule for a fully-amortizing loan.

Annuity present/future value

FREE w/ computeor $0.001POST /api/annuity

Present and future value of a level annuity (equal periodic payments).