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

Getting Started

The Static Maps API allows you to generate static map images based on specified parameters such as location, zoom level, size, and style. In addition, the API allows adding map markers and geometries.

The Static Maps API provides flexibility in how you request and customize your maps. You can use both HTTP GET and HTTP POST requests to tailor your map images.

• Obtain Your API Key: To use the Static Maps API, you need to sign up for an API key. This key is used to authenticate your requests and track your usage. This page provides detailed instructions on how to generate an API key for Geoapify.

• Use the Static Maps API Playground To simplify the process of creating URLs and generating the necessary code, you can use our Static Maps API Playground.

• Use the API Reference: For a comprehensive list of parameters and detailed explanations, refer to the API Reference.

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.

Note! Color values for markers, geometries, and style customization must be URL-encoded.

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

Polyline5

Polyline6

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"}

Map Style Customization

The Static Maps API allows you to customize the style of vector maps (all map styles except "osm-carto"). This powerful feature enables you to tailor the appearance of your maps to better fit your project's needs. Here are the customization options available:

1. Hide Layers: You can choose to hide specific layers that you do not want to display on your map.
2. Change Colors: Customize the colors for fill, line, and text layers to match your desired aesthetic.
3. Change Line Width: Adjust the width of line layers to emphasize certain features or reduce visual clutter.
4. Change Text Size: Modify the size of text layers to improve readability or fit your design.

The customization is done through the styleCustomization parameter, which uses a |-separated format to specify customizations for each layer. The format is as follows:

layer:color;size|layer:color;size|layer:none

Example Customizations

• Change the Color and Size of Layers: To change the color of water bodies to blue with a size of 3, and to change the color of roads to grey with a size of 2:

  styleCustomization=water:blue|roads:grey;20
  

  Copy

• Hide a Layer: To hide the buildings layer:

  styleCustomization=buildings:none
  

  Copy

Important Note

Color values for style customizations must be URL-encoded.

Interactive Playground

The list of available layers can vary depending on the chosen map style. To make the customization process easier, we provide an easy-to-use Playground. This interactive tool displays the available layers and allows you to edit them in a visual and intuitive way.

By leveraging these customization options, you can create highly personalized and visually appealing map images that perfectly match your project's requirements.

Embedding Static Map as 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)

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

Map with Customized Style

https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=600&height=400&center=lonlat:-122.336886,47.60948&zoom=17.3926&pitch=11.5&styleCustomization=highway-minor-casing:%232e5e39;17|highway-secondary-tertiary-casing:%232e5e39;20|highway-primary-casing:%232e5e39;26|highway-minor:%2304832c;12|highway-secondary-tertiary:%2304832c;15|highway-primary:%2304832c;21|poi-level-3:undefined;15|highway-name-major:%23dcf8d8;16|place-other:none&bearing=58.4&scaleFactor=2&apiKey=YOUR_API_KEY

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

HTTP Post Requests

The Static Maps API allows you to generate static map images by specifying parameters such as location, zoom level, size, and style. Typically, these parameters are defined in the URL when using HTTP GET requests. However, URLs have a maximum length of 2,048 characters, which limits the complexity of the map configurations you can create with HTTP GET requests.

To overcome this limitation and enable the creation of static maps with complex geometries, the Static Maps API also supports HTTP POST requests. With HTTP POST, you can include all the necessary parameters in the request body, allowing for much more detailed and intricate map customizations without the constraints of URL length.

Parameters Differences Between GET and POST Requests

The API has similar parameters for both HTTP GET and POST requests. However, some multi-value parameters in GET requests are split into separate parameters in POST requests. The table below lists the parameters that differ between the regular Static Map API (GET) and the POST request format:

Detailed Description of geometries Parameter for Static Maps API

The geometries parameter allows you to add various geometric shapes to your static maps. This parameter supports multiple types of geometries, each with specific attributes for customization. Below is a detailed description of the supported geometries and their parameters.

• geometries: An array of geometry objects, each specifying the type and properties of the shape to be drawn on the map. This array can include any combination of the below geometry types.

General Geometry Attributes

All geometries share some common attributes for styling, which are defined in the joiGeometryBase object:

