# Geocoding as a tool for AI agents

> LLM apps and AI agents need to turn place names into coordinates and back without inventing them. geolith gives an agent one HTTPS GET per lookup with a GeoJSON answer it can quote: /v1/search for names, /v1/reverse for coordinates, /v1/place for a stored gid. Everything an agent needs to call the API is in https://geolith.app/llms.txt, and results may be stored permanently.

## What is a geocoding tool for an AI agent?

A geocoding tool for an AI agent is a function the model can call to turn a place name into coordinates, or coordinates into an address, instead of guessing them from memory. geolith provides it as one HTTPS GET per lookup, plus WebMCP tools on geolith.app and Agent Skills at /.well-known/agent-skills/index.json.

## Define the tool

A geocoding tool for an agent is a thin wrapper around /v1/search. Return only the fields the model needs (label, lat, lon, gid) so the answer stays short.

Tool definition (JSON Schema, any agent framework):

```json
{
  "name": "geocode",
  "description": "Find coordinates for a place name or address. Returns up to 5 matches with label, lat, lon and gid.",
  "input_schema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Place name or address" },
      "country": { "type": "string", "description": "Optional ISO 3166-1 alpha-2 code, e.g. IN" }
    },
    "required": ["text"]
  }
}
```

## Implement it

Call the API from your server with a secret key and map the features to a compact list.

TypeScript:

```ts
export async function geocode(input: { text: string; country?: string }) {
  const url = new URL('https://api.geolith.app/v1/search');
  url.searchParams.set('text', input.text);
  url.searchParams.set('size', '5');
  if (input.country) url.searchParams.set('boundary.country', input.country);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.GEOLITH_API_KEY}` },
  });
  if (!res.ok) return { error: `geolith ${res.status}` };
  const { features } = await res.json();
  return features.map((f: any) => ({
    label: f.properties.label,
    lat: f.geometry.coordinates[1],
    lon: f.geometry.coordinates[0],
    gid: f.properties.gid,
  }));
}
```

## Why agents should not guess coordinates

Language models recall famous coordinates well and everything else badly. A tool call costs one request and returns a real place with a stable id. The agent can show the attribution string and the user can check the result on a map.

## Questions

### Where can an AI assistant read how to call geolith?

https://geolith.app/llms.txt has the base URL, authentication, every endpoint with its parameters, example requests and responses, the attribution rule, pricing and the signup link. https://geolith.app/llms-full.txt adds every page and guide.

### Can an agent store the results?

Yes. Results may be stored permanently on every plan.

## Guides

- https://geolith.app/guides/reverse-geocoding-javascript
- https://geolith.app/guides/geocode-a-csv

Get a free API key (100,000 requests a month): https://console.geolith.app/signup