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.

Usage

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

Parameter Description Example center Latitude,Longitude of map center 48.8588443,2.2943506 zoom Zoom level (1-20) 12 size Image size in pixels 600x400 marker Add a marker at a location 48.8588,2.2943,red polyline Draw a line on the map 48.85,2.29;48.86,2.30,blue,2

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

Sorry, somehow the image couldn't be found :(

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

Sorry, somehow the image couldn't be found :(

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

Sorry, somehow the image couldn't be found :(

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

Sorry, somehow the image couldn't be found :(

More usage Examples

Minimal example: center and zoom

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

Sorry, somehow the image couldn't be found :(

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

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

Sorry, somehow the image couldn't be found :(

Markers and Polyline

Sorry, somehow the image couldn't be found :(

Deployment

with Docker

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

with Node.js

bashCopy code
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

Table of Contents

Docker Static Maps API
Usage
Basemaps
Polylines
Polygons
Markers
Circles
More usage Examples
Deployment

First published: December 28, 2024

Docker Node.js Web-GIS Selfhosted Javascript Open Source GIS