How to Use the LocationIQ (Geocoding & Maps) MCP in Pydantic AI

Q: How do I initialize LocationIQ (Geocoding & Maps) in Pydantic AI?

Use the MCPToolset constructor with your Vinkius HTTP endpoint. Pass this toolset into the toolsets list of your Agent to register all ten spatial tools over MCP.

Q: How do I check my remaining API limits in my Python application?

Invoke checkaccountbalance to get the exact number of remaining OpenStreetMap queries on your token. The response is returned as a typed object, making it easy to build automated alerts when credits run low.

Build type-safe spatial applications in Pydantic AI with strict validation using this MCP server.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect LocationIQ (Geocoding & Maps) MCP to Pydantic AI

Create your Vinkius account to connect LocationIQ (Geocoding & Maps) to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup LocationIQ (Geocoding & Maps) with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-Safe Geocoding and Search via MCP Server

The `search_geocode` tool converts messy address strings into validated latitude and longitude coordinate models. Because Pydantic AI enforces strict runtime validation, any malformed response from the mapping API triggers a validation error instantly. You can restrict your search areas using `search_bounding_box` to define explicit geographic coordinate limits in your Pydantic AI agent. This ensures your agent never processes coordinates outside your application's physical boundaries.

Validated Route and Distance Matrices

The `calculate_distance_matrix` tool outputs a structured table of travel durations across multiple coordinates. This MCP server maps the API response directly to Pydantic models, preventing silent data corruption in your logistics pipeline. For point-to-point navigation, `calculate_directions` returns precise driving, walking, or cycling geometry. If the API returns unexpected route structures, your Pydantic AI code catches the validation error before execution proceeds.

Road Snapping and Address Parsing

The `snap_nearest_roads` tool snaps raw GPS coordinates directly to the closest physical street network. This output is immediately parsed into a typed schema, ensuring your Pydantic AI agent works with clean, road-aligned coordinates. To translate coordinates to text, `reverse_geocode` provides structured postal addresses. You can use `reverse_language_bias` to enforce specific language translations, validating the localized strings against your Pydantic AI application's schema.

Setup guide

Set up LocationIQ (Geocoding & Maps) MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "locationiq-geocoding-maps-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to LocationIQ (Geocoding & Maps) tools.",
)

result = await agent.run("List recent LocationIQ (Geocoding & Maps) transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by LocationIQ. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect LocationIQ (Geocoding & Maps) now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about LocationIQ (Geocoding & Maps) MCP in Pydantic AI

Use the `MCPToolset` constructor with your Vinkius HTTP endpoint. Pass this toolset into the `toolsets` list of your `Agent` to register all ten spatial tools over MCP.

Pydantic AI validates the JSON response against strict Python type hints at runtime. If the API returns an unexpected coordinate format, the framework raises a validation error instead of passing bad data to your agent.

Yes, Pydantic AI is model-agnostic, meaning you can use these mapping tools with local models or commercial LLMs. The MCP toolset translates the schemas into the format required by your chosen model automatically.

Invoke `check_account_balance` to get the exact number of remaining OpenStreetMap queries on your token. The response is returned as a typed object, making it easy to build automated alerts when credits run low.

Your geocoordinates and address queries are handled in an isolated, zero-trust V8 sandbox. This ephemeral execution environment ensures that no location data or tenant keys are logged or stored on disk.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript