# API Acre Place Geocode

> API Acre Place Geocode is a paid API for AI agents from apiacre.com, paid per call via x402, $0.002/call, status unknown (last checked 2026-10-11).

Resolves a global city or locality name into GeoNames-backed coordinates, country, region, population, timezone, and feature metadata without a live network call.

## Facts

- Endpoint: POST https://apiacre.com/v1/data/place-geocode?utm_source=zero.xyz
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-acre-place-geocode-f73fc88a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_aB9vV2XSRqS0JRvHGyq5D

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability api-acre-place-geocode-f73fc88a -d '<json body>'
```

Example prompt: Can you geocode 'London, GB' for me and return up to 5 candidate matches with their coordinates, country info, GeoNames IDs, and population rankings?

## When to prefer this

Choose this endpoint when you need fast, offline-style geocoding of city or locality names without incurring a live geocoding API call latency, and when GeoNames coverage (populated places above 500 population) is sufficient. Prefer it over real-time geocoding APIs when cost, latency, or reliability of external calls is a concern. It is especially useful when you need population-ranked disambiguation of ambiguous city names, structured country/region identity, or timezone data alongside coordinates.

## Known failure modes

- Unrecognized or misspelled place name returns zero results
- Highly ambiguous unqualified names return multiple candidates requiring caller disambiguation
- Place names with fewer than 500 population are not in the cities500 dataset and will not match
- Non-ASCII characters are normalized to ASCII before matching; unusual transliterations may miss
- Snapshot data may lag live GeoNames by days; very new or renamed places may be absent
- Missing required 'place' field returns a validation error

## How this service works

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.

## Output

Returns a JSON object containing: the normalized query, dataset source metadata (GeoNames cities500 snapshot date), and an array of ranked place results each with name, GeoNames ID, coordinates, country code/ISO3/name/continent, matched name type, population rank, and an ambiguity flag. Also includes candidate count, truncation status, and next-action suggestions for follow-on endpoints.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "limit": {
   "type": "integer"
  },
  "place": {
   "type": "string"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": {
   "query": {
    "limit": 5,
    "place": "London, GB",
    "normalized": "london, gb"
   },
   "source": {
    "dataset": "GeoNames cities500",
    "provider": "GeoNames",
    "aliasRecords": 766415,
    "placeRecords": 235408,
    "snapshotBuiltOn": "2026-08-18"
   },
   "results": [
    {
     "name": "London",
     "rank": 1,
     "country": {
      "code": "GB",
      "iso3": "GBR",
      "name": "United Kingdom",
      "continentCode": "EU"
     },
     "geonameId": 2643743,
     "matchedNameType": "primary"
    }
   ],
   "version": "apiacre-place-geocode/1",
   "ambiguous": true,
   "limitations": [
    "Coverage follows the GeoNames cities500 extract: populated places above 500 r...",
    "Matching is exact after Unicode-to-ASCII normalization; this endpoint does no...",
    "Unqualified names can be ambiguous. Review country, first-level region, GeoNa...",
    "Population-based ranking is a selection aid, not proof that the first candida...",
    "Results use the bundled 2026-08-18 snapshot and can differ from newer GeoName..."
   ],
   "candidateCount": 2,
   "resultsTruncated": false,
   "candidateCountCapped": false
  },
  "meta": {
   "cached": false,
   "sources": [],
   "warnings": [],
   "duration_ms": 42,
   "next_actions": [
    {
     "path": "/v1/data/us-weather-forecast",
     "title": "Global weather forecast",
     "method": "POST",
     "reason": "Use one selected place candidate's coordinates for a separately authorized cu...",
     "service": "data.us-weather-forecast"
    }
   ]
  },
  "service": "data.place-geocode",
  "version": "1",
  "request_id": "018f1f54-7f38-7ba2-8dc3-5f90272d9f1a"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-acre-place-geocode-f73fc88a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from apiacre.com](https://www.zero.xyz/host/apiacre.com/llms.txt)