How to use Static Maps

Highlight regions on a static map

Static maps allow you to easily add a map to your website or app as a regular image. So using them is useful when you just want to display a map and don't need any interactivity.

The required map image is generated dynamically on a server. In addition, you can add markers and shares to highlight some areas and places. This tutorial will review how to use Static Maps and set its parameters to achieve the desired results.

Choose a Static Map view

The first thing you need to set when generating a static map is the map image size. Here are the parameters you use for this:

ParameterDescriptionExample
widthStatic map width in pixelswidth=640
heightStatic map height in pixelsheight=460

You can choose from several map styles. Use the style parameter to select one:

ParameterDescriptionExample
styleMap stylestyle=osm-bright-grey

You can choose among several options for your map view - let the algorithms determine the view automatically, trying to fit the provided markers and shapes, or define the map explicitly with the parameters:

ParameterDescriptionExample
areaAn area that should be visible on the maparea=rect:-84.2772,33.7865,-84.2435,33.7712
center + zoomThe map center and zoomcenter=lonlat:-122.685464,45.5130378&zoom=15

Adding markers to a map

You can add single or multiple markers to the map with the markers parameter. When adding more than one marker, use a pipe character (|) to separate each definition:

ParameterDescriptionExample
markerMarkers separated by |marker=lonlat:-122.299807,47.526808|lonlat:-122.305944,47.523674;color:%23bb3f73;size:x-large

You can change marker icons' color, shape, and content by editing their properties. See the Static Maps documentation for details and examples.

Drawing shapes on a map

You can draw shapes (circles, rectangles, and so on) on a static map with the parameters:

ParameterDescriptionExample
geometrycircle, rectangle, polyline, or polygon objects separated by the "|" charactergeometry=circle:-73.044725,40.633252,10;linewidth:3;linecolor:%23ff44ff;fillcolor:%2344ffff
geojsonURL-encoded GeoJSON Feature or FeatureCollection objectgeojson=%7B%22type%22%3A%22Feature%22%2C%22 properties%22%3A%7B%22linecolor%22%3A%22%23000000%22%2C%22linewidth%22%3A5%2C%22 lineopacity%22%3A1%2C%22fillcolor%22%3A%22%234b68dd%22%2C%22 fillopacity%22%3A0.5%7D%2C%22geometry%22%3A%7B%22type%22%3A%22 Polygon%22%2C%22coordinates%22%3A%5B%5B%5B-118.339694%2C33.943600 %5D%2C%5B-118.33969%2C33.941953%5D%2C%5B-118.33523%2C33.941944%5D%2C% 5B-118.33522%2C33.94360%5D%2C%5B-118.339694%2C33.943600%5D%5D%5D%7D%7D

Please note that because of limitations on URL lengths, URL-encoded GeoJSON strings are also limited.

For more details on the structure and visualization properties of geometries, see the Static Map Documentation page.

Static Map examples

To use Geoapify Static Maps, you need a Geoapify API key. You can register and generate one by yourself on the Geoapify MyProjects page.

  • using the center and zoom parameters to define the map view:

Set center and zoom for a map image

https://maps.geoapify.com/v1/staticmap?style=osm-liberty&width=600&height=400&center=lonlat:-122.685464,45.5130378&zoom=15&pitch=52&bearing=54&apiKey=YOUR_API_KEY
  • using the area parameter to define the map view: Set an area to fit on the map
https://maps.geoapify.com/v1/staticmap?style=osm-liberty&width=600&height=400&area=rect:-84.2772,33.7865,-84.2435,33.7712&apiKey=YOUR_API_KEY
  • add a marker in the map center: A static map with a place marker
https://maps.geoapify.com/v1/staticmap?style=klokantech-basic&width=600&height=400&marker=lonlat:15.076032674463988,37.50450761142886;type:awesome;color:%23408ed7;size:x-large;icon:h-square;whitecircle:no&apiKey=YOUR_API_KEY
  • add multiple markers:

A static map with multiple markers

