$ man address-geocode
/address-geocode(1)
PRICE / CALL
$0.02
USDC · base mainnet · scheme: exact
METHOD
POST
CLUSTER
localeCATEGORY
utilities
STATUS
● live
NAME
address-geocode — geocoder / address-to-lat-lng / location resolver
SYNOPSIS
POST https://x402.org/v1/address-geocode
Content-Type: application/json
X-PAYMENT: <signed-transferWithAuthorization>
{ ... }↳ first call →
402 Payment Required. Sign USDCtransferWithAuthorization, retry with theX-PAYMENT header.DESCRIPTION
Geocoder / address-to-lat-lng / location resolver. Address or place-name → coords + structured parts (road, city, state, postcode, country). Powered by OpenStreetMap Nominatim (free public).
INPUT — request schema
| property | type | description | req? |
|---|---|---|---|
| address | string | Free-form address, postal code, place name, or POI. Examples: '1600 Amphitheatre Parkway, Mountain View, CA', '10115 Berlin', 'Eiffel Tower'. | required |
| country_codes | array | Optional ISO 3166-1 alpha-2 filter, e.g. ['us','ca']. | optional |
| limit | number | 1-10. Default 5. | optional |
OUTPUT — response shape
| field | type | description |
|---|---|---|
| query | string | Echo of the address or place-name string that was geocoded. |
| match_count | number | Number of candidate matches Nominatim returned for the query. |
| results | array | Array of geocoded candidates, each with lat/lng plus parsed road, city, state, postcode, and country parts. |
| best_match | object | Top-ranked candidate object with coordinates and structured address parts for the most likely location. |
| source | string | Upstream geocoding provider that produced the results, e.g. 'openstreetmap-nominatim'. |
EXAMPLES — two ways to call
EXAMPLE 1 · curl
curl -X POST https://x402.org/v1/address-geocode \
-H 'Content-Type: application/json' \
-d '{ }'first response =
402 Payment Required with payment requirements; sign + retry with X-PAYMENT.EXAMPLE 2 · mcp
# install once claude mcp add x402 --command "npx x402-deployer-mcp" # then ask Claude Code: # "use the address-geocode tool to ..."
MCP server handles payment automatically — your coding agent just calls the tool by name.
METADATA
- tags
- geocodelocationmapsosmnominatim
- methods
- POST
- cluster
- locale
- price
- $0.02 USDC per call
ADJACENT — other endpoints in locale
| endpoint | description | price |
|---|---|---|
| airport-delays | FAA NAS Status — current US airport delays, ground stops, ground delay programs, weather-driven program changes. | $0.02 |
| bin-lookup | Credit card BIN / IIN lookup. | $0.02 |
| card-bin-lookup | Credit card BIN lookup / IIN lookup / card-issuer lookup. | $0.02 |
| reverse-geocode | Reverse geocoder / lat-lng-to-address. | $0.02 |
| satellite-bbox | Bounding-box satellite composite / Sentinel-2 cloud-free mosaic / region satellite snapshot / arbitrary bbox to imagery. | $0.02 |
| building-permits | Building permits multi-city open-data lookup. | $0.03 |
| flight-status | Flight status / live aircraft position / flight tracker / ICAO24 lookup / callsign lookup / aircraft bounding-box / OpenSky Network state… | $0.01 |
| property-tax | Property tax lookup. | $0.01 |
SEE ALSO