overpass-turbo is a query console for OpenStreetMap data

A GUI for the Overpass API, and what that is for

overpass turbo is a web based data mining tool for OpenStreetMap using the Overpass API, and the readme describes it as a GUI for testing and developing queries for the Overpass API, with the note that it can also be used for simple analysis of OSM data.

The framing matters, because Overpass has a reputation for being powerful and unpleasant. The query language is a small domain specific language, and the feedback loop for writing one is normally: write a query, send it to an API endpoint, wait, get JSON back, and stare at it. overpass turbo replaces the last three steps with a map, a preview and a history, and the readme notes the documentation of the tool lives in the OSM wiki rather than in the repository.

Two deployments are described at the top of the readme. The stable version is at overpass-turbo.eu, and the latest version is at tyrasd.github.io/overpass-turbo, which is the development build. The stable site is the one people use, and the GitHub Pages site is the one you check when you want to know what is about to change.

The audience is two groups. The first is the OpenStreetMap contributor or power user who needs to find the query that answers a question about the map. The second is the developer who wants to hand somebody a link that opens a specific query on a specific location, and for that the readme points to the URL parameter documentation on the OSM wiki.

The project is maintained by Tyrone Asdz, and the licence in the package metadata is MIT, although the repository metadata for the project reports the licence as a custom one that GitHub cannot classify, so the LICENSE file is the one to read.

Two geocoders, and a policy reason for the second one

The geocoding section is short and explains itself, and it is a good example of a small design decision driven by someone else's rules.

Two geocoders are used, both behind the common interface in js/geocoding.ts. Nominatim resolves the {{geocodeId}}, {{geocodeArea}}, {{geocodeBbox}} and {{geocodeCoords}} shortcuts, which are the place name shortcuts you can drop into a query to have it expanded into coordinates, an area or a bounding box. And osmnames backs the autocompletion of the map search box, because the Nominatim usage policy forbids autocomplete style querying.

So the split is not a preference. Nominatim is a volunteer run service with a fair use policy, and a search box that fires a request on every keystroke is precisely the pattern that policy exists to prevent. The solution is to put the autocomplete on a different service that is built for it, and to keep Nominatim for the queries where it is appropriate.

That is worth noting for anyone who wants to run their own instance or point turbo at a different Overpass endpoint, because the geocoder split is part of the contract with the upstream services rather than an implementation detail. It also explains the presence of the osmnames dependency in a tool that otherwise talks to one API.

The other thing this section reveals is the shape of the code. There is a single interface in one file, with two implementations behind it, which is the smallest arrangement that keeps the policy constraint in one place.

URL parameters turn the tool into a link

The development section documents URL parameters, and the readme explains the value in one sentence: overpass turbo can be linked from other applications by using URL parameters. You can provide a query to load, set the initial map location, or instruct turbo to load a template.

That third one is the interesting feature, because templates are a first class part of the tool. A template is a saved query with parameters, and if turbo can be told to load one from a URL, then a documentation site, a wiki page or a bug report can contain a link that opens the right query, on the right map, with the right template, and the reader does not have to have Overpass installed or know the query language.

The template mechanism is also why the project carries a peggy dependency, since a template is a piece of text with a small expression language embedded in it, and a parser generator is how you would build that.

For a self hosted deployment, the practical value of the URL parameters is that they make turbo usable as a front end for an internal tool. A service that generates OSM queries can hand the user a turbo link rather than reimplementing a map and a query preview, and the link works in a browser with nothing installed.

The readme points to the OSM wiki page on Overpass turbo development for the details of the parameter set, which is the reference to read before you build links into anything.

Running the development server, and the toolchain behind it

The install and run instructions are four steps, and they assume pnpm.

First install pnpm, for example via npm install -g pnpm, then run pnpm install, then pnpm dev for a development server listening at http://localhost:5173, then pnpm build for a minified build in./dist, and pnpm preview to serve the production build locally.

The commands are short because the toolchain underneath is doing the work. Nearly every script in the package metadata is a call to vp, the vite-plus command, and vite-plus is pulled from a shared catalogue rather than pinned to a version here, the same way vite is. The test script is the exception, running tsc and then vp test, so the type check is part of the test run rather than a separate step.

pnpm install
pnpm dev

