Place lookup (worldwide)
GET /api/place-lookupCached 1dResolve 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).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | yes | Place name, optionally with a qualifier after a comma: "Pittsburgh", "Austin, TX", "Paris, France" Also accepted as query, search, term, keyword. |
count | number | no | Results to return, 1-10 (default 5) |
country | string | no | Two-letter ISO 3166-1 country code to search within, for example US |
language | string | no | Two-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)."
}| Field | Type | Always present | In the example |
|---|---|---|---|
query | string | yes | Pittsburgh |
found | boolean | yes | true |
count | number | yes | 1 |
results | array of objects | yes | 1 item in the example |
source | string | yes | geocoding-api.open-meteo.com (GeoNames, CC BY 4.0) |
credit | string | yes | Place 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
qis required. An input the tool rejects returns an HTTP 4xx whose body carrieserror,tool,expected,requiredandexample, so the caller can correct it.- A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement runs after the tool and only on a successful response. The exception is a Tempo push credential, a transfer the buyer sent before the call: it settles before the tool runs, so if the tool then fails the payment is recorded as a refund owed to the paying wallet.
- Wallet-only: this tool reaches the network or stored state, so it has no proof-of-work tier. A prepaid card-credits key issued earlier (
Authorization: Bearer a402_...) also pays it. - Cached: an identical request within 1d is answered from cache with
X-Cache: hit. - A
POSTwith a JSON body to /api/place-lookup is served as this GET, with the body as the input. - An
Idempotency-Keyheader makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB is not replayed).
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:
- Location intel - Location intel skill: one call turns a place name into a situational brief: coordinates, country, region and timezone, the US county and state when the place is in the United States, a three-day weather forecast anywhere on Earth, active US hazard alerts, and the past week's magnitude 2.5 and larger earthquakes worldwide.
- Multi-stop trip planner - Plan a multi-stop journey deterministically: resolve each stop to coordinates, sum the pairwise haversine distances, estimate arrival times by adding driving hours per leg, count business days from today to each arrival, and pull the daily weather forecast at every stop, anywhere in the world. Six tools - four pure-CPU (math + time), two egress (place lookup + weather) - covering the deterministic skeleton of every road-trip / sales-tour / delivery-route planning problem.
Related tools
Country info
Country facts by name or ISO code: official name, capital, region, currencies, languages, timezones, dialing code, TLD.
US location lookup (lat/lon)
Resolve a US latitude/longitude to its county, state, and census block FIPS via the US Census Bureau geocoder.
Timezone convert
Convert a datetime from one IANA timezone to another.
A2A Agent Card validate
Validate an A2A (Agent2Agent protocol) Agent Card: required fields, skill shape, transport names, capability flags.
Amortization schedule
Build the full per-period amortization schedule for a fully-amortizing loan.
Annuity present/future value
Present and future value of a level annuity (equal periodic payments).