docker-staticmaps: A selfhosted Static Maps API

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 which can be easily selfhosted.

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.

Sorry, somehow the image is not available :(

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.

Sorry, somehow the image is not available :(

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.

Sorry, somehow the image is not available :(

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.

Sorry, somehow the image is not available :(

More usage Examples

Sorry, somehow the image is not available :(

Sorry, somehow the image is not available :(

Sorry, somehow the image is not available :(

Deployment

with Docker

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

with Node.js

bash
Copy 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