About OSM Notes Viewer

What is this?

OSM Notes Viewer is an interactive web application that visualizes analytics and statistics about OpenStreetMap notes activity around the world.

It surfaces per-user contributions, country-level stats, hashtag trends, and time patterns: when notes are opened and when they are closed.

Manifesto: Our Perspective on OSM Notes

The Importance of Notes in OpenStreetMap

OpenStreetMap Notes are a fundamental mechanism for community collaboration and quality improvement. They serve as a bridge between mappers and the real world, allowing anyone to report issues, suggest improvements, or request new features directly on the map.

Notes represent the collective effort of thousands of contributors working together to improve the map's accuracy and completeness. Each note tells a story—a missing road, an incorrect name, a new business, or a mapping error that needs correction.

Notes keep the map current. People who do not edit OSM can still flag mismatches between the street and the map; mappers use those flags to fix and complete data. That ongoing exchange helps the map track the real world a little better over time.

Our Mission

Our mission is to make OSM Notes more accessible, understandable, and actionable. We believe that by providing better tools and insights, we can:

  • Help mappers identify and resolve notes more efficiently
  • Encourage new contributors to engage with the notes system
  • Provide transparency into the notes ecosystem and community activity
  • Support research and analysis of mapping patterns and trends
  • Foster collaboration within the OpenStreetMap community

The Latin American Community

There is a dedicated community in Latin America focused on resolving OSM Notes. This community works tirelessly to improve the map quality across the region, addressing notes related to:

  • Missing or incorrect road networks
  • Place names and administrative boundaries
  • Points of interest (POIs) and businesses
  • Geographic features and natural landmarks
  • Data quality improvements

This viewer is part of that effort: it offers tools and context for people who map and resolve notes across the region.

Project History

In 2020, during the pandemic, Andrés Gómez began reviewing OSM notes in Colombia: there were many open notes and little clear guidance on how to work through them.

In 2021 he started inviting others. The scope began in Bogotá; with a push from risturiz it grew to all of Colombia, and later to wider Latin America–scale note-resolution efforts.

risturiz coined the term “notathon”: a meetup to resolve notes together. Notathons have since taken place in several countries, and resolvers coordinate in a Telegram channel for mutual support.

That community energy helped strengthen mapping in the region and even brought back State of the Map Latam events.

At the same time, weak tooling led people to ask many apps to improve the note workflow (for example, exposing app name and version, or adding dedicated behaviour, as in fediphoto or the DAMN project). Even so, options for resolvers remained thin: show where a note is (e.g. notesViewer) or open/closed counts (e.g. HDYC), but little aggregate analysis beyond isolated tools such as a heatmap app.

Notes shipped with the OSM 0.6 API and offer few operations. Listing one user’s notes is awkward; a country-wide picture with real analysis still relies heavily on sites such as Pascal Neis’s resultMaps, with their own limits.

There was also a wish to highlight people who resolve many notes in Latin America, which is how the Planet dump came in. A “profile” of note work, in the spirit of what HDYC does for map changes, slowly took shape, along with interest in API queries and up-to-date data.

The design that emerged was to download history and keep it in sync. The first piece, in Bash, already fetched that history. José Luis Cerón brought architectural judgement and recommended staying in Bash given how far the project had come.

Work continued, but ingesting Planet XML was a bottleneck: several tools could not keep up. Years later, José Luis introduced Cursor and modern development; practice projects such as GeoGame run in parallel and will be picked up again once this viewer is on solid ground.

With help from large language models and a lot of prompt iteration, the path was to lean less on heavy XML parsers and more on AWK, which is well suited to large, line-oriented text. That made it possible to process the full note dataset and get the project moving again in late 2025.

AI assistance helped harden the code, fix many bugs, and add unit and integration tests, GitHub Actions, better SQL, and a clear split between ingestion, analytics, common code (commons), and—later—this visualization repo. Other pieces spun out too: WMS, a data repository (including as context for AI tools), an API with capabilities beyond the OSM API (including ML), and a monitoring project to see how the stack fits together.

In 2025 AI sped the work up and forced a lesson in its limits: without solid context, it hallucinates. The repositories therefore emphasise documentation so that any future work—human or assisted—has something reliable to build on.

What We've Built

This project is part of a comprehensive ecosystem consisting of 8 repositories and 2 databases working together to process, analyze, and visualize OSM Notes. The ecosystem includes data ingestion pipelines, analytics systems, REST APIs, web map services, monitoring tools, and visualization interfaces. All components are open source and available for the community to use, modify, and extend.

You will find each component described in the Ecosystem architecture section below.

Ecosystem Architecture

This viewer is part of a comprehensive ecosystem of 8 repositories and 2 databases working together to process, analyze, and visualize OSM Notes:

