Map Marker Icon API - Custom Map Icons as PNG

Generate beautiful map marker PNGs for Leaflet, MapLibre, Google Maps, and more

Map Marker Icon API lets you create fully customizable map marker icons using simple URL parameters. Generate PNG marker images with custom colors, sizes, text or icon content, and more — no design skills needed.

Use the generated icons in Leaflet, MapLibre GL, Google Maps, OpenLayers, or embed them into static images with the Static Maps API. Whether you're building a POI map, store locator, or delivery dashboard, the API helps you create clean, branded visuals.

Choose from Material or Font Awesome icons, customize styles, colors, shadows, and more. Use icons via URL or download them — attribution is required on the free plan.

Try in Playground

Documentation

Features and Capabilities

Customizable Marker Styles

The Map Marker Icon API lets you choose from multiple marker styles to match your map’s purpose and design. Available styles include:

• Material Design — a clean, modern pin-style icon
• Font Awesome — shaped like the classic map marker with rich icon options
• Circle — simple, round map marker icons ideal for category or status indicators
• Plain — displays icon or text without any background shape

You can fully customize each marker with background color (color), content color (contentColor), border (strokeColor), and shadow (shadowColor). This flexibility helps you create consistent, branded map marker PNGs for any use case.

Icon or Text Content

Use either an icon or text as the marker’s inner content:

• Display symbols from the Material Design or Font Awesome v6 icon sets
• Or replace the icon with a single character or number using the text parameter

You can also control the inner content size (contentSize) and color (contentColor) independently from the background.

Custom Icon Size and Content Size

You can control the overall size of the map marker icon using the size parameter, which sets the full height of the PNG image in pixels. Additionally, the contentSize parameter lets you independently adjust the size of the icon or text displayed inside the marker.

This gives you full control over the proportions of the marker — whether you want a compact icon for dense maps or a large, eye-catching marker for key locations.

Example:

• size=64 sets the full marker height to 64 pixels
• contentSize=32 makes the inner icon 32 pixels tall

This flexibility allows you to match different zoom levels, styles, and device resolutions with precision.

Dynamic URL-Based Generation

No build process or image editor needed — just construct a URL with the desired parameters. The API returns a ready-to-use marker PNG. You can use icons dynamically in your app or save them locally for reuse.

Example URL:

https://api.geoapify.com/v2/icon/?type=material&color=%23ffd150&size=80&icon=landmark&iconType=awesome&contentSize=28&contentColor=%234f4f4f&apiKey=YOUR_API_KEY

Retina-Ready PNG Output

The Map Marker Icon API generates high-quality PNG images, optimized for both standard and high-resolution (retina) displays. To create retina-ready icons, simply add the scaleFactor=2 parameter to your API request.

This ensures that your map marker PNGs look sharp and crisp on all screens — whether they’re used in a web app, mobile app, or desktop interface.

Example (2× retina icon):

https://api.geoapify.com/v2/icon/?type=awesome&color=%23ff5050&size=80&icon=paw&contentSize=35&contentColor=%23294685&scaleFactor=2&apiKey=YOUR_API_KEY

You can use these icons directly via URL or download and embed them into your application — ideal for modern, pixel-perfect maps.

Works with All Major Map Libraries

The Map Marker Icon API is compatible with all popular JavaScript mapping libraries. You can use the generated map marker PNGs directly as custom icons:

• Leaflet – Use L.icon() and L.marker() to display custom icons.
• MapLibre GL – Create an HTML element and use it with new maplibregl.Marker().
• Google Maps – Set the icon property when creating a google.maps.Marker.
• OpenLayers – Use ol.style.Icon for adding custom image markers to vector layers.

Each map marker icon is designed with correct anchor points, so it integrates seamlessly without needing manual adjustments.

Free to Use with Attribution

You can use the Map Marker Icon API for free under the Geoapify Free Plan — all you need to do is include proper attribution. The generated map marker PNGs can be used directly via URL or downloaded and included in your projects without any additional restrictions from Geoapify.

The icons are based on open-source libraries and come with the following attribution requirements:

• Geoapify Attribution
  If you're on the Free Plan (allows you generating up to 3000 icons / day for Free), you must display:
  The map marker icons are generated with Geoapify.
  Paid plans with the White Label option remove this requirement.

• Font Awesome Attribution
  If you use Font Awesome icons (iconType=awesome), attribution is required under the OFL 1.1. Attribution is not strictly required as the API is generating PNGs, but it’s good practice to acknowledge the source of the artwork.

• Material Design Attribution
  Material icons are licensed under the Apache License 2.0 and do not require attribution.

This means you can generate icons dynamically or download and bundle them with your app — even on the free plan — as long as the attribution terms are followed.

