osm-static-maps

Here you have a demo. Also a dynamic version of the demo, for testing purposes.

How to use

1. CLI

The quickest way, with no install required, is via npx:

npx osmsm --help
npx osmsm -g '{"type":"Point","coordinates":[-105.01621,39.57422]}' > map.png
or, if chrome executable is not found
PUPPETEER_EXECUTABLE_PATH=/path/to/chrome npx osmsm -g '...' > map.png

Or install it globally to get the osmsm command:

sudo npm i -g osm-static-maps
osmsm --help
osmsm -g '{"type":"Point","coordinates":[-105.01621,39.57422]}' > map.png

• note: if you have this error trying to install globally Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/osm-static-maps/node_modules/puppeteer/.local-chromium', it's caused by this pupeteer issue https://github.com/puppeteer/puppeteer/issues/367, you can workaround by installing globally with the unsafe-perm flag:

sudo npm i -g osm-static-maps --unsafe-perm=true

2. nodejs library

npm install osm-static-maps

// index.js old school
osmsm = require('osm-static-maps');
osmsm({geojson: geojson})
  .then(function(imageBinaryBuffer) { ... })
  .catch(function(error) { ... })
// index.js modern style (also supports typescript)
import osmsm from 'osm-static-maps'
const imageBinaryBuffer = await osmsm({geojson})

3. Standalone sample server

npx osmsm serve

Or install it globally:

sudo npm i -g osm-static-maps
osmsm serve

Or you can use docker-compose

git clone [email protected]:jperelli/osm-static-maps.git
cd osm-static-maps
docker-compose up

4. Cloud service

You can use the heroku-hosted alternative directly here

We are currently in the cloud beta, contact me directly at [email protected] so I can give you access to the cloud service.

API Reference

All parameters have a short and long version. The short version can be used only with the shell CLI. The long version can be used with the library and can be passed to the app server as GET query params, or POST json body (remember to set the header Content-Type: application/json)

| | Parameter | Description | Default Value | | - | ---- | ---- | ---- | | g | geojson | geojson object to be rendered in the map | undefined | | f | geojsonfile | filename or url to read geojson data from (use '-' to read from stdin on CLI) | undefined | | H | height | height in pixels of the returned img | 600 | | W | width | height in pixels of the returned img | 800 | | c | center | center of the map lon,lat floats string | (center of the geojson) or '-57.9524339,-34.921779' | | z | zoom | zoomlevel of the leaflet map | value of maxZoom | | Z | maxZoom | max zoomlevel of the leaflet map | 17 | | A | attribution | attribution legend | 'osm-static-maps / © OpenStreetMap contributors' (or 'osm-static-maps' when vectorserverUrl is set) | | t | tileserverUrl | url of a tileserver | 'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' | | m | vectorserverUrl | url of a vector tile server (MVT style.json) | undefined | | M | vectorserverToken | used as Authorization: Bearer header on vector map requests | undefined | | | vectorserverAttribution | append the vector layers source attributions (CLI: --no-vectorserverAttribution to disable) | true | | D | renderToHtml | returns html of the webpage containing the map (instead of a binary image) | false | | F | type | format of the image returned ('png'/'jpeg'/'webp') | 'png' | | q | quality | quality of the image returned (0-100, only for jpeg and webp; png is lossless) | 100 | | x | imagemin | enable lossless compression with optipng / jpegtran (ignored for webp) | false | | X | oxipng | enable lossless compression with oxipng (png only) | false | | a | arrows | render arrows to show the direction of linestrings | false | | s | scale | enable render a scale ruler (boolean or a json options object) | false | | T | timeout | miliseconds until page load throws timeout | 20000 | | k | markerIconOptions | set marker icon options (a json options object) *see note | undefined (leaflet's default marker) | | S | style | style to apply to each feature (a json options object) *see note | undefined (leaflet's default) | | e | haltOnConsoleError | throw error if there is any console.error(...) when rendering the map image | false | | i | isolated | render in a fresh browser page instead of reusing a warm one (see Page reuse) | false |

• Note on markerIconOptions: it's also accepted a markerIconOptions attribute in the geojson feature, for example {"type":"Point","coordinates":[-105.01621,39.57422],"markerIconOptions":{"iconUrl":"https://leafletjs.com/examples/custom-icons/leaf-red.png"}}

• Note on style: it's also accepted a pathOptions attribute in the geojson feature, for example {"type":"Polygon","coordinates":[[[-56.698,-36.413],[-56.716,-36.348],[-56.739,-36.311]]],"pathOptions":{"color":"#FF5555"}} (also remember that the # char needs to be passed as %23 if you are using GET params)

Page reuse

Every render needs a browser page with leaflet/maplibre parsed and the background layer loaded, which is most of the time of a render once the tiles are cached. Since 6.0.0 those pages are kept warm and reused: a render that finds an idle page with the same width, height, maxZoom, tile/vector server, token, attribution setting and marker icon only swaps the geojson, arrows, scale, attribution text and view inside it. Repeated or neighbouring renders (e.g. many routes of the same city) get several times faster; a render in an area whose tiles are not loaded yet is still bound by the tile download. By default up to 4 idle pages are kept and a page is closed and rebuilt after 100 renders (configureBrowser({ maxIdlePages, maxRendersPerPage }), osmsm serve --max-idle-pages N --max-renders-per-page N, or the env vars OSMSM_MAX_IDLE_PAGES / OSMSM_MAX_RENDERS_PER_PAGE); a page whose render failed is closed. Idle pages only cost memory while they wait; closing one drops its in-memory tiles, not chromium's HTTP cache, so the rebuilt page re-reads them from the disk cache.

Pass isolated: true (-i, --isolated on the CLI, ?isolated=true on the server, osmsm serve --isolated to make it the default) to render in a fresh page that is closed afterwards.

The one-shot CLI additionally launches chromium with --single-process; serve and the library never do, as one crashed render would take the shared browser down.

Development

git clone [email protected]:jperelli/osm-static-maps.git
cd osm-static-maps
npm install
npm run dev    # start the sample server with autoreload
npm test       # run the test suite (vitest)

Running the library/CLI/server requires Node >= 20 (see engines). The test toolchain (vitest/vite) is stricter and needs Node 20.19+, 22.12+, or 24+ — this only matters for contributors running npm test, not for consumers of the published package. The CI matrix runs the tests on Node 20, 22, 24 and 26.

Design considerations & architecture

Read the blogpost on the creation of this library and how it works internally

LICENSE

- GPL-2.0-only

Credits

Specially to the contributors of

• OpenStreetMap
• Leaflet
• Puppeteer
• ExpressJS
• Handlebars