Skip to content

OSM.md

Latest commit

 

History

History
162 lines (118 loc) · 7.66 KB

OSM.md

File metadata and controls

162 lines (118 loc) · 7.66 KB

🌍 OpenStreetMap Tool

The OpenStreetMap tool helps you find points of interest, get directions, and explore locations right from your chat interface. Whether you're looking for the nearest coffee shop, trying to navigate to a new address, or just curious about what's around you, this tool makes it easy to get the information you need from OpenStreetMap.

Full Documentation (Gemini): gemini://agnos.is/projects/open-webui-filters/osm-tool

Full Documentation (HTTP/Web): https://agnos.is/projects/open-webui-filters/osm-tool/

Changelog: located at https://git.agnos.is/

License: AGPLv3 or later

📌 Key Features

  • 📍 Find Points of Interest (POIs) near locations, addresses, or GPS coordinates (e.g., bakeries, hospitals, schools, etc.)
  • 🧭 Reverse geocoding to resolve coordinates into human-readable addresses
  • 🗺️ Navigation routes via OpenRouteService (ORS) for walking, cycling, or driving directions
  • ⏱️ Travel time estimation between locations using ORS distance calculations
  • 🏙️ Urban awareness for accurate search radiuses.
  • 💾 Caching to reduce load on the public services and comply with OSM policies.
  • 🔄 Context-aware conversations (e.g., "Find a café near me" → "How do I get there?")

📱 Supported Models

Recommended: Qwen 3 (14b+ parameters) with native function calling enabled for best performance.

✅ Regularly Tested Models (Mid-Range Quantization)

The tool is regularly tested with these models at quants ranging from Q3_K_XL to Q5_K_M, using llama.cpp.

No testing is currently done with ollama.

⚠️ Notes for Model Selection

  • Native function calling allows the tool to work better (multiple function calls etc). Open WebUI's built-in function calling also works, but is limited to one function call per message.
  • Context Window: Ensure models have sufficient context window size (a minimum of 8k is recommended).
  • Qwen 2.5 14b and Mistral Nemo are older models that aren't officially recommended, but should work fine for most use cases.
  • Llama 3.1 8b is not recommended. It may work with very explicit prompts.
  • Weaker models may need the "Instruction Oriented Interpretation" setting disabled for consistent results.

🧩 How It Works

  1. Address Resolution

    • Converts input (e.g., "123 Main St, Example City, USA") to GPS coordinates using Nominatim.
    • Requires valid User-Agent and From Header to avoid being blocked by Nominatim.

  2. Define Search Area

    • Creates a geographic "box" around the resolved address to define the search area.
    • Uses the center point of the either the bounding box, or the OSM-defined center point of a town/city.

  3. POI Search

    • Queries OpenStreetMap via Overpass Turbo API for points of interest within a radius of the center point.
    • Supports categories like:
      • 🛒 Groceries, restaurants, bakeries
      • 🏫 Schools, universities
      • 🚶‍♂️ Recreation (parks, playgrounds, sports facilities)
      • 🚇 Public transport (bus stops, train stations)
      • 🏥 Hospitals, clinics, doctors

  4. Navigation

    • Uses OpenRouteService (ORS) to calculate routes (requires API key).
    • Supports:
      • 🚶 Walking directions
      • 🚲 Cycling routes
      • 🚗 Driving navigation

🛠️ Configuration Requirements

⚠️ Mandatory Settings

  • User-Agent: A custom identifier for API requests (e.g., "OSM-Tool/1.0 (https://example.com)")
  • From Header: A valid email address (e.g., "user@example.com") for API compliance

📡 API Endpoints

  • Nominatim API URL: Default: https://nominatim.openstreetmap.org
    • Used for reverse geocoding (coordinates → address) and address resolution.
  • Overpass Turbo API URL: Default: https://overpass-turbo.eu
    • Used for querying OpenStreetMap for POIs.

🔄 Advanced Options

  • Instruction Oriented Interpretation:
    • Enabled: Provides detailed parsing instructions to the model (recommended).
    • Disabled: Simplifies output for weaker models.
  • Status Indicators: Shows real-time tool activity in the UI.
  • ORS API Key: Required for navigation and acccurate distance calculations.
  • ORS Instance:
    • Default: Public ORS instance (https://api.openrouteservice.org).
    • Can be changed to a custom ORS instance if self-hosted.

📌 Usage Tips

📍 Best Practices

  • Avoid city-wide searches - be specific when searching for locations.
  • Avoid sub-unit details (e.g., apartment numbers, floor levels).

🗺️ Navigation Setup

Enabling OpenRouteService allows the tool to provide navigation instructions and more accurate distance calculations.

  1. Sign up for OpenRouteService.
  2. Generate an API token in your ORS account.
  3. Input the API key in the ORS API Key setting of the tool.
  4. Enable ORS integration in the tool configuration.

📍 Real-Time Location Support

To enable location-based queries (e.g., "Find the nearest coffee shop"):

  1. Enable user location in OpenWebUI settings (under "User Preferences" or "Privacy").
  2. Configure a model with {{USER_LOCATION}} in its system prompt (e.g. "The user's current location is {{USER_LOCATION}}.").
  3. OpenWebUI will automatically inject real-time GPS coordinates into the system prompt for every message.

📜 Nominatim Compliance

The tool will not function without valid User-Agent and From Header settings. View Nominatim Terms of Use

Rate Limiting: The public Nominatim API server allows 1 request per second. For production use, consider self-hosting Nominatim with caching.

🛠️ Troubleshooting

🔧 Common Issues

  • No Results Found:
    • Verify the input address is valid and includes city/country.
    • Check the resolved location on OpenStreetMap by clicking on the search result.
    • Verify search radius (urban/suburban/rural) is correct. Explicitly tell the model to use the correct one if necessary.
  • Model Misbehavior:
    • Use a stronger model.
    • Disable Instruction Oriented Interpretation for weaker models.
    • Explicitly specify which tool function for the model to use (e.g. "Use the find eateries tool").

Recent Updates

New in 3.2.x:

  • Greatly improved source citations and status events, making use of new features in Open WebUI 0.6.30+.
  • Change detailed mode instructions to a structured set of data.
  • Better handling of generic city-wide queries (e.g. "What restaurants are in NYC?") by centering on OSM-defined lat/lon.
  • Report resolved location name in tool results.
  • Do not return public bookcases when searching for bars.

New in 3.1.x:

  • Drastically reduce number of functions to save on context window size.
  • Provide a specific function to guide LLMs in converting GPS coordinates to human-readable place names.

New in 3.0.0:

  • Urban awareness for urban, suburan, and rural areas.
  • New POI categories: gas stations and EV fast chargers.
  • Return replies from functions as JSON instead of markdown.
⚡