Static Maps API

The Static Maps API allows developers to create map images in their applications, providing a quick and easy way to display location data without the need for a full interactive map interface. With a simple HTTP request, users can generate maps with customizable markers, zoom levels, and map styles, making it an ideal solution for displaying location-based information on websites and mobile apps.

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:

• Authentication and Geocoding API key
• API reference
• API URL Examples
• Required attribution
• Pricing

Authentication 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:

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:

Here are examples of marker definitions:

Marker	Parameters
	lonlat:-122.68573,45.51105;type:awesome;color:%231db510;size:x-large;icon:apple-alt;whitecircle:no
	lonlat:-122.68363,45.51081;type:circle;color:%23109db5;text:1;textsize:large;shadow:no
	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

Rect

Polyline

Polygon

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:

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

• OpenStreetMap Legal FAQ

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

• Font Awesome Free License

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:

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.