# TBS Geocoding API – Forward Geocoding

> TBS Geocoding API – Forward Geocoding is a paid API for AI agents from x402.tbs-digital.com, paid per call via x402, $0.001/call, status unknown (last checked 2026-10-09).

Converts a place name or address string into latitude, longitude, country, administrative regions, timezone, and GeoNames feature code

## Facts

- Endpoint: GET https://x402.tbs-digital.com/geo/forward?utm_source=zero.xyz
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/tbs-geocoding-api-forward-geocoding-9c5969c1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_M_Ct94RSlTldm3BL3tnWh

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 tbs-geocoding-api-forward-geocoding-9c5969c1
```

Example prompt: What are the latitude and longitude coordinates for Lyon, France, and what timezone is it in?

## When to prefer this

Choose this endpoint when you need a fast, keyless, stablecoin-payable forward geocoding call that returns a unified schema including timezone and admin regions — especially useful for AI agent pipelines needing structured location enrichment without managing API keys or complex billing. Prefer it over raw Open-Meteo geocoding when you want a normalized response with x402 micropayment support.

## Known failure modes

- Ambiguous place name returns best-guess match that may not be the intended location
- Very obscure or misspelled place names may return no result or a wrong match
- No result returned for purely postal-code-only queries if not supported
- Network or upstream Open-Meteo service unavailability causes error response
- Missing q or address parameter results in a bad request error

## How this service works

Forward geocoding for AI agents: turn a place name or address into coordinates. Returns the best-match latitude, longitude, country and ISO country code, administrative regions (admin1/admin2), population, IANA timezone and GeoNames feature code. Query by q= or address=. Sourced from Open-Meteo geocoding — keyless, unified schema, stablecoin-payable.

## Output

Returns a best-match location object including latitude, longitude, country name, ISO country code, admin1 and admin2 administrative regions, population estimate, IANA timezone identifier, and GeoNames feature code, along with request metadata such as source, request_id, and generated_at timestamp.

## 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",
     "properties": {
      "q": {
       "type": "string",
       "description": "Place name / address to geocode, e.g. Paris"
      },
      "address": {
       "type": "string",
       "description": "Alias for q"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "payer": {
       "type": "object",
       "properties": {
        "address": {
         "type": "string",
         "nullable": true
        },
        "network": {
         "type": "string"
        }
       }
      },
      "source": {
       "type": "string"
      },
      "location": {
       "type": "object",
       "nullable": true
      },
      "request_id": {
       "type": "string"
      },
      "generated_at": {
       "type": "string"
      }
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/tbs-geocoding-api-forward-geocoding-9c5969c1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402.tbs-digital.com](https://www.zero.xyz/host/x402.tbs-digital.com/llms.txt)