Code Examples: Using Marker PNGs in Map Libraries

The Map Marker Icon API generates marker icons with a soft drop shadow by default. This shadow adds a few pixels below the icon, which helps with visibility but can affect how the marker aligns on the map.

To ensure proper placement, you may need to adjust anchor points or positioning depending on the mapping library:

• In Leaflet, set iconAnchor slightly above the bottom of the image.
• In MapLibre GL or Mapbox GL, you can offset the icon using CSS or padding.
• In Google Maps, use the anchor property in the icon config to align the visible tip of the marker correctly.
• In OpenLayers, use the anchor property in ol.style.Icon.

You can preview your marker icons in the Marker Icon Playground, which also shows the image dimensions and the shadow offset helping you determine the correct anchor values for your map library.

If you prefer a flat icon with no shadow, add the noShadow parameter to your API request:

https://api.geoapify.com/v2/icon/?type=awesome&color=%23ff50bb&size=40&icon=tree&contentSize=18&contentColor=%2334811a&noShadow&noWhiteCircle&scaleFactor=2&apiKey=YOUR_API_KEY

Now let’s look at examples for using map marker PNGs in each of the most popular mapping libraries.

Leaflet Custom Marker

To use a custom map marker in Leaflet, generate the icon with the Geoapify Marker Icon API and assign it using L.icon(). Leaflet allows you to control how the icon is positioned on the map with iconAnchor and how popups are displayed with popupAnchor.

In this example:

• size=60 in the URL defines the marker height without shadow.
• The default shadow adds 6 extra pixels to the bottom, so the total image height becomes 66 pixels.
• iconSize: [45, 66] matches the actual image dimensions (width × height).
• iconAnchor: [22.5, 60] places the anchor point at the bottom center of the visible marker (excluding the shadow).
• popupAnchor: [0, -62] makes the popup open just above the top of the icon.

The marker uses a Font Awesome "paw" icon, custom background and icon colors, and is retina-ready via scaleFactor=2.

const markerIcon = L.icon({
  iconUrl: `https://api.geoapify.com/v2/icon/?type=awesome&color=%23ffc3e8&size=60&icon=paw&contentSize=29&contentColor=%2334811a&noWhiteCircle&scaleFactor=2&apiKey=${myAPIKey}`,
  iconSize: [45, 66],
  iconAnchor: [22.5, 60],
  popupAnchor: [0, -62]
});

const zooMarkerPopup = L.popup().setContent("This is Munich Zoo");

const zooMarker = L.marker([48.096980, 11.555466], {
  icon: markerIcon
}).addTo(map).bindPopup(zooMarkerPopup);

Try this example live on JSFiddle →

MapLibre GL Custom Marker

This example demonstrates how to add a custom marker generated by the Geoapify Marker Icon API using a DOM element. The icon includes a shadow, and the popup is positioned above the visible part of the marker.

In this case:

• size=60 in the URL defines the height of the icon (excluding shadow).
• The full image height including shadow is 66px — so the icon size is 60px and the shadow adds 6px.
• iconWidth is the width of the PNG (e.g., 45px).
• The marker is offset vertically by 6px (66px - 60px) to visually pin it to the bottom tip of the icon.
• The popup is offset to appear just above the actual icon (ignoring the shadow area).

const markerIconSize = {
  iconWidth: 45,
  iconHeight: 60,
  iconHeightWithShadow: 66,
}

const el = document.createElement('div');
el.className = 'marker';
el.style.backgroundImage = `url(https://api.geoapify.com/v2/icon/?type=awesome&color=%23c3e2ff&size=60&icon=monument&contentSize=25&contentColor=%232b2b2b&noWhiteCircle&scaleFactor=2&apiKey=${myAPIKey})`;
el.style.backgroundSize = 'contain';
el.style.backgroundRepeat = 'no-repeat';
el.style.width = `${markerIconSize.iconWidth}px`;
el.style.height = `${markerIconSize.iconHeightWithShadow}px`;

new maplibregl.Marker({
  element: el,
  anchor: 'bottom',
  offset: [0, markerIconSize.iconHeightWithShadow - markerIconSize.iconHeight]
})
  .setLngLat(pinCoords)
  .setPopup(
    new maplibregl.Popup({
      offset: { bottom: [0, -markerIconSize.iconHeight] }
    }).setHTML("Statue of Liberty")
  )
  .addTo(map);

Try this example live on JSFiddle →

Google Maps (AdvancedMarkerElement with Geoapify PNG Icon)

This example shows how to use a Geoapify Marker Icon with the newer AdvancedMarkerElement from the Google Maps JavaScript API. We use a retina PNG marker, align it to the map coordinate, and show a popup on click.

