🌍 OpenStreetMap Tool
An AI tool that allows large language models to find points of interest (POIs) on OpenStreetMap near a requested address or place.
The OSM tool can:
- Find points of interest near a location, address, or GPS coordinates.
- Find the address/location of a specific place by name.
- Provide navigation directions to a destination.
- Reason about how long it takes to get from A to B.
Recommended Setup
- Qwen 3 (14b parameters or higher) with native function calling enabled.
- A context window of 8,000 tokens or more.
Supported Models
The tool is routinely tested with the following models at mid-range quantization levels, using llama.cpp:
Mistral Small 3.2 24b (Q4_K_S quant)
Qwen 3 30b-a3b Instruct 2507 (Q3_K_XL quant)
The tool is tested using NATIVE tool calling in OpenWebUI (i.e. model function calling set to native), but OpenWebUI's built-in function calling should also work.
Native tool calling is preferred because is enables the model to handle advanced multi-step tasks (like searching for POIs and displaying them on a map).
Other Models
Despite being older, Qwen 2.5 14b and Mistral Nemo demonstrate the contextual awareness for conversational use of the tool, and can also be used.
Weaker Models
- Llama 3.1 8b generally needs explicit instruction to use the tool properly.
- Models with less parameters may not interpret results correctly.
- Weaker models may benefit from disabling the "Instruction Oriented Interpretation" setting.
- Since 4.0, weaker models should be more accurate.
Finding Points of Interest
The tool can search a location for nearby grocery stores, restaurants and bakeries, recreational areas, educational institutions, transit options, and more. It's best used by asking the AI to find whatever you're looking for near a given address or area.
How it Works
The tool first converts the address or place to GPS coordinates, and then picks the center point of that area, and looks for points of interest in a radius around it.
For example, if you ask it to find grocery stores near "123 Main Street, Example Town", it will first figure out that "123 Main Street" in Example Town is at GPS coordinates X,Y. Then the tool will check a radius around that point for grocery stores.
Search Tips
While the tool is smart enough to find things near specific addresses, regions, or even entire cities, there are some ways to maximize its effectiveness.
- It is best to be as specific as possible when searching.
- Do not specify apartment numbers or sub-units.
When the tool searches, it creates a bounding box. A bounding box is an imaginary box that gives us a small "portion of the map" where the resolved address or place is located. The geographical center of the bounding box is used to find search results.
If you ask the tool to find POIs in an entire city, it will look in a radius from roughly the geographical center of the city. Finding POIs from the geographical center of a city will give limited and probably not very useful results.
Navigation
The tool allows LLMs to query OpenRouteService (ORS) for navigation information. Asking the model how to get to a destination will cause it to return navigation instructions to your destination.
- You must sign up for and enable ORS integration (see below).
- By default, the model doesn't know your location.
- You will have to tell it your starting location.
- For real-time location, see 'Real-Time Location' below.
Navigation: Supported Models
Qwen 3 and Mistral Small support navigation well. These models and their derivatives demonstrate contextual awareness and can understand conversations where the user asks about a destination, and then asks how to get there in a later message.
Enhancing the User Experience
The OSM tool can integrate with OpenWebUI's user location features and third party services to provide an enhanced user experience.
Displaying a Map
If you ask the model to display your results, you will get a nice interactive map that you can use to click on the results and see exactly where they are. This feature requires Open WebUI 0.6.31 or higher, and is exposed as the `show_map` function.
Real-Time Location
In order to have the OSM tool be able to answer questions like "where is the nearest grocery store to me?", it needs access to your real-time location. This can be accomplished with the following steps in OpenWebUI:
- Enable user location in your user settings.
- Create a model with a _system prompt_ that references the variable `{{USER_LOCATION}}`.
- OpenWebUI will automatically substitute the GPS coordinates reported by the browser into the model's system prompt on every message.
OpenRouteService Integration
The tool can use OpenRouteService for navigation and more accurate search results.
By default, the OSM tool calculates "as the crow flies" (Haversine) distances between GPS points to figure out the closest points of interest. But the tool can optionally use OpenRouteService to calculate the actual travel distance between two points in order to provide more accurate results. Just because something is close by geographically, doesn't mean it'll be the same distance to get there!
To use OpenRouteService, you must:
- Sign up for an account at the ORS website.
- Create an API token on the ORS website.
- Put the API key in the ORS API Key setting for the tool.
Configuration
The OSM tool should work out of the box on any low-traffic instance of Open Web UI that uses sufficiently advanced large language models. The only settings you MUST set are the User-Agent and From headers.
Settings
The tool exposes these settings:
- User-Agent: The custom user agent to set for OSM and Overpass Turbo API requests.
- From Header: The email address for the From header for OSM and Overpass API requests.
- Nominatim API URL: URL of the API endpoint for Nominatim, the reverse geocoding (address lookup) service. Defaults to the public instance. This must be the root URL of the service.
- Overpass Turbo API URL: URL of the API endpoint for Overpass Turbo, for searching OpenStreetMap. Defaults to the public endpoint.
- Instruction Oriented Interpretation: Controls the level of detail in the instructions for interpreting results given to the LLM. By default, it gives detailed instructions. Turn this setting off if results are inconsistent, wrong, or missing.
- Status Indicators: If enabled, emit update events to the web UI, showing what the tool is doing and what search results it has found, or if it has encountered an error.
- ORS API Key: Provide an API key for Open Route Service to calculate navigational routes to nearby places, to provide more accurate search results.
- ORS Instance: By default, use the public Open Route Service instance. Can be changed to point to another ORS instance.
- Return Raw OSM Data: Enable to include all raw OSM data in each search result. Disabled by default to save on token use.
- Tile Server: Custom OSM tile server URL for use with the Leaflet library.
Tile Server
The tile server should adhere to the {s}, {z}, {x}, {y} format. The default value is:
https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
Nominatim Terms of Use
The tool WILL NOT RUN without the User-Agent and From headers set. This is because the public instance of the Nominatim API will block you if you do not set these. Use of the public Nominatim instance is governed by their terms of use.
The default API services are suitable for applications with a low volume of traffic (absolute max 1 API call per second). If you are running a production service, you should set up your own Nominatim and Overpass services with caching.
Issues and Feature Requests
Issues and feature requests can be opened in two places:
‗‗‗‗‗‗‗‗‗‗‗‗‗‗‗‗‗‗‗‗