Static Maps API

The Static Maps API allows dynamically generating map pictures that can be embedded to websites or apps as ordinary images. The API supports a number of available projections and methods for drawing.

In addition, the Static Maps API lets you generate beautifully rendered high-resolution maps of any size for printing or inclusion in marketing materials.

Try the Static Maps API interactively on our playground:

Static Maps Live Demo



Authenfication and API key

You need an API key to use the static maps API from Geoapify. We have a Free pricing plan you can start with. So sign up and generate an API key when you don't have one already.

This page describes how to generate an API key for Geoapify if you are a new user.

API reference

Here is the Static Maps API URL form:


https://maps.geoapify.com/v1/staticmap?REQUEST_PARAMS


Request parameters

The Static Maps API uses the following parameters to define map images:

Param Description Example
apiKey Geoapify API key apiKey=c3da27885e3573e09e550d044bc55e22
style One of the supported map styles style=osm-bright
width Image width, in pixels, default is 1024. The maximal value is 4096; greater values are available on request. width=800
height Image height, in pixels, default is 768. The maximal value is 4096; greater values are available on request. height=600
format Image format, jpeg or png, default is jpeg as it is much faster for bigger map images. format=png
area Area to display currently supports only rectangular regions defined by two comma-separated pairs of longitude, latitude coordinates area=rect:12.024,42.226,13.001,41.542
center Coordinates of map center, currently supports a coordinate in form of longitude, latitude center=lonlat:-74.044548,40.689252
zoom Map zoom, only used in conjunction with "center", default is 17. Value ∈ [1..20] zoom=14.5
pitch View angle. Value ∈ [0..60] pitch=18
bearing Map rotation in degree. Value ∈ [0..360] bearing=45
marker Marker definition string, multiple markers are separated by pipe "|" character marker=lonlat:-122.68573,45.51105;color:%23ff0000;size:medium
scaleFactor Map image scale factor. Value ∈ [1..2]; greater values are available on request scaleFactor=2
geometry Geometry definition string, multiple geometries are separated by pipe "|" character geometry=circle:-74.04472450744129,40.69366453643252,50;linewidth:5
geojson URL-encoded GeoJSON string with a max length of 1024 characters, the GeoJSON-feature properties linecolor, lineopacity, linewidth, linestyle (solid, dotted, dashed, longdash), fillcolor, fillopacity define visualization options.

NOTE! You must specify one of the following parameters to define the map view: center, area, markers, geometry, or geojson. When the exact map view (center or area) information is missing, it's defined automatically to fit markers or geometries provided.

Marker definitions

You can add multiple markers to static maps. All marker definition parameters are joined with ";" character. Definitions of multiple markers are separated with "|" character.

The following parameters define a marker position and view:

Name Description Example
lonlat Longitude and latitude coordinates of the marker lonlat:-122.68573,45.51105
color Marker color, named or in hex form. Note, # should be URL encoded as "%23". color:%23ff0000
type Marker type, one of material, awesome, circle type:material
size Marker size, one of small, medium, large, x-large, xx-large size:x-large
icon Marker icon name (e.g icon:cloud) icon:tree
iconsize Marker icon size - one of small, medium, large iconsize:medium
icontype Underlying icon font - one of awesome, material icontype:awesome
text Marker text to be used instead of icon text:1
textsize Marker text size, one of small, medium, large textsize:small
whitecircle Add white circle when painting icon or text, one of yes, no whitecircle:no
shadow Shadow presence and color - one of auto, no shadow:no
shadowcolor Color name or hex value; by default derived from marker color shadowcolor:blue
strokecolor Marker outer line color; by name or hex value strokecolor:%230077ff

Here are examples of marker definitions:

Marker Parameters
A map marker with apple icon lonlat:-122.68573,45.51105;type:awesome;color:%231db510;size:x-large;icon:apple-alt;whitecircle:no
Round map marker lonlat:-122.68363,45.51081;type:circle;color:%23109db5;text:1;textsize:large;shadow:no
Material icon marker lonlat:-122.68280,45.50998;type:material;color:%23d1d1d1;size:xx-large;icon:bus-alt;icontype:awesome;strokecolor:%23000000;shadow:no

NOTE! The marker parameters string should be URL-encoded, especially ones containing "#" characters. You can use encodeURIComponent() method to encode URL parameters in JavaScript.

Use Marker Icon API Playground to generate icons for map markers.

Geometry definitions

You can add multiple geometries to static maps. The geometry visualization parameters are joined with ";" character. Definitions of multiple geometries are separated with "|" character.

