Marker Icon API

The Marker Icon API generates custom map marker icons as PNG images from URL parameters. Choose a pin, circle, or plain shape, add an icon or text, and set the size, colors, outline, and shadow. Icons come from Material Icons, Material Symbols, Font Awesome 6 Free, Lucide, Tabler Icons, Phosphor Icons, and Material Design Icons.

Here’s an example of a generated marker icon:

This API can be used for:

• Interactive maps - show places, stores, vehicles, or events with Leaflet, MapLibre GL, OpenLayers, or Google Maps
• Category marker sets - give each place category its own icon and color
• Numbered stops - label route stops or search results with text such as 1, 2, 3
• Static assets - generate markers once and store them with your application

Each response includes headers with the marker's display size and anchor point, so you can place the marker precisely without measuring the image. With scaleFactor, markers stay sharp on high-density screens.

See How to Add Markers to a Map for Leaflet, MapLibre GL, and OpenLayers integrations, or How to Add Markers to a Static Map when the output should be a PNG or JPEG map image.

Explore and test the Marker Icon API in the API Playground:

• Authentication and API key
• API reference
• Shadows and map placement
• URL examples
• Attribution
• Pricing
• API reference (V1, deprecated)

What's new in v2

• Size in pixels: size and contentSize set heights in pixels instead of preset keywords.
• More icon libraries: Font Awesome 6, Lucide, Tabler Icons, Phosphor Icons, Material Design Icons, and Material Symbols, in addition to Material Icons.
• More shapes: plain markers without a background, and map-pin shapes from the Tabler, Phosphor, Lucide, and Material Symbols libraries.
• Content color: contentColor sets the icon or text color separately from the background.
• Outlines and shadows: strokeWidth adds an opaque outline, and shadowType selects one of six shadow styles.
• Retina output: scaleFactor generates high-resolution PNGs.
• Layout headers: Icon-Width, Icon-Height, Icon-Anchor-X, and Icon-Anchor-Y return the display size and anchor, and Icon-Marker-Style returns the equivalent Static Maps marker. A HEAD request returns only the headers.

Authentication and API key

To use the Marker Icon API, you need an API key. You can register and get an API key for free in Geoapify MyProjects, without a credit card.

The Free plan includes 3000 credits per day, and each marker request costs 1 credit. For more information, see the Pricing page.

How to get the Geoapify API key

1. Register on the Geoapify MyProjects page.
2. Create a new project.
3. Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
4. Optionally, protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.

Marker URLs are usually loaded directly by the browser, for example in an <img> element or by a map library, so the API key is visible in the page. Restrict it to your website's HTTP referrers or origins. To keep the key private, generate the markers you need once on your server and serve the stored PNG files; you are free to store and reuse generated markers.

Need more help? Follow this step-by-step guide to create your first project and obtain your API key.

API Reference

The Marker Icon API generates a PNG map marker from URL parameters: a background shape, an icon or text, colors, an outline, and a shadow. Response headers return the marker's display size and anchor point, so you can place it on a map without measuring the image.

Use the image in HTML and CSS, in client-side map libraries such as Leaflet, MapLibre GL, OpenLayers, or Google Maps, or store it as a static asset. For placement details and map-library code, see Shadows and map placement and How to Add Custom Marker Icons to Leaflet, MapLibre GL, and OpenLayers Maps.

Authentication

Pass your API key as the apiKey URL parameter or in the x-api-key request header. Browsers can load a marker in an <img> element only with the apiKey URL parameter.

Generate a marker

HTTP GET https://api.geoapify.com/v2/icon?type=material&icon=home&apiKey=YOUR_API_KEY

All parameters are optional except apiKey. A request with only apiKey returns a default 42 px Material-style pin.

Request URL parameters

Shape and content

Size and resolution

Colors, outline, and shadow

Value formats:

