Skip to content
Free static example · no wallet required

Global place geocode

Inspect the exact response envelope first. When you need current analysis for your own input, one successful x402 call costs $0.002 USDC on Base or Solana.

Run a fresh result · $0.002 USDCReview schemaRaw JSON
No accountNo subscriptionExact USDC priceFresh calls only are paid
Full response envelope

What you receive

Demonstration data only. The paid endpoint returns a fresh result and settlement receipt.

{
  "request_id": "018f1f54-7f38-7ba2-8dc3-5f90272d9f1a",
  "service": "data.place-geocode",
  "version": "1",
  "data": {
    "version": "apiacre-place-geocode/1",
    "query": {
      "place": "London, GB",
      "normalized": "london, gb",
      "limit": 5
    },
    "candidateCount": 2,
    "candidateCountCapped": false,
    "ambiguous": true,
    "resultsTruncated": false,
    "results": [
      {
        "rank": 1,
        "geonameId": 2643743,
        "name": "London",
        "matchedNameType": "primary",
        "country": {
          "code": "GB",
          "name": "United Kingdom",
          "iso3": "GBR",
          "continentCode": "EU"
        },
        "admin1": {
          "code": "ENG",
          "name": "England"
        },
        "coordinates": {
          "latitude": 51.50853,
          "longitude": -0.12574
        },
        "population": 8961989,
        "timezone": "Europe/London",
        "featureCode": "PPLC",
        "modifiedOn": "2026-08-17"
      },
      {
        "rank": 2,
        "geonameId": 2643741,
        "name": "City of London",
        "matchedNameType": "alternate",
        "country": {
          "code": "GB",
          "name": "United Kingdom",
          "iso3": "GBR",
          "continentCode": "EU"
        },
        "admin1": {
          "code": "ENG",
          "name": "England"
        },
        "coordinates": {
          "latitude": 51.51279,
          "longitude": -0.09184
        },
        "population": 8072,
        "timezone": "Europe/London",
        "featureCode": "PPLA3",
        "modifiedOn": "2021-02-17"
      }
    ],
    "source": {
      "provider": "GeoNames",
      "dataset": "GeoNames cities500",
      "snapshotBuiltOn": "2026-08-18",
      "placeRecords": 235408,
      "aliasRecords": 766415,
      "homeUrl": "https://www.geonames.org/",
      "downloadUrl": "https://download.geonames.org/export/dump/",
      "license": "CC BY 4.0",
      "licenseUrl": "https://creativecommons.org/licenses/by/4.0/",
      "attribution": "GeoNames (CC BY 4.0; https://www.geonames.org/).",
      "transformation": "API Acre normalizes exact names and qualifiers, then ranks matches by alias quality, population, and stable GeoName ID.",
      "networkRequestsMade": 0
    },
    "limitations": [
      "Coverage follows the GeoNames cities500 extract: populated places above 500 residents and administrative seats through PPLA4, subject to source completeness and accuracy.",
      "Matching is exact after Unicode-to-ASCII normalization; this endpoint does not perform fuzzy matching, street-address geocoding, point-of-interest search, parcel lookup, or routing.",
      "Unqualified names can be ambiguous. Review country, first-level region, GeoName ID, and coordinates before using a candidate.",
      "Population-based ranking is a selection aid, not proof that the first candidate is the caller's intended place.",
      "Results use the bundled 2026-08-18 snapshot and can differ from newer GeoNames records."
    ]
  },
  "meta": {
    "duration_ms": 42,
    "cached": false,
    "sources": [],
    "warnings": [],
    "next_actions": [
      {
        "service": "data.us-weather-forecast",
        "title": "Global weather forecast",
        "reason": "Use one selected place candidate's coordinates for a separately authorized current global forecast.",
        "method": "POST",
        "path": "/v1/data/us-weather-forecast",
        "price": "$0.003",
        "input_template": {
          "latitude": "$result.data.results[0].coordinates.latitude",
          "longitude": "$result.data.results[0].coordinates.longitude",
          "forecast_type": "day_night",
          "units": "si",
          "periods": 6,
          "include_current_conditions": false,
          "include_active_alerts": false,
          "timezone": "$result.data.results[0].timezone"
        },
        "use_output": "Run only after confirming the intended country and region candidate. The forecast is a separate paid request and current weather-source coverage can vary by coordinates.",
        "handoff_path": "/catalog/data.us-weather-forecast",
        "checkout_path": "/try/data.us-weather-forecast",
        "sample_path": "/samples/data.us-weather-forecast",
        "maximum_atomic_usdc": "3000",
        "handoff_payment_required": false,
        "executes_automatically": false,
        "authorization_required": true
      }
    ]
  }
}
Example request

Input JSON

{
  "place": "London, GB",
  "limit": 5
}
Delivery contract

One paid POST

Resolve one global city or locality name into bounded, population-ranked GeoNames coordinates, country and first-level-region identity, population, timezone, feature code, and source freshness without a request-time network call.

POST /v1/data/place-geocode

Inspect validation rules and output schema

Need current data?

Run this exact service.

The checkout verifies the request, selected network, USDC asset, recipient, and price before opening a wallet.

Continue · $0.002 USDC