https://maps.geoapify.com/v1/staticmap?style=klokantech-basic&width=600&height=400&marker=lonlat:15.076032674463988,37.50450761142886;type:awesome;color:%23408ed7;size:x-large;icon:h-square;whitecircle:no|lonlat:15.076094476565743,37.5117317930609;type:awesome;color:%23408ed7;size:x-large;icon:h-square;whitecircle:no|lonlat:15.06022542074038,37.50748071337533;type:awesome;color:%23408ed7;size:x-large;icon:h-square;whitecircle:no|lonlat:15.05242096705527,37.51107144705128;type:awesome;color:%23408ed7;size:x-large;icon:h-square;whitecircle:no|lonlat:15.068758290102267,37.51028727857664;type:awesome;color:%23aaafb4;size:large;icon:h-square;whitecircle:no|lonlat:15.067301458747664,37.50673778139405;type:awesome;color:%23aaafb4;size:large;icon:h-square;whitecircle:no|lonlat:15.059028737841913,37.5014957734128;type:awesome;color:%23aaafb4;size:large;icon:h-square;whitecircle:no|lonlat:15.053669679644344,37.5050867949646;type:awesome;color:%23aaafb4;size:large;icon:h-square;whitecircle:no|lonlat:15.074637645211197,37.50013361660724;type:awesome;color:%23aaafb4;size:large;icon:h-square;whitecircle:no|lonlat:15.069018438558373,37.5028579053683;type:awesome;color:%23aaafb4;size:large;icon:h-square;whitecircle:no&apiKey=YOUR_API_KEY
  • add circles to the map:

Draw circles on a map image

https://maps.geoapify.com/v1/staticmap?style=osm-bright-grey&width=600&height=400&geometry=circle:7.445297742419882,46.948361872425124,30;fillcolor:%23f9a9eb;fillopacity:0.5|circle:7.438301614578734,46.94649487478634,20;fillcolor:%23293a77|circle:7.441672476175171,46.94811873223475,100;fillcolor:%236ded83;fillopacity:0.5&apiKey=YOUR_API_KEY
  • add rectangles to the map:

Draw rectangles on a map image

https://maps.geoapify.com/v1/staticmap?style=toner-grey&width=600&height=400&geometry=rect:-0.3735794501762939,39.46012847701809,-0.32031815564982935,39.48224631549971;fillcolor:%23ff8737|rect:-0.3881691777199876,39.44533409789409,-0.3698880733277292,39.45863560890271;linecolor:%2300afff;linewidth:5;linestyle:dashed&apiKey=YOUR_API_KEY
  • add polylines and polygons to the map:

Polylines and polygons on a map

https://maps.geoapify.com/v1/staticmap?style=positron&width=600&height=400&geometry=polyline:-77.81882286071777,34.27218359557089,-77.8165054321289,34.26977200698157,-77.81418800354004,34.26821153044989,-77.81161308288574,34.26686382286875,-77.80929565429688,34.267502213362675,-77.8066349029541,34.26792780433297,-77.80345916748045,34.26806966751108,-77.7996826171875,34.26821153044989,-77.79487609863281,34.26906270305702,-77.7912712097168,34.270126656700164,-77.78895378112793,34.27104873896822,-77.78800964355467,34.270977809921966,-77.78500556945801,34.26941735576717,-77.78148651123047,34.267147552575445,-77.7788257598877,34.26516142452615,-77.77599334716797,34.26310431388478;linewidth:5;linecolor:%23eb44ea|polygon:-77.80212879180907,34.26303337813771,-77.79882431030273,34.26140183944268,-77.79448986053467,34.265374226203555,-77.795090675354,34.26583529465743,-77.79590606689452,34.26654462580447,-77.79654979705809,34.26672195765641,-77.7971076965332,34.26526782543215,-77.79839515686035,34.264061940615136,-77.79942512512207,34.26352992711102,-77.8001546859741,34.26356539478267,-77.80066967010498,34.26399100567567,-77.80092716217041,34.264168342912114,-77.80152797698975,34.263671797707836,-77.80212879180907,34.26303337813771;fillcolor:%23d6ff00;fillopacity:0.7&apiKey=YOUR_API_KEY
  • add more complex shapes as GeoJSON:

Polygons with holes on static maps

https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=600&height=400&geojson=%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22fillcolor%22%3A%22%23488ca6%22%2C%22fillopacity%22%3A0.6%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B-118.368072%2C33.928548%5D%2C%5B-118.36910%2C33.918292%5D%2C%5B-118.37013%2C33.90347%5D%2C%5B-118.366355%2C33.894642%5D%2C%5B-118.358459%2C33.88865%5D%2C%5B-118.348503%2C33.880677%5D%2C%5B-118.3382034%2C33.870130%5D%2C%5B-118.32893%2C33.86613%5D%2C%5B-118.311424%2C33.86072%5D%2C%5B-118.29219%2C33.8610%5D%2C%5B-118.28670%2C33.858157%5D%2C%5B-118.2863%2C33.86129%5D%2C%5B-118.291511%2C33.8726%5D%2C%5B-118.2877349%2C33.87326%5D%2C%5B-118.286018%2C33.8764%5D%2C%5B-118.288421%2C33.898631%5D%2C%5B-118.28910%2C33.91373%5D%2C%5B-118.28292%2C33.9222808%5D%2C%5B-118.2818%2C33.9276%5D%2C%5B-118.290481%2C33.92883%5D%2C%5B-118.300094%2C33.92655%5D%2C%5B-118.31176%2C33.924559%5D%2C%5B-118.3203%2C33.924559%5D%2C%5B-118.33030%2C33.922850%5D%2C%5B-118.340606%2C33.92683%5D%2C%5B-118.35433%2C33.933390%5D%2C%5B-118.368072%2C33.928548%5D%5D%2C%5B%5B-118.352966%2C33.916013%5D%2C%5B-118.352279%2C33.902051%5D%2C%5B-118.32824%2C33.90319%5D%2C%5B-118.326873%2C33.916013113401696%5D%2C%5B-118.352966%2C33.916013%5D%5D%2C%5B%5B-118.343696%2C33.887232%5D%2C%5B-118.34378%2C33.87775%5D%2C%5B-118.318033%2C33.8872%5D%2C%5B-118.343696%2C33.887232%5D%5D%5D%7D%7D&apiKey=YOUR_API_KEY
  • gray out map except for an area with GeoJSON:

Gray out map except a polygon

https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=600&height=400&area=rect:2.2158050537109375,48.8032455364465,2.470550537109375,48.911218476584025&geojson=%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22fillcolor%22%3A%22%23000%22%2C%22fillopacity%22%3A0.7%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B2.19142913%2C48.7822111%5D%2C%5B2.50350952%2C48.7822111%5D%2C%5B2.50350952%2C48.9441512%5D%2C%5B2.19142913%2C48.9441512%5D%2C%5B2.19142913%2C48.7822111%5D%5D%2C%5B%5B2.30781%2C48.8956%5D%2C%5B2.29373%2C48.89022%5D%2C%5B2.2837%2C48.882%5D%2C%5B2.25254%2C48.8522%5D%2C%5B2.25528%2C48.8466%5D%2C%5B2.2539%2C48.8389%5D%2C%5B2.2607%2C48.8355%5D%2C%5B2.271%2C48.8351%5D%2C%5B2.3263%2C48.8202%5D%2C%5B2.3359%2C48.8174%5D%2C%5B2.35107%2C48.8177%5D%2C%5B2.36309%2C48.8172%5D%2C%5B2.3778%2C48.82266%5D%2C%5B2.4094%2C48.8355%5D%2C%5B2.41458%2C48.8516%5D%2C%5B2.41081%2C48.8651%5D%2C%5B2.4132%2C48.8692%5D%2C%5B2.40772%2C48.87961%5D%2C%5B2.39776%2C48.8843%5D%2C%5B2.3912%2C48.9006%5D%2C%5B2.3191%2C48.8999%5D%2C%5B2.30781%2C48.8956%5D%5D%5D%7D%7D&marker=lonlat:2.3494655661542367,48.85774273910704;type:awesome;color:%2319b8fc;size:large&apiKey=YOUR_API_KEY

What's next