• color accepts HEX (#ff5050 or #f50), named colors (red), rgb(255,80,80), and rgba(255,80,80,0.8). Use rgba() for semi-transparent colors. URL-encode the value: # must be sent as %23. URLSearchParams and OpenAPI clients encode it automatically.
• flag parameters are enabled when present without a value or with 1, true, or yes. noShadow, noShadow=true, and noShadow=1 are equivalent.

Icon catalogs:

Check the attribution requirements of the library you use.

Here is a request example for a 64 px orange pin with a white outline, a drop shadow, and double resolution:

curl -o home-marker.png "https://api.geoapify.com/v2/icon?type=material&icon=home&color=%23ef6c00&strokeColor=%23ffffff&strokeWidth=3&shadowType=drop&size=64&contentSize=26&scaleFactor=2&apiKey=YOUR_API_KEY"

Response

The response is a image/png marker. These response headers describe its layout:

The headers are exposed to browser scripts through CORS, so fetch() can read them.

Example: type=material&size=60&scaleFactor=2 returns an 85 × 130 px PNG with these headers:

Icon-Width: 42.5
Icon-Height: 65
Icon-Anchor-X: 21.25
Icon-Anchor-Y: 58.92

The marker is 60 px high plus a 5 px shadow. Display it at 42.5 × 65 CSS pixels (85 / 2 × 130 / 2), with the anchor 21.25 px from the left edge and 58.92 px from the top edge.

Get only the layout headers

HTTP HEAD https://api.geoapify.com/v2/icon?PARAMS

A HEAD request with the same parameters returns the Icon-* headers without the image. Use it to size and anchor a marker before displaying it:

curl -I "https://api.geoapify.com/v2/icon?type=material&size=60&scaleFactor=2&apiKey=YOUR_API_KEY"

Place the marker on a map

Display the PNG at Icon-Width × Icon-Height and put the Icon-Anchor-X, Icon-Anchor-Y point on the location. The anchor is not at the bottom of the image, because the shadow is drawn below the marker. See Shadows and map placement for layout tables and Leaflet, MapLibre GL, and OpenLayers code samples.

Errors

Errors are returned as JSON with an HTTP status code:

Here is an error example:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "size should be a positive number"
}

Caching

Generated markers can be cached and stored: responses include Cache-Control: public, max-age=3600. Because one marker style needs only one request, generate each style once and reuse it rather than requesting the same image for every map point.

OpenAPI specification

The Marker Icon API OpenAPI specification describes all parameters, response headers, and errors. You can import it into API clients, code generators, and AI coding agents.

Shadows and map placement

A map marker must touch the map at one exact point, its anchor. For a pin, that is the tip; for a circle, usually its center. The Marker Icon API draws a shadow under most markers, so the returned image is larger than the size you request, and the anchor is not at the bottom edge of the image. This page explains how the shadow changes the image, how to read the exact size and anchor from the response headers, and how to apply them in Leaflet, MapLibre GL, and OpenLayers.

The image is bigger than the requested size

size sets the height of the marker shape only. The shadow is drawn below the shape and makes the image taller. Some shadow styles also make it wider:

• With the default ellipse shadow, a type=awesome&size=42 marker is a 32 × 47 px image: 42 px for the pin and 5 px for the shadow.
• The pin tip is 4.3 px above the image bottom, inside the shadow.
• The image width depends on the shape: pins are narrower than they are high, and circles are as wide as they are high.

Leaflet, MapLibre GL, and OpenLayers anchor an image at its center by default, and bottom-center is the usual manual fix for pins. If you anchor this marker at its bottom center, the pin tip floats about 5 px above the location, and the error grows with the marker size:

Use noShadow when you prefer simple arithmetic: the image is then exactly size px high and the pin tip is at the bottom. In all other cases, read the layout from the response headers.

Layout headers

Every marker response includes its layout in CSS pixels:

The values can be fractional and they depend on every shape parameter, including type, size, strokeWidth, shadowType, noShadow, and scaleFactor. Because the PNG is rounded to whole pixels at each scaleFactor, the anchor changes slightly between resolutions, for example 42.74 at scaleFactor=1 and 42.49 at scaleFactor=2 for the same pin. Read the headers for the exact URL you display.