For checks, the readme lists pnpm test for the Vitest suite, pnpm check for the format, lint and type checks as done in CI, pnpm format to format the code in place and pnpm lint to lint it. Formatting is applied automatically to staged files by the pre-commit hook, and there is one setup step, running pnpm exec vp config once after cloning to install it.

The dependency list shows what the tool is built from. Leaflet 1.9.4 is the map, jQuery 4 and jQuery UI are the interaction layer, CodeMirror 5.65 is the query editor, Bulma 1.0 is the styling, and the data handling is osmtogeojson for turning the result into something drawable, tokml and togpx for the export formats, tag2link and html2canvas for the export and sharing features, osm-auth for the OpenStreetMap authentication, and the id-tagging-schema package for the editing form that lets you change a tag on the map. On the development side there is peggy for the template parser, happy-dom as the DOM for the tests, and TypeScript 7.

The dependency on a git reference rather than a release, for the togpx package, is a small thing that a security scanner will ask about and a maintainer will know about.

Three branches, and how a release becomes a static site

The git branches section is short and explains the release model.

Development is done in the master branch, stable releases are marked with git tags, and the gh-pages branch contains static builds of the releases.

That is why the readme lists two URLs at the top, the stable one at overpass-turbo.eu and the latest version on GitHub Pages. The Pages branch is the deployment target for a tagged release, and the Pages site under the repository is where the development build is visible. Anyone who wants to see what the next release will look like can look at the second URL, and anyone who wants a stable tool uses the first.

The Makefile is a small asset pipeline rather than a build system, and its two targets reflect that. The icons target pulls three icon sets, maki, mapnik and osmic, and each has its own recipe. The maki and mapnik recipes download a zip and unzip the PNGs into the icons directory. The osmic recipe clones the repository, runs its export script with a config file for overpass turbo, optimises the PNGs with optipng and copies the result into place.

The changelog is generated rather than written. The changelog script runs git-cliff with the cliff.toml configuration, which means the release notes come from the commit history, and there is a TODO.md at the root for the things that are not done yet.

Translations are handled through Transifex, with a .tx directory in the repository for the configuration, a locales directory for the translated strings, and the instructions for translators are to sign up, open the project page, click JOIN THIS PROJECT and pick a language. For a language that is not listed yet, the readme asks you to email the maintainer or open an issue, and for developers the pull command is tx pull --all with the Transifex client.

When to use turbo and when to write your own client

There is a clear alternative to overpass turbo, and it is not another GUI. It is talking to the Overpass API directly from your own code.

The difference in approach is real. overpass turbo is a browser application for a human: you compose a query, you look at a map, you read a preview, and you save or share a link. A direct client is a library call in a script: you build the query string, you send it, you parse the JSON, and you do whatever you want with it. The turbo path is better for exploring what data exists and for sharing a finding with a colleague. The direct path is better for anything scheduled, anything that processes results at volume, and anything that has to run without a person watching.

The readme itself points at the two alternatives worth knowing. Ultra is a re-imagining of overpass turbo powered by MapLibre GL JS, which allows for visualizing large datasets and complex styling. And QuickOSM is a QGIS plugin to fetch OSM data with the Overpass API, which is the same idea in a different host application for people who live in QGIS rather than a browser.

The limitation to keep in mind is on the data side rather than the tool side. The Overpass API is a shared public resource with usage policies, and a tool that makes querying easy is also a tool that makes it easy to query too much. The readme does not discuss rate limiting or etiquette, so that is a decision you have to make for yourself, and the first thing to check is which public instance you are pointed at and what its policy says.

Editorial conclusion

overpass-turbo is worth adopting if you work with OpenStreetMap data and you want to compose and test Overpass queries in a browser with a map and a data preview instead of in a text editor and a command line, because the URL parameter support means a query can be shared and reloaded as a link. It is the wrong choice if you need programmatic bulk extraction, where a direct Overpass API client in your own code is simpler, and it is the wrong choice if you need analysis rather than querying, since the readme is explicit that it is a GUI for testing and developing queries with simple analysis as a secondary use. Before you deploy your own instance, read the licence file rather than the MIT field in the package metadata, and note that the last push was on 2026-10-02.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. tyrasd/overpass-turbo on GitHub