Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



Create a static image of a map with the features you want

Version published
Weekly downloads
increased by45.34%
Install size
124 MB
Weekly downloads




Openstreetmap static maps is a nodejs lib, CLI and server open source inspired on google static map service

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

How to use

1. CLI

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, 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

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

Or you can use docker-compose

git clone
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 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)

ParameterDescriptionDefault Value
ggeojsongeojson object to be rendered in the mapundefined
fgeojsonfilefilename or url to read geojson data from (use '-' to read from stdin on CLI)undefined
Hheightheight in pixels of the returned img600
Wwidthheight in pixels of the returned img800
ccentercenter of the map lon,lat floats string(center of the geojson) or '-57.9524339,-34.921779'
zzoomzoomlevel of the leaflet mapif vectorserverUrl available, use 12 else 20
ZmaxZoommax zoomlevel of the leaflet map17
Aattributionattribution legend'osm-static-maps / © OpenStreetMap contributors'
ttileserverUrlurl of a tileserver'http://{s}{z}/{x}/{y}.png'
mvectorserverUrlurl of a vector tile server (MVT style.json)undefined
MvectorserverTokentoken of the vector tile server (MVT)'no-token'
DrenderToHtmlreturns html of the webpage containing the map (instead of a binary image)false
Ftypeformat of the image returned ('jpeg'/'png')'png'
qqualityquality of the image returned (0-100, only for jpg)100
ximageminenable lossless compression with optipng / jpegtranfalse
Xoxipngenable losslsess compression with oxipngfalse
aarrowsrender arrows to show the direction of linestringsfalse
sscaleenable render a scale ruler (boolean or a json options object)false
Ttimeoutmiliseconds until page load throws timeout20000
kmarkerIconOptionsset marker icon options (a json options object) *see noteundefined (leaflet's default marker)
Sstylestyle to apply to each feature (a json options object) *see noteundefined (leaflet's default)
ehaltOnConsoleErrorthrow error if there is any console.error(...) when rendering the map imagefalse
  • 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":""}}

  • 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)

Design considerations & architecture

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


  • GPLv2


Specially to the contributors of

  • OpenStreetMap
  • Leaflet
  • Puppeteer
  • ExpressJS
  • Handlebars


Last updated on 30 Apr 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc