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.

Getting 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 Specification

Here is the Static Maps API URL form:


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


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

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

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

NOTE! For each Static Maps API call, you need to specify the center or area of the map.

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.

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)