# Geocodio — how to use (mcp.ai)

Connect your Geocodio account and use 7 tools for developer tools straight from your AI agent. Connect with your own API key. Geocodio provides straightforward and easy-to-use geocoding, reverse geocoding, and data matching services for US and Canadian addresses.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_geocodio?ms=1787293560000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `geocodio_batch_reverse_geocode`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/geocodio`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/geocodio/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/geocodio/batch/reverse/geocode` — Tool to batch reverse geocode up to 10,000 coordinates in one request. Use when you need addresses for many lat/lon pairs.
  - body: { limit?: integer, fields?: string, coordinates: string[] }
- `POST https://api.mcp.ai/api/geocodio/delete/list` — Permanently deletes a Geocodio spreadsheet list by its ID. Use this to cancel a processing list job or remove a completed list. This action is destructive and cannot be undone. The list_id must be obt
  - body: { list_id: integer }
- `POST https://api.mcp.ai/api/geocodio/geocode/batch` — Tool to batch geocode up to 10,000 addresses to coordinates in one request. Use when you need to convert multiple addresses to lat/lon coordinates. Optionally calculates distances to specified destina
  - body: { limit?: integer, fields?: string, addresses: string[], destinations?: string[], distance_mode?: string, distance_units?: string, distance_order_by?: string, distance_sort_order?: string, distance_max_results?: integer, distance_max_distance?: number, distance_max_duration?: integer, distance_min_distance?: number, distance_min_duration?: integer }
- `POST https://api.mcp.ai/api/geocodio/geocode/google/maps/compatible` — Tool to geocode addresses using Google Maps-compatible API format. Use when you need a drop-in replacement for Google Maps Geocoding API for US and Canada addresses.
  - body: { key: string, latlng?: string, address?: string }
- `POST https://api.mcp.ai/api/geocodio/get/coordinates/for/batch/reverse/geocode` — Utility tool that returns a predefined list of sample US coordinates (latitude,longitude strings). Use this to obtain ready-to-use coordinate inputs for the batch reverse geocode action. The coordinat
- `POST https://api.mcp.ai/api/geocodio/single/geocode` — Tool to forward geocode a single address. Use when you need coordinates and metadata for one address.
  - body: { q?: string, city?: string, limit?: integer, state?: string, county?: string, fields?: string, format?: string, street?: string, country?: string, street2?: string, postal_code?: string }
- `POST https://api.mcp.ai/api/geocodio/single/reverse/geocode` — Tool to reverse geocode a single coordinate. Use when you need to convert one lat,lng to an address.
  - body: { lat: number, lng: number, limit?: integer, fields?: string, format?: string }

## Example prompts
- "What can I do in Geocodio?"
- "Show me a summary of my Geocodio account"

## More
- Page: https://mcp.ai/geocodio
- Agent spec (llms.txt): https://mcp.ai/geocodio/llms.txt
- Postman collection: https://mcp.ai/geocodio/postman.json