@brakebein/osm-static-maps

osm-static-maps

Openstreetmap static maps is a Node.js lib, CLI and server open source inspired on Google static map service.

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 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. Node.js library

npm install osm-static-maps

// index.js old school
const { 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 [e-mail]:jperelli/osm-static-maps.git
cd osm-static-maps
docker-compose up

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	if vectorserverUrl available, use 12 else 20
Z	maxZoom	max zoomlevel of the leaflet map	17
A	attribution	attribution legend	'osm-static-maps / © OpenStreetMap contributors'
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	token of the vector tile server (MVT)	'no-token'
D	renderToHtml	returns html of the webpage containing the map (instead of a binary image)	false
F	type	format of the image returned ('jpeg'/'png')	'png'
q	quality	quality of the image returned (0-100, only for jpg)	100
x	imagemin	enable lossless compression with optipng / jpegtran	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

• 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

Design considerations & architecture

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

LICENSE

• GPLv2

Credits

Specially to the contributors of

• OpenStreetMap
• Leaflet
• Puppeteer
• ExpressJS
• Handlebars