docker-staticmaps: A selfhosted Static Maps API

Many developers rely on Google’s Static Maps API to generate map images, but this has limitations such as:

API rate limits

Cost for high-volume usage

Potential data privacy concerns

Dependency on an external service

For a long time I was looking for an alternative to Maps Static API from Google which can be selfhosted but I couldn't find anything which seemed to fit my needs.

However I found staticmaps which is a Node.JS library for creating map images with markers, polylines, polygons and text. But the library doesn't provide a web interface so I decided to built one on top of it with express and containerized the staticmaps API.

Docker Static Maps API

docker-staticmaps is a containerized web version for staticmaps with express.

In general docker-staticmaps provides a self-hosted alternative that allows you to generate static map images on your own server without relying on third-party APIs.

Demo

Usage

To get a static map from the endpoint /staticmaps several prameters have to be provided.

center - Center coordinates of the map in the format lon, lat

zoom - Set the zoom level for the map.

width - default 300 - Width in pixels of the final image

height - default 300 - Height in pixels of the final image

format - default png (e.g. png, jpg or webp)

basemap - default osm - Map base layer

Basemaps

For different basemaps docker-staticmaps is using exisiting tile-services from various providers. Be sure to check their Terms of Use for your use case or use a custom tileserver with the tileUrl parameter!

basemap - default "osm" - Select the basemap

osm - default - Open Street Map

streets - Esri street basemap

satellite - Esri's satellite basemap

hybrid - Satellite basemap with labels

topo - Esri topographic map

gray - Esri gray canvas with labels

gray-background - Esri gray canvas without labels

oceans - Esri ocean basemap

national-geographic - National Geographic basemap

otm - OpenTopoMap

stamen-toner - Stamen Toner black and white map with labels

stamen-toner-background - Stamen Toner map without labels

stamen-toner-lite - Stamen Toner Light with labels

stamen-terrain - Stamen Terrain with labels

stamen-terrain-background - Stamen Terrain without labels

stamen-watercolor - Stamen Watercolor

carto-light - Carto Free usage for up to 75,000 mapviews per month, non-commercial services only.

carto-dark - Carto Free usage for up to 75,000 mapviews per month, non-commercial services only.

carto-voyager - Carto Free usage for up to 75,000 mapviews per month, non-commercial services only.

custom - Pass through the tile URL using parameter tileurl

Polylines

With the parameter polyline you can add a polyline to the map in the following format:

polyline=polylineStyle|polylineCoord1|polylineCoord2|...

polylineCoord - required - in format lat,lon and seperated by |. Atleast two locations are needed to draw a polyline.

The polylineStyle consists of the following two parameters separated by |.

weight - default 5 - Weight of the polyline in pixels, e.g. weight:5

color - default blue -24-Bit-color hex value, e.g. color:0000ff

If no center is specified, the polyline will be centered.

Polyline with no zoom, weight:6 and color:0000ff

http://localhost:3000/staticmaps?width=600&height=600&polyline=weight:6|color:0000ff|48.726304979176675,-3.9829935637739382|48.72623035828412,-3.9829726446543385|48.726126671101639,-3.9829546542797467|48.725965124843256,-3.9829070729298808|48.725871429380568,-3.9828726793245273|48.725764250990267,-3.9828064532306628|48.725679557682362,-3.9827385375789146|48.72567025076134,-3.9827310750289113|48.725529844164292,-3.9826617613709225|48.725412537198615,-3.9826296635284164|48.725351694726704,-3.9826201452878531|48.725258599474508,-3.9826063049230411|48.725157520450125,-3.9825900299314232|48.725077863838543,-3.9825779905509102|48.724930435729831,-3.9825514102373938|48.724815578113535,-3.9825237355887291|48.724760905376989,-3.9825013965800564|48.724677938456551,-3.9824534296566916|48.724379435330384,-3.9822469276001118|48.724304509274596,-3.9821850264836076|48.7242453124599,-3.9821320570321772|48.724206187829317,-3.9821063430223207|48.724117073204575,-3.9820862134785551

Polygons

With the parameter polygon you can add a polygon to the map in the following format:

polygon=polygonStyle|polygonCoord1|polygonCoord2|...

polygonCoord - required - in format lat,lon and seperated by |. First and last locations have to be the same to close the polygon.

The polygonStyle consists of the following two parameters separated by |.

color - default blue -24-Bit-color hex value, e.g. color:4874db

weight - default 5 - Weight of the polygon in pixels, e.g. weight:5

fill - default green -24-Bit-color hex value, e.g. fill:eb7a34

If no center is specified, the polygon will be centered.

Polygon with no zoom, color:4874db,weight:7 and fill:eb7a3

http://localhost:3000/staticmaps?width=600&height=600&polygon=color:4874db|weight:7|fill:eb7a34|41.891169,12.491691|41.890633,12.493697|41.889012,12.492989|41.889467,12.490811|41.891169,12.491691

Markers

With the parameter markers you can draw one or multiple markers depending on how much pair of coordinates you pass to the parameter

markers=markerCoord1|markerCoord2|...

markerCoord - required - in format lat,lon and separated by |. Atleast one coordinate is needed to draw a marker.

If no center is specified, the markers will be centered.

Markers

http://localhost:3000/staticmaps?width=600&height=600&markers=48.726304979176675,-3.9829935637739382|48.724117073204575,-3.9820862134785551

Circles

With the parameter circle you can add a circle to the map in the following format:

circle=circleStyle|circleCoord

circleCoord - required - in format lat,lon and separated by |. Atleast one locations is needed to draw a marker.

The circleStyle consists of the following parameters seperated by |.

radius - required - Circle radius in meter, e.g. radius:500

color - default #0000bb - Stroke color of the circle, e.g. color:#0000bb

width - default 3 - Stroke width of the circle, e.g. width:3

fill - default #AA0000 - Fill color of the circle, e.g. fill:#AA0000

If no center is specified, the circle will be centered.

Circle with no zoom

http://localhost:3000/staticmaps?width=600&height=600&basemap=osm&circle=radius:100|48.726304979176675,-3.9829935637739382

More usage Examples

Minimal example: center and zoom

http://localhost:3000/staticmaps?center=-119.49280,37.81084&zoom=9

width=500, height=500, center=-73.99515,40.76761, zoom=10, format=webp, basemap=carto-voyager

http://localhost:3000/staticmaps?width=500&height=500¢er=-73.99515,40.76761&zoom=10&format=webp&basemap=carto-voyager

Markers and Polyline

http://localhost:3000/staticmaps?width=600&height=600&polyline=weight:6|color:0000ff|48.726304979176675,-3.9829935637739382|48.72623035828412,-3.9829726446543385|48.726126671101639,-3.9829546542797467|48.725965124843256,-3.9829070729298808|48.725871429380568,-3.9828726793245273|48.725764250990267,-3.9828064532306628|48.725679557682362,-3.9827385375789146|48.72567025076134,-3.9827310750289113|48.725529844164292,-3.9826617613709225|48.725412537198615,-3.9826296635284164|48.725351694726704,-3.9826201452878531|48.725258599474508,-3.9826063049230411|48.725157520450125,-3.9825900299314232|48.725077863838543,-3.9825779905509102|48.724930435729831,-3.9825514102373938|48.724815578113535,-3.9825237355887291|48.724760905376989,-3.9825013965800564|48.724677938456551,-3.9824534296566916|48.724379435330384,-3.9822469276001118|48.724304509274596,-3.9821850264836076|48.7242453124599,-3.9821320570321772|48.724206187829317,-3.9821063430223207|48.724117073204575,-3.9820862134785551&markers=48.726304979176675,-3.9829935637739382|48.724117073204575,-3.9820862134785551

Deployment

with Docker

docker run -d \
--name='static-maps-api' \
-p '3003:3000/tcp' \
'mxdcodes/docker-staticmaps:latest'

with Node.js

git clone https://github.com/dietrichmax/docker-staticmaps
npm i
npm run start

Links

GitHub: https://github.com/dietrichmax/docker-staticmaps

Docker Hub: https://hub.docker.com/r/mxdcodes/docker-staticmaps