Get the layout with a HEAD request

A HEAD request returns the headers without the image. Use it to inspect a marker or to compute its layout once, for example in a build script:

curl -I "https://api.geoapify.com/v2/icon/?type=awesome&icon=landmark&color=%23ff005c&size=42&contentSize=18&scaleFactor=2&apiKey=YOUR_API_KEY"

Response headers (reduced):

HTTP/2 200
content-type: image/png
cache-control: public, max-age=3600
icon-width: 32
icon-height: 47
icon-anchor-x: 16
icon-anchor-y: 42.49497841631692
icon-marker-style: type:awesome;size:42;icontype:awesome;icon:landmark;color:#ff005c;contentsize:18
access-control-expose-headers: Icon-Width, Icon-Height, Icon-Anchor-X, Icon-Anchor-Y, Icon-Marker-Style

The PNG for this URL is 64 × 94 px. Divided by scaleFactor=2, it is displayed at 32 × 47 CSS px, with the pin tip at [16, 42.49].

A HEAD request is a full API request. In a browser, request the image once with fetch() and read the headers from the same response, as in the code samples below. That costs one request per marker style instead of two. The headers are exposed through CORS, so browser scripts can read them.

To use Icon-Marker-Style in a Static Maps API request, prefix it with the location and URL-encode # as %23:

marker=lonlat:-77.0353,38.8895;type:awesome;size:42;icontype:awesome;icon:landmark;color:%23ff005c;contentsize:18

Marker size and anchor by type

Display size and anchor in CSS pixels for each marker type with the default shadow. Anchors are rounded to one decimal place.

Type	Image (size=42)	size=32	size=42	size=64
material		23 × 35, anchor 11.5, 32.1	30 × 46, anchor 15, 42	45 × 70, anchor 22.5, 63.5
awesome		25 × 36, anchor 12.5, 32.9	32 × 47, anchor 16, 42.7	49 × 71, anchor 24.5, 64.4
tabler		30 × 37, anchor 15, 33.5	39 × 49, anchor 19.5, 43.8	59 × 75, anchor 29.5, 66.5
phosphor		26 × 37, anchor 13, 33.2	34 × 48, anchor 17, 43.5	51 × 73, anchor 25.5, 65.9
lucide		26 × 36, anchor 13, 33	35 × 48, anchor 17.5, 43.8	52 × 73, anchor 26, 66
material-symbols		26 × 36, anchor 13, 33	35 × 48, anchor 17.5, 43.8	52 × 73, anchor 26, 66
material-symbols-rounded		27 × 37, anchor 13.5, 33.2	35 × 48, anchor 17.5, 43.4	54 × 74, anchor 27, 66.4
circle		32 × 32, anchor 16, 16	42 × 42, anchor 21, 21	64 × 64, anchor 32, 32
plain		32 × 32, anchor 16, 16	42 × 42, anchor 21, 21	64 × 64, anchor 32, 32

• Pins add a shadow of 3–11 px below the shape, depending on the type and size. The anchor is the pin tip, close to size but not equal to it.
• circle markers have no shadow unless you set shadowType, and plain markers never have one. Without a shadow, the image is size × size and the anchor is the center.
• With noShadow, every pin is exactly size px high and its anchor is [width / 2, size].

Shadow types

shadowType changes both the look and the layout. The table shows size=42 markers:

Shadow	material pin	Size and anchor	circle	Size and anchor
ellipse (default)		30 × 46, anchor 15, 42		43 × 50, anchor 21.5, 44
ellipse-dark		30 × 47, anchor 15, 42.3		43 × 50, anchor 21.5, 43
ellipse-soft		44 × 57, anchor 22, 49.6		63 × 65, anchor 31.5, 53
floating		30 × 54, anchor 15, 48.6		43 × 60, anchor 21.5, 52
drop		46 × 62, anchor 23, 49.3		65 × 71, anchor 32.5, 39
glow		43 × 54, anchor 21.5, 47.8		61 × 60, anchor 30.5, 30
noShadow		30 × 42, anchor 15, 42		42 × 42, anchor 21, 21

