Static Maps API
Generate map images from OpenStreetMap data, in PNG or JPEG, with one URL
A static map is a non-interactive digital image that represents a specific geographic area. It is widely used in websites, print materials, and non-interactive applications to showcase location information, routes, landmarks, and spatial data.
The Static Maps API renders OpenStreetMap data into a map image. You specify the map center or bounding box, zoom level, map style, markers to highlight points of interest, and polylines or polygons to show areas and routes, and get back a ready-to-use PNG or JPEG.
On this page
Try Static Maps API
Try our Static Maps API with Live Demo! This interactive demonstration allows you to generate a customized static map image featuring a single marker positioned at the center.
In this demo, you can experiment with parameters such as map style, address for the map center, zoom level, and adjust the map bearing and pitch to achieve your desired visual effect.
In addition, you can generate map images at double the resolution to cater to high-density Retina screens. This ensures exceptional clarity and sharpness on Retina-supported devices, delivering an enhanced visual experience.
Explore the Playground to try further API possibilities and create static maps with multiple map markers.
Please refer to our comprehensive Documentation Page for detailed information about the API options and map URL examples.
Features and Capabilities
With comprehensive features and capabilities, you can effortlessly create dynamic and visually captivating static map images. Customize your maps with various map styles, choose from multiple marker options to enhance key locations, and add polylines and polygons to visualize routes and areas.
Here are some API features we would like to highlight:
Multiple Map Markers
Our API allows you to seamlessly add multiple markers to your map, each with distinct characteristics. Choose from 9 marker shapes, icons from 7 open-source icon libraries or text, and set the size, color, outline, and one of 6 shadow styles.
Markers are drawn with the Marker Icon API, so a marker on a static map looks the same as the marker PNG on your interactive map.
Print-Quality Maps
Use the Static Maps API to generate high-resolution, print-quality map images. Our API supports popular image formats such as JPEG and PNG.
Create maps up to a resolution of 4096 x 4096 px using our standard API endpoints. Additionally, we offer the capability to accommodate even bigger sizes upon request.
Polylines and Polygons on Maps
The Static Maps API empowers you to enhance your map images by adding various geometries such as circles, rectangles, lines, and polygons.
You can customize the appearance of the geometries - specify the fill color and opacity for shapes, define stroke width, line styles, and other parameters to achieve the desired visual representation for lines and polygons.
Storing and Printing at No Extra Costs
We use OpenStreetMap for Static Maps API, so you can freely cache, store, and redistribute the maps at no extra cost.
However, providing proper attributions to OpenStreetMap and other contributors is essential. Learn more about attribution requirements on our documentation page.
Customizing Maps with Ease
With our API, you can effortlessly adjust map styles to suit your preferences or branding needs. Whether it's tweaking colors, fonts, or map elements, the possibilities are endless.
Here is an example of how to customize the 'toner' map style:
Here is the corresponding URL:
https://maps.geoapify.com/v1/staticmap?style=toner&width=600&height=400¢er=lonlat:14.431849,50.069343&zoom=12.3195&styleCustomization=water:%234d3b3b|road_label_primary:none|road_label_secondary:none|place_label_park:none|place_label_city:%23c52020;67&scaleFactor=2&apiKey=YOUR_API_KEYOur Map Playground takes customization to the next level by providing an interactive platform where you can visualize and fine-tune your map styles in real-time. Experiment with different settings and instantly preview the changes. Once you're satisfied with the look, the Playground generates the corresponding Static Maps API URL for easy integration into your projects.
To learn more about all the API parameters, visit our documentation page.
Static Maps from OpenStreetMap Data
Every static map is rendered from OpenStreetMap data. Most map styles are built on the OpenMapTiles schema; osm-carto follows the classic look of openstreetmap.org. The same styles are available for interactive map tiles, so a static image can match the interactive map in your app.
Because the data is open, you can cache, store and print the images. In return, the map needs these credits:
- © OpenStreetMap contributors: required for all styles.
- © OpenMapTiles: required for all styles except
osm-carto. - Powered by Geoapify: required on the Free plan.
Put the credits in the corner of a map picture, or beside a printed map or in the publication's acknowledgments. The attribution documentation has the exact text and links.
URL examples
Explore these static map examples showcasing various map views, print-ready configurations, and the addition of map markers. These examples serve as practical demonstrations of how you can leverage the Static Maps API to achieve your desired map visualizations.
A variety of map views
- This API call generates a static map using map center and zoom to define the area to be displayed:
https://maps.geoapify.com/v1/staticmap?style=osm-bright-smooth&width=800&height=600¢er=lonlat:-74.004158,40.722619&zoom=12.1401&apiKey=YOUR_API_KEY
- This API call returns a static map for the specified map bounds:
https://maps.geoapify.com/v1/staticmap?style=osm-bright-smooth&width=800&height=600&area=rect:-74.04472450744129,40.69366453643252,-73.98100315654642,40.72408084086641&apiKey=YOUR_API_KEY
High-resolution maps
Geoapify's Static Maps API allows you to create high-resolution images of maps. The scaleFactor parameter doubles the pixel density of the image (scaleFactor=2) for Retina screens and print media.
- Default scaleFactor:
https://maps.geoapify.com/v1/staticmap?style=toner&width=800&height=600¢er=lonlat:-0.113019,51.503962&zoom=15.0858&apiKey=YOUR_API_KEY
- scaleFactor = 2:
https://maps.geoapify.com/v1/staticmap?style=toner&scaleFactor=2&width=800&height=600¢er=lonlat:-0.113019,51.503962&zoom=15.0858&apiKey=YOUR_API_KEY
By default, the scale factor can be 1 or 2. Bigger values are possible upon request. Please email us for more information on this.
Adding map markers
You can mark multiple locations on your static map using the marker parameter. Each marker can have a custom icon, color, size, and style. Our Map Marker Icon API lets you generate rich and visually distinct markers.
Icons come from seven open-source icon libraries. Use the icontype option to choose the library of the icon:
| Library | icontype |
|---|---|
| Material Icons | material |
| Material Symbols, Outlined and Rounded | material-symbols, material-symbols-rounded |
| Font Awesome 6 Free | awesome |
| Lucide | lucide |
| Tabler Icons | tabler |
| Phosphor Icons | phosphor |
| Material Design Icons | mdi |
These marker options control the shape, outline, and shadow:
| Option | Values |
|---|---|
type | material, awesome, circle, plain, and the library pin shapes tabler, phosphor, lucide, material-symbols, material-symbols-rounded |
strokewidth, strokecolor | Opaque outline from 0 to 10 px, at most marker size / 6, and its color |
shadowtype, shadowcolor | Shadow style ellipse, ellipse-dark, ellipse-soft, floating, drop, or glow, and its color |
When you omit icontype, the library follows the shape, as in the Marker Icon API: material for material, circle, and plain markers, awesome for awesome markers, and the library of the same name for the library pin shapes.
Here's an example with five markers in Chicago: Tabler, Phosphor, Material Symbols, and Lucide pins and a circle, with white outlines and drop, glow, and floating shadows:
https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=1000&height=600¢er=lonlat:-87.6356,41.8812&zoom=14.35&marker=lonlat:-87.623713,41.879584;type:tabler;icon:building-bank;color:%236a1b9a;size:56;contentsize:24;shadowtype:drop;strokewidth:3;strokecolor:%23ffffff;contentcolor:%23ffffff;whitecircle:no|lonlat:-87.622554,41.882702;type:phosphor;icon:tree;color:%232e7d32;size:56;contentsize:24;shadowtype:glow;shadowcolor:%232e7d32;contentcolor:%23ffffff;whitecircle:no|lonlat:-87.640302,41.878691;type:material-symbols;icon:train;color:%231565c0;size:56;contentsize:24;shadowtype:drop;strokewidth:3;strokecolor:%23ffffff;contentcolor:%23ffffff;whitecircle:no|lonlat:-87.62683,41.880695;type:lucide;icon:hotel;color:%23c2185b;size:56;contentsize:24;shadowtype:floating;contentcolor:%23ffffff;whitecircle:no|lonlat:-87.648021,41.884184;type:circle;icontype:material;icon:restaurant;color:%23d55e00;size:48;contentsize:24;shadowtype:drop;contentcolor:%23ffffff;whitecircle:no&scaleFactor=2&format=png&apiKey=YOUR_API_KEYTo find the marker string for a style you designed with the Marker Icon API, read the Icon-Marker-Style response header of the icon request: it contains the same marker options, ready to be prefixed with lonlat:. See the documentation for all marker options and the how-to Add Markers to a Static Map.
Add a geometry
You can add one geometry or multiple geometries to the map - circles, rectangles, polygons, and other shapes. Here is an example of a URL with a polygon:
https://maps.geoapify.com/v1/staticmap?style=positron&width=800&height=600&geometry=polygon:2.303309440612793,48.87913539780315,2.305106520652771,48.87817579776886,2.305160164833069,48.87820049358877,2.3049724102020264,48.87939646227402,2.3049402236938477,48.87945290846696,2.303309440612793,48.87913539780315;fillcolor:%23ff1234&apiKey=YOUR_API_KEYAdd a GeoJSON
The following Static Map URL example shows how to add a geometry as a GeoJSON:
https://maps.geoapify.com/v1/staticmap?style=positron&width=800&height=600&geojson=%7B%22type%22%3A%22FeatureCollection%22%2C%22features%22%3A%5B%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22linecolor%22%3A%22%23555555%22%2C%22linewidth%22%3A2%2C%22lineopacity%22%3A1%2C%22fillcolor%22%3A%22%235873f9%22%2C%22fillopacity%22%3A0.5%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B2.303309440612793%2C48.87913539780315%5D%2C%5B2.305106520652771%2C48.87817579776886%5D%2C%5B2.305160164833069%2C48.87820049358877%5D%2C%5B2.3049724102020264%2C48.87939646227402%5D%2C%5B2.3049402236938477%2C48.87945290846696%5D%2C%5B2.303309440612793%2C48.87913539780315%5D%5D%5D%7D%7D%5D%7D&apiKey=YOUR_API_KEYLong routes and many markers: POST requests
URLs are limited to 2,048 characters, so a long route geometry or dozens of markers may not fit into a GET request. For these cases, the Static Maps API also accepts a POST request with a JSON body that holds the same parameters: markers, geometries and GeoJSON. See POST requests in the documentation.
Change Map Style
Customizes specific elements of the map style. Each customization is separated by a pipe (|) character.
https://maps.geoapify.com/v1/staticmap?style=klokantech-basic&width=800&height=600¢er=lonlat:-21.875423,64.135571&zoom=9.5335&styleCustomization=landcover_grass:%2378993f|water:%23899ba8|place_label_other:21|place_label_city:30&apiKey=YOUR_API_KEYIn this example:
landcover_grassis set to color #78993f.wateris set to color #899ba8.place_label_otherandplace_label_cityare customized with undefined values and specific font sizes (21 for "place_label_other" and 30 for "place_label_city").
Getting Started
Step 1: Obtain your API Key
- To begin using the Geoapify API, start by registering an account on MyProjects Geoapify.
- Create a new project and obtain your unique API Key, which will be necessary for API access.
For detailed guidance on Geoapify projects and API keys, refer to the comprehensive information available on the Getting Started page.
Step 2: Generate the Static Map URL
- Utilize the Static Map Playground to generate the map URL for your desired configuration effortlessly.
- You can define the map view within the Playground and include markers as needed. The Marker Icon API can assist you in generating the markers to be displayed on the map.
Step 3: Embed the Map as an Image, HTML, or CSS
- The Playground conveniently provides the map URL and the corresponding code for embedding the map using HTML or CSS.
- Copy and paste the provided code to integrate the map into your application or website seamlessly.
With these three steps, you can efficiently generate static map images and seamlessly embed them into your projects. Enjoy the ease and flexibility of the Static Maps API to enhance your mapping capabilities.
Pricing
The cost of a static map in credits depends on its size and the number of markers:
| Rule | Cost in credits |
|---|---|
| Request | 1 credit per static map |
| Map tiles | number of map tiles ÷ 4 |
| Map markers | 1 credit per marker |
For example, an 800 x 600 px map with six markers costs 1 + (800 × 600) / (256 × 256) / 4 + 6 = 1 + 2 + 6 = 9 credits. A perspective view (pitch) needs more map tiles, so it costs more. Use the Credits Calculator to estimate your usage, and see Static Maps pricing in the documentation.
Geoapify implements a Freemium pricing model, enabling you to start for free and scale as your needs grow. The Free pricing plan grants 3,000 credits per day, allowing you to evaluate our services without any cost.
Guides
These guides show how to build static map URLs and POST requests, with ready-to-run examples.
Create the map image
Set the map view, size and style, then add markers.
- Create a static map imageBeginner5 min
- Add markers to a static mapBeginner5 min
Draw on the map
Show a route or an area with a POST request.
- Draw routes and areas on a static mapIntermediate10 min
FAQ
What are Static Maps?
A static map is a digital image of a map that represents a specific geographic area. Unlike interactive maps, static maps do not offer real-time data or interactive features like panning or zooming. They are commonly used in websites, print materials, and non-interactive applications to display location information, routes, landmarks, and other spatial data.
How can I generate static maps?
You can generate static maps using the Static Maps API by Geoapify. The API allows you to specify parameters such as map center, zoom level, map style, markers, and other elements to customize the appearance and content of the map. Build a URL in the Static Maps Playground or start with the quick start guide.
What image formats are supported for static maps?
Image formats supported for Geoapify's static maps include PNG (Portable Network Graphics) and JPEG (Joint Photographic Experts Group). These formats provide a good balance between image quality and file size, making them suitable for embedding static maps in websites, applications, or printing.
Can I store and cache static maps?
Yes, Geoapify's terms allow storing and caching static maps. This allows you to minimize API requests and improve performance by serving the cached map images. Keep the required attribution with the image.
What is the maximal map image size I can generate with the Static Maps API?
The maximal map image size that can be generated with the Static Maps API is 4096x4096 pixels for the standard API endpoints. Geoapify offers larger sizes upon request. Contact us if you need bigger map pictures.
Which marker styles can I use on a static map?
Each marker in the marker parameter can use one of 9 shapes (material, awesome, circle, plain, and the tabler, phosphor, lucide, material-symbols, and material-symbols-rounded pins), an icon from 7 libraries selected with icontype or text, an outline (strokewidth, strokecolor), and a shadow style (shadowtype: ellipse, ellipse-dark, ellipse-soft, floating, drop, or glow). See the marker options and the Marker Icon API.
Is the Static Maps API based on OpenStreetMap?
Yes. The map images are rendered from OpenStreetMap data. Most map styles use the OpenMapTiles schema; osm-carto follows the classic openstreetmap.org look. Credit OpenStreetMap contributors, OpenMapTiles (except osm-carto) and, on the Free plan, Geoapify. See the attribution requirements.
Can I use OpenStreetMap static maps in a commercial product?
Yes. You can use static maps in commercial projects on the Free and paid plans, as long as you keep the required attribution. See the commercial-use FAQ for the plan rules.
How many credits does a static map cost?
A static map costs 1 credit per request, plus the number of map tiles divided by 4, plus 1 credit per marker. An 800 x 600 px map with six markers costs 9 credits. Estimate your usage with the Credits Calculator.
Can I use the print version of the map in commercial products? Are there additional costs?
You can use the print version of the map in commercial products without additional costs.
Can I switch off the attribution on static maps?
Switching off the attribution on static maps may be possible on specific requests for paid plans. However, if the attribution is disabled, it becomes the user's responsibility to ensure proper attribution is provided in an alternative manner. This typically involves providing attribution for the underlying mapping data, such as OpenStreetMap, through alternative means. For the correct attribution guidelines for print maps, refer to the documentation available at OpenStreetMap Attribution Guidelines.