• The marker icon has a defined size of 60px in the URL and a 6px shadow added automatically.
• We adjust the icon using transform: translateY(-6px) to align it correctly on the map.
• The popup (InfoWindow) is offset by -60px to appear above the visible icon.

const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

const myAPIKey = "YOUR_API_KEY";

const map = new Map(document.getElementById("map"), {
    zoom: 10,
    center: { lat: 51.5073371, lng: -0.1276495 }, // London
});

const customMarkerIcon = document.createElement("img");
customMarkerIcon.src = `https://api.geoapify.com/v2/icon/?type=awesome&color=%23c3e2ff&size=60&icon=monument&contentSize=25&contentColor=%232b2b2b&noWhiteCircle&scaleFactor=2&apiKey=${myAPIKey}`;
customMarkerIcon.style.width = "45px";
customMarkerIcon.style.height = "66px";
customMarkerIcon.style.transform = "translateY(-6px)`;

const customMarker = new AdvancedMarkerElement({
    map,
    position: { lat: 51.5073371, lng: -0.1276495 },
    content: customMarkerIcon,
    title: "A marker using a custom PNG image",
});

const infoWindow = new google.maps.InfoWindow({
    content: "City of London",
    pixelOffset: new google.maps.Size(0, -60), // move popup above icon
});

customMarkerIcon.addEventListener("click", () => {
    infoWindow.open({
    anchor: customMarker,
    map,
    });
});

This approach ensures the marker aligns precisely and remains visually crisp on retina displays. Let me know if you'd like to add a variation with text-only markers or label icons next!

OpenLayers Example – Custom Marker and Popup

This example shows how to add a custom map marker PNG to OpenLayers using the Geoapify Marker Icon API, and position a popup above it.

• The marker icon size is set to 60 in the API URL.
• The shadow adds 6px, so the full image height becomes 66px.
• The anchor aligns the marker at the visible bottom (excluding shadow): anchor: [0.5, 60 / 66]
• The popup is positioned 8px above the icon top: offset: [0, -(60 + 8)]

const markerCoords = ol.proj.fromLonLat([2.2945, 48.85825]); // Eiffel Tower

const marker = new ol.Feature({
    geometry: new ol.geom.Point(markerCoords),
    name: 'Eiffel Tower',
});

marker.setStyle(new ol.style.Style({
    image: new ol.style.Icon({
    src: `https://api.geoapify.com/v2/icon/?type=awesome&color=%23fcd3b2&size=60&icon=monument&contentSize=25&contentColor=%232b2b2b&noWhiteCircle&scaleFactor=2&apiKey=${myAPIKey}`,
    width: 45,
    height: 66, // PNG image size: width × height
    anchor: [0.5, 60/66],  // Bottom-center, adjusted for shadow
    anchorXUnits: 'fraction',
    anchorYUnits: 'fraction'
    })
}));

const vectorLayer = new ol.layer.Vector({
    source: new ol.source.Vector({
    features: [marker],
    }),
});

map.addLayer(vectorLayer);

    
// Create popup element
const popupElement = document.createElement('div');
popupElement.className = 'ol-popup';
popupElement.innerHTML = 'Eiffel Tower';
document.body.appendChild(popupElement);

const overlay = new ol.Overlay({
    element: popupElement,
    positioning: 'bottom-center',
    stopEvent: false,
    offset: [0, -(60 + 8 /* tooltip size */ )], // move above the marker
});

map.addOverlay(overlay);

// Show popup on click
map.on('click', function (event) {
    map.forEachFeatureAtPixel(event.pixel, function (feature) {
    if (feature === marker) {
        overlay.setPosition(markerCoords);
    }
    });
});

Try it on JSFiddle →

Pricing and Licensing

The Map Marker Icon API is built on top of open-source technologies — including Material Design Icons and Font Awesome — and we follow the same spirit of openness.

You can use the API in two ways:

• Dynamic Use with API Key (Cloud Access)

  • Use icon URLs dynamically by including your Geoapify API key.
  • The Free plan offers up to 3,000 requests per day.
  • View pricing and upgrade options →

• Generate Once, Host Yourself

  • You may generate marker icons using the API and store them locally in your app or website — with no usage limits from Geoapify.

Attribution Requirements

If you use the API on the Free plan, you must include the following attribution:

"The map marker icons are generated with Geoapify"

Additionally, when you use icons from third-party libraries:

• Font Awesome Free

  • Fonts that we use for the API are licensed under the SIL Open Font License 1.1
  • No attribution is required under the SIL Open Font License 1.1 (Font Awesome Fonts). However, it's still good practice to credit the creators of the artwork, especially in open-source-friendly projects.

• Material Design Icons

  • Licensed under the Apache License 2.0
  • No attribution is required for Material Icons when used under that license

FAQ