# Agent Time & Place – Geocode

> Agent Time & Place – Geocode is a paid API for AI agents from time-place.agent-utils.workers.dev, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-15).

Converts a city name (in any spelling or language) into structured geographic data including coordinates, timezone, region, and population.

## Facts

- Endpoint: GET https://time-place.agent-utils.workers.dev/v1/geocode
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent-time-place-geocode-3f900913
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_MMANeYhjl2O1_icLHU-CN

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 agent-time-place-geocode-3f900913
```

Example prompt: What are the coordinates and timezone for Munich, Germany?

## When to prefer this

Use this endpoint when you need to resolve a human-readable city name (in any language or spelling) to structured geographic data including coordinates, IANA timezone, country, and administrative region. It is ideal for AI agents that need to chain geocoding into downstream operations (timezone lookups, distance calculations, holiday checks, sun times) within the same Agent Time & Place service suite. Prefer it over general-purpose geocoding APIs when sub-cent deterministic pricing and no API-key authentication (x402 payment-as-auth) are required.

## Known failure modes

- City name not found: returns empty results array with count 0
- Ambiguous city name without country filter: returns multiple results requiring disambiguation
- Invalid country filter (non-ISO code): may return no results or an error
- Payment not attached or invalid x402 payment: request rejected with 402 status
- Rate or quota issues on the underlying worker

## How this service works

Geocoding, timezones, holidays, business days, sun times, FX and distances for AI agents. Deterministic, sub-cent, no API key: payment is authentication (x402).

## Output

Returns a JSON object with a count of matches, the original query string, and an array of result objects each containing: latitude, longitude, native name, ASCII name, first-level administrative region (state/province), whether it is a capital, ISO 3166-1 alpha-2 country code, IANA timezone identifier, population, and full country name.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "q"
     ],
     "properties": {
      "q": {
       "type": "string",
       "description": "City name, native or English spelling (e.g. 'München' or 'Munich')"
      },
      "limit": {
       "type": "integer",
       "default": 5,
       "maximum": 25,
       "minimum": 1
      },
      "country": {
       "type": "string",
       "description": "Optional ISO 3166-1 alpha-2 filter, e.g. 'DE'"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "count": {
       "type": "integer"
      },
      "query": {
       "type": "string"
      },
      "results": {
       "type": "array",
       "items": {
        "type": "object",
        "properties": {
         "lat": {
          "type": "number"
         },
         "lon": {
          "type": "number"
         },
         "name": {
          "type": "string"
         },
         "ascii": {
          "type": "string"
         },
         "admin1": {
          "type": "string",
          "description": "First-level region (state/province)"
         },
         "capital": {
          "type": "boolean"
         },
         "country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2"
         },
         "timezone": {
          "type": "string",
          "description": "IANA timezone id"
         },
         "population": {
          "type": "integer"
         },
         "countryName": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "count": 1,
  "query": "Munich",
  "results": [
   {
    "lat": 48.1374,
    "lon": 11.5755,
    "name": "München",
    "ascii": "Munich",
    "admin1": "Bavaria",
    "capital": false,
    "country": "DE",
    "timezone": "Europe/Berlin",
    "population": 1260391,
    "countryName": "Germany"
   }
  ]
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent-time-place-geocode-3f900913/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from time-place.agent-utils.workers.dev](https://www.zero.xyz/host/time-place.agent-utils.workers.dev/llms.txt)