Repositories

  1. OSM-Notes-Ingestion: Downloads and maintains OSM notes data from Planet dumps and the API. Handles incremental updates and synchronization.
  2. OSM-Notes-Common: Shared libraries and utilities used across all projects, including validation helpers, error handling, and common Bash scripts.
  3. OSM-Notes-Analytics: Data warehouse and ETL that processes ingested data and produces statistics, datamarts, and JSON/CSV exports, plus ML-based suggestions for note actions (close, comment, map).
  4. OSM-Notes-Viewer: This web app: it presents the analytics data with user and country pages and interactive charts.
  5. OSM-Notes-Data: Publishes pre-generated JSON via GitHub Pages or a CDN: profiles, country stats, and indexes.
  6. OSM-Notes-API: REST API for live access: single-note details, hashtag stats, ML recommendations, and search.
  7. OSM-Notes-Monitoring: Monitoring stack: Grafana dashboards, Prometheus metrics, and health checks for the whole ecosystem.
  8. OSM-Notes-WMS: GeoServer and WMS (Web Map Service) configuration: workspaces, layers, and styles for map services.

Databases

  1. PostgreSQL (ingestion database): Raw notes from Planet and the API. Tables such as notes, note comments, users, and countries. Used by OSM-Notes-Ingestion for storage and incremental updates.
  2. PostgreSQL (analytics warehouse): Star-schema warehouse with fact and dimension tables for ETL and stats. Feeds user and country datamarts and time-based analysis. Used by OSM-Notes-Analytics.

Services

  • GeoServer (WMS): Map layers for the UI, configured from OSM-Notes-WMS. Includes open notes, closed notes, and country boundaries.
  • ML recommendations: Implemented in OSM-Notes-Analytics; suggests actions on notes (close, comment, map) and is exposed through the API.

Data Flow

Data flows through the ecosystem as follows:

  1. OSM Planet / API → Raw notes data
  2. OSM-Notes-Ingestion → Download and store in PostgreSQL (ingestion DB)
  3. OSM-Notes-Analytics → ETL into the analytics warehouse
  4. OSM-Notes-Analytics → Export JSON to the OSM-Notes-Data repository
  5. OSM-Notes-Data → Serve static JSON over a CDN
  6. OSM-Notes-Viewer → Load and display the data
  7. OSM-Notes-API → Dynamic REST access
  8. OSM-Notes-WMS (GeoServer) → WMS layers for maps
  9. OSM-Notes-Analytics (ML) → Recommendations via the API
  10. OSM-Notes-Monitoring → System health and performance

The analytics backend extracts notes data, transforms and aggregates statistics, and generates pre-calculated JSON files every 15 minutes.

Data Origins

All data displayed in this viewer originates from OpenStreetMap (OSM), including both cartographic data and notes data. The cartographic information is used for geographic visualization and mapping, while the notes data provides the statistics and analytics shown throughout the application.

To improve the accuracy of maritime zones representation, data from Marine Regions was used as a reference. This allowed us to enhance the maritime boundaries and zones when attempting to replicate the information from that portal using OSM data, ensuring better alignment with recognized maritime boundaries and Exclusive Economic Zones (EEZs).

Licenses: OpenStreetMap data is licensed under the Open Database License (ODbL). Marine Regions data is licensed under CC-BY 4.0.

Features

  • 🔍 Search users and countries
  • 📊 Interactive statistics and charts
  • 📈 Activity heatmaps (GitHub-style)
  • 🌍 Geographic distribution analysis
  • #️⃣ Hashtag usage tracking
  • ⏰ Working hours visualization
  • 📱 Responsive design for all devices

Technology

This is a fully static web application built with vanilla HTML, CSS, and JavaScript. It requires no backend server and fetches all data from pre-generated JSON files.

Stack:

  • HTML5 & CSS3
  • Vanilla JavaScript (ES6 modules)
  • Chart.js for visualizations
  • Deployed on CDN for global access

Open Source

All 8 repositories in the OSM Notes ecosystem are open source and available on GitHub under the OSM-Notes organization. We believe in transparency, collaboration, and community-driven development.

The entire codebase is freely available for anyone to use, study, modify, and distribute. This open approach allows the community to contribute improvements, report issues, and adapt the tools to their specific needs.

Each repository’s role and how they connect is covered under Ecosystem architecture above.

Contact

For questions, suggestions, or collaboration opportunities:

Monitoring & Status

Check system health, performance, and data processing status here:

📊 View Monitoring Dashboard (Grafana)

The dashboard provides real-time metrics on data processing, API performance, database status, and system health. Powered by Grafana and Prometheus.

Contributing

Contributions are welcome. You can:

  • Report bugs or request features via GitHub Issues
  • Submit pull requests with improvements
  • Share feedback and suggestions
  • Help resolve OSM Notes in your region
  • Contribute translations for your language

Acknowledgments

Special thanks to the OpenStreetMap community and all contributors who make notes data available.