Google Maps Bridge API

A FastAPI-based bridge service that integrates Google Maps functionality with local LLM systems (like Open WebUI). This project provides location search and route navigation capabilities by generating dynamic Google Maps URLs without requiring GCP credentials.

Overview

This project consists of two main components:

1. Backend API (main.py) - A FastAPI server that generates Google Maps URLs
2. LLM Tool Integration (tools.py) - A tool wrapper for integration with Open WebUI and other local LLM platforms

Features

• Location Search - Generate Google Maps links for any destination
• Route Navigation - Get driving directions to any destination
• CORS Enabled - Works seamlessly with Docker-based Open WebUI instances
• Error Handling - Graceful error handling for connection and server issues
• Async Support - Built with async/await for optimal performance

Project Structure

heypico-test/
├── main.py          # FastAPI server implementation
├── tools.py         # LLM tool integration for Open WebUI
├── note.txt         # Project notes and clarifications
└── README.md        # This file

How It Works

Integration Example

Architecture

The system works around GCP's technical limitations by using dynamic URL mapping:

1. Instead of using the official GCP Maps API Key, the backend constructs direct Google Maps URLs
2. Supports two contexts:
   • location - Shows the destination on Google Maps
   • direction - Shows the driving route to the destination
3. The tool automatically determines which context to use based on user intent

API Endpoints

GET /map

Generate a Google Maps link.

Parameters:

• destination (string, required) - The place or city name
• context (string, required) - Either "location" or "direction"

Response:

{
  "status": "success",
  "query": "Paris",
  "link": "https://www.google.com/maps/search/?api=1&query=Paris"
}

Setup & Usage

Requirements

• Python 3.7+
• FastAPI
• Uvicorn

Installation

pip install fastapi uvicorn requests

Running the Server

python main.py

The API will be available at http://0.0.0.0:8000

Using with Open WebUI

1. Deploy the backend service accessible from your Docker network (port 8000)
2. Configure Open WebUI to use the tool from tools.py
3. The tool will automatically call the backend and return Google Maps links

Configuration

• Host: 0.0.0.0 (accessible from any network interface)
• Port: 8000
• CORS: Enabled for all origins, methods, and headers
• Request Timeout: 10 seconds (prevents prolonged waits on connection failures)

Design Decision

This project was originally planned to use the official GCP Maps SDK. However, due to recurring technical issues with payment method verification on the Google Cloud Platform side, direct API integration was not feasible. The current solution provides full functionality through dynamic URL construction, ensuring 100% reliability without external API credentials.

Error Handling

• Connection Errors - Returns HTTP 503 with connection problem details
• Server Errors - Returns HTTP 500 for unexpected exceptions
• Tool Integration - Gracefully handles backend failures with descriptive error messages

Model & System Prompt

Recommended Model: DeepSeek-R1 8B

System Prompt Guidance: When using this tool with an LLM, instruct the model to display the tool output directly without additional summarization or commentary. This ensures the Google Maps links are presented clearly to the user.