Below listed the geometry types and their visualization specification that are supported:

Circle

Parameter Required? Description Example
circle:lon,lat,radius REQUIRED The type of geometry, a circle's center and radius in pixels circle:-74.044724,40.693664,50
linecolor:color OPTIONAL Stroke color, URL-encoded color string value linecolor:%23a577ff
lineopacity:opacity OPTIONAL Stroke opacity, takes values from 0 to 1 lineopacity:0.3
linewidth:width OPTIONAL Stroke line width in pixels linewidth:3
linestyle:style OPTIONAL Line style, takes values solid, dotted, dashed, longdash linestyle:dotted
fillcolor:color OPTIONAL Fill color, URL-encoded color string value fillcolor:%23ffff00
fillopacity:opacity OPTIONAL Fill opacity, takes values from 0 to 1 fillopacity:0.3

Rect

Parameter Required? Description Example
rect:lon1,lat1,lon2,lat2 REQUIRED The type of geometry, a rect's nord-west and south-east points longitude and latitude coordinates rect:-74.0447245,40.696645,-74.041724,40.692664
linecolor:color OPTIONAL Stroke color, URL-encoded color string value linecolor:%23a577ff
lineopacity:opacity OPTIONAL Stroke opacity, takes values from 0 to 1 lineopacity:0.3
linewidth:width OPTIONAL Stroke line width in pixels linewidth:3
linestyle:style OPTIONAL Line style, takes values solid, dotted, dashed, longdash linestyle:dotted
fillcolor:color OPTIONAL Fill color, URL-encoded color string value fillcolor:%23ffff00
fillopacity:opacity OPTIONAL Fill opacity, takes values from 0 to 1 fillopacity:0.3

Polyline

Parameter Required? Description Example
polyline:lon1,lat1,lon2,lat2,... REQUIRED The type of geometry, a list longitude and latitude coordinates polyline:13.410189,52.521661,13.412529,52.519263,13.407814,52.517903
linecolor:color OPTIONAL Stroke color, URL-encoded color string value linecolor:%23a577ff
lineopacity:opacity OPTIONAL Stroke opacity, takes values from 0 to 1 lineopacity:0.3
linewidth:width OPTIONAL Stroke line width in pixels linewidth:3
linestyle:style OPTIONAL Line style, takes values solid, dotted, dashed, longdash linestyle:dotted

Polygon

Parameter Required? Description Example
polygon:lon1,lat1,lon2,lat2,... REQUIRED The type of geometry, a list longitude and latitude coordinates polygon:13.410189,52.521661,13.412529,52.519263,13.407814,52.517903
linecolor:color OPTIONAL Stroke color, URL-encoded color string value linecolor:%23a577ff
lineopacity:opacity OPTIONAL Stroke opacity, takes values from 0 to 1 lineopacity:0.3
linewidth:width OPTIONAL Stroke line width in pixels linewidth:3
linestyle:style OPTIONAL Line style, takes values solid, dotted, dashed, longdash linestyle:dotted
fillcolor:color OPTIONAL Fill color, URL-encoded color string value fillcolor:%23ffff00
fillopacity:opacity OPTIONAL Fill opacity, takes values from 0 to 1 fillopacity:0.3

GeoJSON geometry definitions

You can provide a GeoJSON as input to draw it on a map. Because URLs have a length limit, the maximum length of a URL-encoded GeoJSON string is 1,024 characters.

You can provide a Feature or FeatureCollection object as the GeoJSON. Each Feature object may have the following properties to define its appearance on the map:

Parameter Description Example
linecolor Stroke color, URL-encoded color string value "linecolor": "#a577ff"
lineopacity Stroke opacity, takes values from 0 to 1 "lineopacity": 0.3
linewidth Stroke line width in pixels "linewidth": 3
linestyle Line style, takes values solid, dotted, dashed, longdash "linestyle": "dotted"
fillcolor Fill color, URL-encoded color string value "fillcolor": "#ffff00"
fillopacity Fill opacity, takes values from 0 to 1 "fillopacity": 0.3

Below is a GeoJSON object example:

{
  "properties": {
    "fillcolor": "rgb(33,67,11)",
    "fillopacity": 0.4
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [ [ [ 35, 10 ], [ 45, 45 ], [ 15, 40 ], [ 10, 20 ], [ 35, 10 ] ], [ [ 20, 30 ], [ 35, 35 ], [ 30, 20 ], [ 20, 30 ] ] ]
  },
  "type": "Feature"
}

The URL-encoded string for the GeoJSON above is:

geojson={"properties"%3A{"fillcolor"%3A"rgb(33%2C67%2C11)"%2C"fillopacity"%3A0.4}%2C"geometry"%3A{"type"%3A"Polygon"%2C"coordinates"%3A[[[35%2C10]%2C[45%2C45]%2C[15%2C40]%2C[10%2C20]%2C[35%2C10]]%2C[[20%2C30]%2C[35%2C35]%2C[30%2C20]%2C[20%2C30]]]}%2C"type"%3A"Feature"}

Embedding static map pictires to website

You can easily link to a map relevant to your content by using an <img> tag or with CSS background-image ptoperty. In addition, you can add a map with the markup language. Here are code samples of adding static maps:

Using <img> tag

We recommend that you set the width and height of the image container and include the image's description in the "alt" property:

HTML
<img 
  width="600" 
  height="400" 
  src="https://maps.geoapify.com/v1/staticmap?style=toner-grey&width=600&height=400&center=lonlat:-122.683237,45.510309&zoom=15.9318&apiKey=YOUR_API_KEY" 
  alt="Portland State University, 724 Southwest Hooker Street, Portland, OR 97201, United States of America"
>

As background-image

As the static maps are usually generated dynamically, you will probably want to specify styles as container properties:

HTML
<div 
  style="width:600px;height:400px;background-image:url(https://maps.geoapify.com/v1/staticmap?style=toner-grey&width=600&height=400&center=lonlat:-122.683237,45.510309&zoom=15.9318&apiKey=YOUR_API_KEY);"
></div>

With the markdown language

As the API returned a JPG or PNG image, I can also add it with markdown language:

MD
![Portland State University, 724 Southwest Hooker Street, Portland, OR 97201, United States of America](https://maps.geoapify.com/v1/staticmap?style=toner-grey&width=600&height=400&center=lonlat:-122.683237,45.510309&zoom=15.9318&apiKey=YOUR_API_KEY)

API URL Examples

Here are API URL examples (click the URL to generate a static map):

Map with custom pitch and bearing

https://maps.geoapify.com/v1/staticmap?style=osm-liberty&width=600&height=400&center=lonlat:-122.68464,45.510378&zoom=15.7669&pitch=52&bearing=54&apiKey=YOUR_API_KEY

Double-resolution map

https://maps.geoapify.com/v1/staticmap?style=toner-grey&scaleFactor=2&width=600&height=400&center=lonlat:-122.683263,45.510323&zoom=15.9318&apiKey=YOUR_API_KEY

Map with markers

https://maps.geoapify.com/v1/staticmap?style=osm-bright-grey&width=600&height=400&center=lonlat:-122.670651,45.522488&zoom=14.8713&marker=lonlat:-122.67648120519785,45.52446015500584;type:material;color:%231f63e6;size:x-large;icon:cloud;icontype:awesome;text:1;whitecircle:no|lonlat:-122.67129648458975,45.52309591904512;type:material;color:%231f63e6;size:x-large;icon:cloud;icontype:awesome;text:2;whitecircle:no|lonlat:-122.66444608451033,45.522964424673916;type:material;color:%231f63e6;size:x-large;icon:cloud;icontype:awesome;text:3;whitecircle:no&apiKey=YOUR_API_KEY

Map with geometries

https://maps.geoapify.com/v1/staticmap?style=osm-carto&width=600&height=400&zoom=8.8809 &geometry=circle:-74.04472450744129,40.69366453643252,50;linewidth:5;linecolor:%23ff6600;fillcolor:%236600ff;lineopacity:0.3;fillopacity:0.8%7Ccircle:-74.04372450744129, 40.61366453643252,50;linewidth:5;linecolor:%23ff6600;fillcolor:%236600ff;lineopacity:0.3;fillopacity:0.6&apiKey=YOUR_API_KEY

Map with GeoJSON

https://maps.geoapify.com/v1/staticmap?style=osm-carto&width=600&height=400&zoom=8.8809&geometry=polygon:13.410189,52.521661, 13.410212,52.52168,13.410233,52.521696,13.410262,52.521719,13.4103,52.521748,13.40983,52.522035,13.409605,52.52219,13.409581,52.522225, 13.409504,52.522309,13.409814,52.522449,13.409941,52.522514,13.409996,52.522539,13.410126,52.522613,13.410157,52.522631,13.410212,52.522663,13.410426,52.522787, 13.410996,52.523147,13.411062,52.523187,13.41114,52.523236,13.411357,52.52337,13.411535,52.52348,13.4119,52.523714,13.411954,52.523748,13.412102,52.523856, 13.412151,52.523893,13.412333,52.523864,13.412361,52.523851,13.412682,52.5237,13.413107,52.523506,13.413528,52.52331,13.413624,52.523265,13.413681,52.523238, 13.41383,52.523169,13.413966,52.523106,13.414481,52.522865,13.414797,52.522721,13.41496,52.522645,13.415045,52.522604,13.415093,52.522582,13.415147,52.522554, 13.415192,52.522532,13.415224,52.522518,13.415258,52.5225,13.415398,52.522436,13.415814,52.522245,13.41607,52.522126,13.416128,52.522099,13.416218,52.522058, 13.41627,52.522028,13.416135,52.521899,13.416118,52.521884,13.415996,52.521772,13.415912,52.521696,13.415613,52.521419,13.415284,52.521118,13.415246,52.521083, 13.415133,52.520975,13.415035,52.520877,13.414937,52.520786,13.414817,52.52068,13.41467,52.520564,13.414578,52.520496,13.414385,52.520378,13.414082,52.520228, 13.413928,52.520152,13.413761,52.520068,13.413652,52.520021,13.41343,52.519924,13.413186,52.519816,13.41288,52.519674,13.412529,52.519263,13.412017,52.51893, 13.411686,52.518733,13.411343,52.518572,13.411223,52.518559,13.410817,52.51833,13.410648,52.518225,13.410388,52.51811,13.410068,52.517964,13.409867,52.51779, 13.40982,52.517751,13.409569,52.517537,13.409271,52.517281,13.409196,52.51722,13.409156,52.517186,13.40905,52.517092,13.408929,52.517186,13.408639,52.517296, 13.408296,52.517551,13.40829,52.517555,13.407814,52.517903;linewidth:5;linecolor:%23ff6600;linestyle:dashed;fillcolor:%236600ff;lineopacity:1;fillopacity:0.8&apiKey=YOUR_API_KEY

You can try more API options with Static Maps API Playground >>

Attribution

Map style Attributions

By default, Static Maps API adds map style attributions into the right bottom corner of the map image. But you need to care about attributions yourself when you hide the automatically added attribution.

The following attributions are required:

1. Geoapify attribution

The Free Pricing Plan requires the Geoapify attribution. The correct Geoapify attribution is:

Powered by <a href="https://www.geoapify.com/">Geoapify</a>

Geoapify paid packages include the "White label" option. So no Geoapify attribution is needed when you subscribed to Geoapify.

2. OpenStreetMap attribution

The Geoapify server generates place tiles based on OpenStreetMap data, which is licensed under ODbL 1.0. Using this service will require proper attribution:

<a href="https://www.openstreetmap.org/copyright" target="_blank">© OpenStreetMap contributors</a>

Learn more

3. OpenMapTiles attribution

We use the OpenMapTiles schema to generate map tiles (except the osm-carto map style). It requires the following attribution:

<a href="http://openmaptiles.org/" target="_blank">© OpenMapTiles</a>

Icon library attribution

You need to add an attribution to Font Awesome when you add Font Awesome map markers generated with Map Markers API. The Font Awesome icons are distributed under SIL OFL 1.1 license.

Learn more

Where to put it?

This credit needs to appear in a place that would be appropriate for the medium or means you are using. For example:

  • For interactive maps and map pictures, the credit should typically appear in the corner of the map, as commonly seen with map APIs/libraries such as Leaflet, MapLibre, OpenLayers;
  • For printed maps, the credit should appear beside a map if that's where other such credits appear, and/or in "acknowledgments" section of the publication.

Pricing

We calculate the cost for Geoapify API calls in credits. Credits help us make our Pricing Plans flexible, universal, and simple to understand.

We offer a Free pricing plan with 3,000 credits per day. Start using our API for free and with no commitment. When you need more than the free plan offers, subscribe to one of our paid plans.

We use the following rules to calculate your Static Maps API usage fee:

Rule Cost in credits Example
Request cost 1 static map request cost is 1 credit
Map tiles cost NUMBER_OF_MAP_TILES / 4 The 1200x600px is about 15-20 map tiles, which is 4-5 credits
Map Markers cost 1 map marker is 1 credit A map with 4 markers costs additional 4 credits

Examples

An 800x600 px map with six markers cost 1 + (800*600)/(256*256)/4 + 6 = 1 + 2 + 6 = 9 credits.

Note! More tiles are needed when you use a perspective view for a map. Therefore, the number of tiles will increase.