city-roads: rendering every road in a city from OpenStreetMap data

What city-roads actually produces, and who it is for

The project renders every single road in a city at once. You type a place name into the search box and get a drawing of the street network for that area, hosted at https://anvaka.github.io/city-roads/. The README frames the result as art.

The audience splits in two. The first group is people who want the image itself: a poster-like view of a city's street pattern. The second group is software engineers. The README states that behind the simple UI there are scripting capabilities, and that programs can be developed on top of city-roads, with examples in the separate city-script repository and a Scene API documented in API.md. If you are looking for a map component to embed in a product, this is not that. It is a renderer with a programmatic scene description.

Overpass, Nominatim and the cached city index

The data flow has three stages. First, name resolution: whatever you type goes to Nominatim, which returns a list of area ids. Second, a cache lookup: the project indexed roughly 3,000 cities with population larger than 100,000 people and stored them in a protobuf format in a separate repository, anvaka/index-large-cities. The area id from Nominatim is checked against that cache first. Third, the fallback: if the area is not in the cache, the roads are fetched from OpenStreetMap through the Overpass API.

The README is explicit about why the cache exists. Overpass is free as long as you follow the ODbL licence, but it can be rate-limited and sometimes slow, and the tool is downloading thousands of roads within an area. Pre-indexing the large cities removes that download for the common case.

The trade-off is that the cache only covers cities above the population threshold. A small town or any other area missing from the cache goes to Overpass on every request, which is where the latency and rate-limit behaviour described in the README shows up. There is no documented retry policy or offline mode in the README, so a slow Overpass response is visible to the user as a slow render.

Running city-roads locally and rendering your first city

The README gives the local development commands directly. The project uses Vite, so the dev server starts on localhost:8080 with hot reload.

# install dependencies
npm install

# serve with hot reload at localhost:8080
npm run dev

After npm run dev, open localhost:8080 in a browser. You should see the search box. Type a city name and the app resolves it through Nominatim, checks the cached city index, and either renders from cache or fetches roads from Overpass.

For a production bundle, the README lists a build step and an optional analyzer report:

# build for production with minification
npm run build

# build for production and view the bundle analyzer report
npm run build --report

The package.json confirms the toolchain: the dev script is vite, the build script is vite build, and there is a lint script that runs eslint over .vue, .js, .jsx, .cjs and .mjs files. The runtime dependencies include w-gl for WebGL rendering, d3-geo, pbf for the protobuf city index, and vue 3. If you only want the hosted version, none of this is necessary; the commands matter when you want to modify the renderer or self-host it.

The rendering ceiling is your video card, not the data

The README states the limitation plainly: rendering is limited by the browser and video card memory capacity. The author was able to render Seattle roads without a hiccup on a very old Samsung phone, but Tokyo, with 1.4 million segments, was very slow on that device. Selecting an area with millions of roads, such as Washington state, may cause the page to crash even on a powerful device.

That is the wrong-tool case. If your goal is a statewide or countrywide network diagram, city-roads is not the instrument; the failure is a browser tab that dies, not a degraded but usable picture. The README's own summary is that most cities render without problems.

There is a second boundary that the README does not address: what the roads mean. The output is geometry. The README does not document filtering by road class, one-way status, speed limit or surface, and it does not describe a routing layer. If your question is how to get from A to B, or which streets are one-way, this project answers a different question.

Scripting against the Scene API instead of the UI

The scripting path is the part aimed at engineers. The README points to API.md in the repository for the Scene API and to the city-script repository for examples.

What the README does not provide is an inventory of Scene API methods, and the repository has no published releases. The API.md file in the repository root is the authoritative source, and it is the file to read before writing code against it. Treat the API as the contract and the absence of published releases as a signal that versioning is not the project's primary concern.

Maintenance context is relevant here. The repository is not archived, and the last push was on 2026-10-10, about three weeks before the current date.

How city-roads differs from general-purpose map libraries

The obvious alternative is a general-purpose web map library such as Leaflet or MapLibre GL, paired with a tile source and a road layer. The difference in approach is fundamental. A tile-based map library streams pre-rendered raster or vector tiles for the current viewport and expects you to add interaction, popups and layers on top. city-roads does the opposite: it fetches the raw road geometry for the whole area through Overpass, caches a city index to avoid repeated downloads, and renders the entire network in one WebGL scene through w-gl.

That architecture is why the visual is dense and complete, and also why the failure mode is a crashed tab rather than a blank tile. A tile-based map degrades gracefully when you zoom out, because the server decides what detail to send. city-roads asks the client to hold everything, and the README's Tokyo and Washington examples show where that ends.

The second difference is data licensing. Overpass data comes under ODbL, and the README notes the API is free as long as you follow those licences. Tile providers have their own terms. The project's own source code is MIT, but the rendered road data is not covered by that MIT grant, and the README does not spell out attribution requirements for derived images.

Licence, forks and what a fork costs you

The repository is MIT licensed, and the README says the source code is licensed under MIT. That is permissive: you can use the code in your own projects, which the README explicitly welcomes. It is not legal advice, and MIT covers the code, not the OpenStreetMap data flowing through Overpass, which the README ties to ODbL.

Upgrade cost is low in the ordinary sense. The repository has no published GitHub releases, so there is no changelog to track and no migration path to plan. The dependency set is small and modern enough to be unremarkable: vue 3, vite 2, d3-geo, pbf, tinycolor2, w-gl. A fork inherits that set and the npm scripts, nothing more. If you fork, the cost is not upgrades; it is that you now own the Overpass fallback path and any rate-limit behaviour that comes with it.

Editorial conclusion

Adopt city-roads if you need a fast visual answer to what a city's street network looks like, or if you want to script scenes through the documented Scene API. Do not adopt it for routing, turn-by-turn directions, or any query that needs road attributes or topology; it renders geometry, and the README does not describe a routing layer. Before building on it, open API.md and confirm the Scene API surface matches what your program needs, check the ODbL obligations that come with OpenStreetMap data, and test your target area in the hosted app first, because the README states that an area with millions of roads may crash the page even on a powerful device.

Frequently asked questions

Official sources

1. anvaka/city-roads on GitHub
2. Issues
3. License: MIT
4. Project website
5. README