• Ground shadows (ellipse, ellipse-dark, ellipse-soft, floating) are drawn below the marker. For a circle, the anchor moves down to the shadow, so the circle stands above the location like a pin. With floating, the marker hovers visibly above the anchor.
• drop and glow blur around the whole shape and add space on every side, so Icon-Anchor-X changes too. For a circle, the anchor stays at the circle center.
• A wider image also changes the horizontal anchor. Never assume the anchor is at width / 2 unless the shadow is symmetric.

Code samples

Each sample requests one marker style with fetch(), reads its size and anchor from the headers, and reuses the image for all locations. The locations are Washington, DC landmarks. The samples assume that a map object already exists.

The shared helper:

const markerUrl = "https://api.geoapify.com/v2/icon/?type=awesome&icon=landmark&color=%23ff005c&size=42&contentSize=18&scaleFactor=2&apiKey=YOUR_API_KEY";

const locations = [
  { name: "Lincoln Memorial", lat: 38.8893, lon: -77.0502 },
  { name: "Washington Monument", lat: 38.8895, lon: -77.0353 },
  { name: "United States Capitol", lat: 38.8899, lon: -77.0091 }
];

// Requests the marker once and reads its display size and anchor
// (CSS pixels) from the Icon-* response headers.
async function loadMarker(url) {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Marker request failed with HTTP ${response.status}`);
  }

  const header = (name) => Number(response.headers.get(name));
  const marker = {
    width: header("Icon-Width"),
    height: header("Icon-Height"),
    anchorX: header("Icon-Anchor-X"),
    anchorY: header("Icon-Anchor-Y"),
    imageUrl: URL.createObjectURL(await response.blob())
  };

  if (!(marker.width > 0 && marker.height > 0)) {
    throw new Error("The marker response has no Icon-* layout headers");
  }
  return marker;
}

Leaflet

Leaflet places iconAnchor on the location. Coordinates use [latitude, longitude] order.

const marker = await loadMarker(markerUrl);

// One icon object for every marker with this style.
const icon = L.icon({
  iconUrl: marker.imageUrl,
  iconSize: [marker.width, marker.height],
  iconAnchor: [marker.anchorX, marker.anchorY],
  // Relative to iconAnchor: open popups above the top of the pin.
  popupAnchor: [marker.width / 2 - marker.anchorX, -marker.anchorY]
});

for (const location of locations) {
  L.marker([location.lat, location.lon], { icon, alt: location.name })
    .bindPopup(location.name)
    .addTo(map);
}

MapLibre GL markers

A MapLibre Marker aligns one of nine named positions of the element with the location. None of them is the pin tip above a shadow, so align the top-left corner and shift the element by the anchor. Coordinates use [longitude, latitude] order.

const marker = await loadMarker(markerUrl);

for (const location of locations) {
  const element = document.createElement("img");
  element.src = marker.imageUrl;
  element.alt = location.name;
  element.style.width = `${marker.width}px`;
  element.style.height = `${marker.height}px`;

  new maplibregl.Marker({
    element,
    // Put the image's top-left corner on the location,
    // then shift it so the anchor point lands there instead.
    anchor: "top-left",
    offset: [-marker.anchorX, -marker.anchorY]
  })
    .setLngLat([location.lon, location.lat])
    .setPopup(new maplibregl.Popup({ offset: [0, -marker.anchorY] }).setText(location.name))
    .addTo(map);
}

MapLibre GL symbol layer

For many points, add the image once and render the points as a symbol layer. icon-offset uses the same top-left technique.

map.on("load", async () => {
  const marker = await loadMarker(markerUrl);
  const image = await map.loadImage(marker.imageUrl);

  // pixelRatio must equal the scaleFactor in the marker URL,
  // so the image is drawn at its display size.
  map.addImage("landmark-marker", image.data, { pixelRatio: 2 });

  map.addSource("landmarks", {
    type: "geojson",
    data: {
      type: "FeatureCollection",
      features: locations.map((location) => ({
        type: "Feature",
        properties: { name: location.name },
        geometry: { type: "Point", coordinates: [location.lon, location.lat] }
      }))
    }
  });

  map.addLayer({
    id: "landmarks",
    type: "symbol",
    source: "landmarks",
    layout: {
      "icon-image": "landmark-marker",
      "icon-anchor": "top-left",
      "icon-offset": [-marker.anchorX, -marker.anchorY],
      "icon-allow-overlap": true
    }
  });
});

OpenLayers

An OpenLayers Icon takes the anchor as fractions of the image size by default. Fractions are independent of scaleFactor. Convert [longitude, latitude] coordinates to the map projection with fromLonLat().

import Feature from "ol/Feature.js";
import Point from "ol/geom/Point.js";
import VectorLayer from "ol/layer/Vector.js";
import VectorSource from "ol/source/Vector.js";
import Icon from "ol/style/Icon.js";
import Style from "ol/style/Style.js";
import { fromLonLat } from "ol/proj.js";

const marker = await loadMarker(markerUrl);

const markerStyle = new Style({
  image: new Icon({
    src: marker.imageUrl,
    width: marker.width,
    height: marker.height,
    // Fractions of the displayed size, so the anchor does not depend on scaleFactor.
    anchor: [marker.anchorX / marker.width, marker.anchorY / marker.height]
  })
});

const source = new VectorSource({
  features: locations.map((location) => new Feature({
    name: location.name,
    geometry: new Point(fromLonLat([location.lon, location.lat]))
  }))
});

map.addLayer(new VectorLayer({ source, style: markerStyle }));

For a step-by-step guide with the result map, see How to Add Custom Marker Icons to Leaflet, MapLibre GL, and OpenLayers Maps.

URL Examples

Each example shows the rendered marker and its request URL. Add scaleFactor=2 for sharp markers on high-density screens. Replace YOUR_API_KEY with your API key.

Icon	Example	URL
	Default Material pin with a custom color	https://api.geoapify.com/v2/icon?type=material&color=%23ff5722&size=64&apiKey=YOUR_API_KEY
	Font Awesome pin and icon	https://api.geoapify.com/v2/icon?type=awesome&icon=coffee&color=%230099ff&size=64&contentSize=26&apiKey=YOUR_API_KEY
	Tabler pin; iconType defaults to tabler	https://api.geoapify.com/v2/icon?type=tabler&icon=coffee&color=%230b7285&size=64&contentSize=26&apiKey=YOUR_API_KEY
	Material Symbols Rounded pin and icon	https://api.geoapify.com/v2/icon?type=material-symbols-rounded&icon=restaurant&color=%23d55e00&size=64&contentSize=26&apiKey=YOUR_API_KEY
	Font Awesome pin with a Material Design Icons icon (iconType=mdi)	https://api.geoapify.com/v2/icon?type=awesome&iconType=mdi&icon=bicycle&color=%23332288&size=64&contentSize=26&apiKey=YOUR_API_KEY
	Text instead of an icon, for numbered stops	https://api.geoapify.com/v2/icon?type=material&text=12&color=%230077bb&size=64&contentSize=22&apiKey=YOUR_API_KEY
	Opaque white outline and drop shadow	https://api.geoapify.com/v2/icon?type=material&icon=home&color=%23ef6c00&strokeColor=%23ffffff&strokeWidth=3&shadowType=drop&size=64&contentSize=26&apiKey=YOUR_API_KEY
	Phosphor pin with a colored glow	https://api.geoapify.com/v2/icon?type=phosphor&icon=tree&color=%232e7d32&shadowType=glow&shadowColor=%232e7d32&size=64&contentSize=26&apiKey=YOUR_API_KEY
	Circle marker with a stroke and a floating shadow	https://api.geoapify.com/v2/icon?type=circle&icon=star&color=%23ffffff&strokeColor=%23000000&shadowType=floating&size=48&contentSize=26&apiKey=YOUR_API_KEY
	Plain icon without a background shape	https://api.geoapify.com/v2/icon?type=plain&icon=car&iconType=awesome&color=%232ecc71&size=64&contentSize=48&apiKey=YOUR_API_KEY
	Plain text without a background shape	https://api.geoapify.com/v2/icon?type=plain&text=A&color=%23e91e63&size=64&contentSize=48&apiKey=YOUR_API_KEY
	Marker without a shadow	https://api.geoapify.com/v2/icon?type=awesome&color=%23ff9800&size=64&noShadow&apiKey=YOUR_API_KEY
	White icon directly on the background, without the white circle	https://api.geoapify.com/v2/icon?type=material&icon=park&color=%232e7d32&contentColor=%23ffffff&noWhiteCircle&size=64&contentSize=30&apiKey=YOUR_API_KEY

Attribution

The Marker Icon API uses icons and pin shapes from open-source icon libraries: Material Icons and Material Symbols, Font Awesome 6 Free, Lucide, Tabler Icons, Phosphor Icons, and Material Design Icons.

Attribution requirements depend on your Geoapify plan and on the libraries you use, both through iconType and through the pin shape selected with type.

1. Geoapify attribution

If you are on a paid Geoapify plan with the "White Label" option, no Geoapify attribution is needed.

If you are using the Free Pricing Plan, you must provide Geoapify attribution.
The correct attribution is:

The map marker icons are generated with <a href="https://www.geoapify.com/">Geoapify</a>.

2. Font Awesome attribution

When you use Font Awesome icons in your markers (iconType=awesome) or the Font Awesome pin shape (type=awesome, based on the Font Awesome location-dot icon) via Marker Icon API, attribution to Font Awesome is required.

• Font Awesome Free Icons are licensed under the Creative Commons Attribution 4.0 License (CC BY 4.0).
• Font Awesome Fonts are licensed under the SIL Open Font License 1.1 (OFL 1.1).

Learn more:

• Font Awesome Free License Overview

3. Material Icons and Material Symbols

Material Icons (iconType=material, type=material) and Material Symbols (iconType=material-symbols or material-symbols-rounded, and pin shapes of the same names) are available under the Apache License 2.0. No additional attribution is required.

4. Other icon libraries

The following libraries do not require visible attribution on your map. If you redistribute the icon files, keep the library's license notice.

Pricing

Geoapify uses credits as the pricing currency.
Each API call you make consumes credits, and your total daily usage is measured as Daily API Usage.

Geoapify offers several Pricing Plans, starting with a Free Plan that includes 3000 credits per day.
You can upgrade at any time as your usage or business needs grow.

Using the Marker Icon API is simple and transparent:

• 1 API call = 1 credit.
• No additional costs for the number of icons you generate.
• You are free to store the generated icons on your side without any restrictions.
• You can also redistribute the stored icons (e.g., as part of your applications or websites) at no extra charge.

DEPRECATED: API Reference (V1)

⚠️ Important:
This version of the Marker Icon API is deprecated and will no longer receive updates.
We recommend switching to Marker Icon API v2 for new projects.

The Marker Icon API v1 was designed to generate customizable PNG marker icons for use in web projects. The generated images can be embedded into HTML, styled with CSS, or used directly in client-side mapping libraries.

Request URL

https://api.geoapify.com/v1/icon?PARAMS

Request parameters

Important notes:

• API v1 uses predefined size keywords (small, medium, etc.) instead of pixel values.
• Font Awesome integration in v1 uses the v5 icon set.
• v1 does not support contentColor, plain type, or pixel-based size control (available in v2).