🌍 SPOT: Natural Language Interface to OpenStreetMap

Describe a place, get a map of matching locations.
SPOT is an open-source tool that lets you search the world using natural language. It turns user queries into geospatial searches over OpenStreetMap (OSM) data — with no code or tagging knowledge required.

➡️ Try the Demo
📽️ Watch the Demo Video

---

✨ Key Features

• 🔎 Natural Language → Structured Geospatial Search
• 🧠 Fine-tuned open LLMs (Mistral, LLaMA3) interpret scene descriptions
• 🏷️ Semantic bundling of OSM tags using Elasticsearch
• 🗺️ Interactive map frontend (Next.js + Leaflet)
• 💾 Dockerized architecture with multiple composable modules
• 📚 Open source & published under AGPLv3

---

📝 OSM Tag Bundles – Check & Suggest

SPOT relies on a curated list of OSM tag bundles to interpret user queries correctly. If you notice a query doesn’t work as expected, it might be due to a missing or mismatched tag.

📄 View the tag bundles list (CSV)
💬 Submit a suggestion or correction → Pinned Issue

┈┈┈┈┈┈┈┈┈┈┈

💻 Alternatively, you can use the Interactive Tag Viewer & Editor

---

📦 Architecture Overview

SPOT is composed of several Dockerized modules, managed centrally:

kid2-spot/
├── frontend/                 # Map-based UI
├── apis/
│   ├── osmquery/             # Queries local OSM DB
│   ├── osmtagsearch/         # Maps phrases to OSM tag bundles
│   └── central-nlp-api/      # Orchestrates inference & pipeline
├── data_and_training/
│   ├── datageneration/       # Synthetic data generation
│   └── unsloth-training/     # LLM training pipeline
└── docker-compose.yml        # Orchestrates all services

---

🔧 Configuration

• See ENVIRONMENT.md for service ports and module env variables.
• See SECURITY.md for secrets handling best practices.

---

🚀 Quickstart

To clone and run the full project locally:

git clone --recurse-submodules https://github.com/dw-innovation/kid2-spot.git
cd kid2-spot
docker compose up --build

Note: Make sure Docker has enough memory and disk space. You may need to configure .env files (see submodule READMEs).

---

📚 Publications

• ACL 2025 Demo Paper: aclanthology.org/2025.acl-demo.8
• OSM Science 2023: arXiv

---

🧠 Submodules Overview

Module	Description
frontend	Map UI (Leaflet + Next.js)
central-nlp-api	Converts NL → YAML → OSM tags
osm-tag-search-api	Maps phrases to OSM tag bundles (Elasticsearch)
osm-query-api	Executes spatial query on local OSM DB
datageneration	Synthetic YAML/sentence generator for training
unsloth-training	Training script for open LLMs

Each module has its own README file. You can also run each independently for debugging.

---

🎥 Demo Video

Spot-Demo.mp4

---

🧑‍💻 Contributing

We welcome contributors from all backgrounds – developers, mappers, researchers, journalists!

Ways to help:

• Improve tag bundles or suggest new ones
• Help with frontend or UX design
• Add tests or documentation
• Improve prompts or training data

Please see CONTRIBUTING.md to get started.

---

🔗 Related Docs

• Main SPOT Repo
• Frontend UI
• Central NLP API
• OSM Tag Search API
• OSM Query API
• SPOT Datageneration
• Unsloth Training Script

---

🛡 License

This project is licensed under the GNU AGPLv3.
If you improve SPOT, please share your changes with the community.

© Deutsche Welle Research & Cooperation Projects · AGPLv3 License