• linecolor: The color of the line.
• lineopacity: The opacity of the line.
• linewidth: The width of the line.
• linestyle: The style of the line, which can be solid, dotted, dashed, or longdash.
• fillcolor: The fill color for the shape.
• fillopacity: The opacity of the fill color.

Supported Geometry Types

1. Circle (circle)

   {
     "type": "circle",
     "linecolor": "#000000",
     "lineopacity": 1,
     "linewidth": 1,
     "linestyle": "solid",
     "fillcolor": "#000000",
     "fillopacity": 1,
     "value": {
       "lat": <latitude>,
       "lon": <longitude>,
       "radius": <radius>
     }
   }
   

   Copy
   • lat: Latitude of the circle's center.
   • lon: Longitude of the circle's center.
   • radius: Radius of the circle.

2. Rectangle (rect)

   {
     "type": "rect",
     "linecolor": "#000000",
     "lineopacity": 1,
     "linewidth": 1,
     "linestyle": "solid",
     "fillcolor": "#000000",
     "fillopacity": 1,
     "value": {
       "lat1": <latitude1>,
       "lon1": <longitude1>,
       "lat2": <latitude2>,
       "lon2": <longitude2>
     }
   }
   

   Copy
   • lat1: Latitude of the first corner.
   • lon1: Longitude of the first corner.
   • lat2: Latitude of the opposite corner.
   • lon2: Longitude of the opposite corner.

3. Polyline (polyline)

   {
     "type": "polyline",
     "linecolor": "#000000",
     "lineopacity": 1,
     "linewidth": 1,
     "linestyle": "solid",
     "value": [
       {"lat": <latitude1>, "lon": <longitude1>},
       {"lat": <latitude2>, "lon": <longitude2>}
     ]
   }
   

   Copy
   • value: An array of coordinate objects, each with lat and lon.

4. Polyline with Precision 5 (polyline5)

   {
     "type": "polyline5",
     "linecolor": "#000000",
     "lineopacity": 1,
     "linewidth": 1,
     "linestyle": "solid",
     "value": "<encoded_polyline>"
   }
   

   Copy
   • value: An encoded polyline string with precision 5.

5. Polyline with Precision 6 (polyline6)

   {
     "type": "polyline6",
     "linecolor": "#000000",
     "lineopacity": 1,
     "linewidth": 1,
     "linestyle": "solid",
     "value": "<encoded_polyline>"
   }
   

   Copy
   • value: An encoded polyline string with precision 6.

6. Polygon (polygon)

   {
     "type": "polygon",
     "linecolor": "#000000",
     "lineopacity": 1,
     "linewidth": 1,
     "linestyle": "solid",
     "fillcolor": "#000000",
     "fillopacity": 1,
     "value": [
       {"lat": <latitude1>, "lon": <longitude1>},
       {"lat": <latitude2>, "lon": <longitude2>}
     ]
   }
   

   Copy
   • value: An array of coordinate objects, each with lat and lon.

Examples of Post Requests

Style customization and markers

Request Type: POST

URL: https://maps.geoapify.com/v1/staticmap?apiKey=YOUR_API_KEY

Request body:

{
    "style": "osm-bright",
    "scaleFactor": 2,
    "width": 600,
    "height": 400,
    "center": {
        "lat": 47.60948,
        "lon": -122.336886
    },
    "zoom": 17.3926,
    "pitch": 11.5,
    "styleCustomization": [
        {
            "layer": "highway-minor-casing",
            "color": "#2e5e39",
            "size": 17
        },
        {
            "layer": "place-other",
            "color": "none"
        }
    ],
    "bearing": 58.4,
    "markers": [
        {
            "lat": 47.60924165639446,
            "lon": -122.33647609028213,
            "color": "#ff0000",
            "size": "medium"
        }
    ]
}

Geometries

Request Type: POST

URL: https://maps.geoapify.com/v1/staticmap?apiKey=YOUR_API_KEY

Request body:

{
    "style": "osm-bright",
    "lang": "uk",
    "width": 600,
    "height": 400,
    "geometries": [
        {
            "type": "rect",
            "fillcolor": "#ff9976",
            "fillopacity": 0.6,
            "linewidth": 5,
            "linecolor": "red",
            "value": {
                "lat1": 48,
                "lon1": 12,
                "lat2": 48.5,
                "lon2": 12.5
            }
        }
    ]
}

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.