New in the Marker Icon API: More Icon Libraries, Pin Shapes, Outlines, Shadows, Anchors

The Geoapify Marker Icon API now draws icons from seven open-source libraries, offers five new pin shapes that match those libraries, and adds opaque outlines, six shadow styles, and response headers that tell you exactly where each marker touches the map. All of it is controlled with URL parameters on the same https://api.geoapify.com/v2/icon endpoint, and existing v2 URLs keep working. This post shows each new option as an image grid you can compare at a glance. It then explains the change developers will notice most: why a shadow moves a marker's anchor, and how the new Icon-* headers and a HEAD request fix placement in Leaflet, MapLibre GL, and OpenLayers.

Key takeaways

• Icon libraries: iconType now accepts tabler, phosphor, mdi, material-symbols, and material-symbols-rounded, on top of material, awesome, and lucide.
• Pin shapes: type=tabler, phosphor, lucide, material-symbols, and material-symbols-rounded use the map-pin shape of that library, and any shape can carry icons from any library.
• Outlines and shadows: strokeWidth adds an opaque outline; shadowType picks one of six shadow styles, with shadowColor for colored glows.
• Exact placement: Icon-Width, Icon-Height, Icon-Anchor-X, and Icon-Anchor-Y return the display size and anchor; a HEAD request returns them without the image.
• Static Maps: the same shapes, libraries, outlines, and shadows work in Static Maps marker options, and Icon-Marker-Style gives you the matching string.

What's New in the Marker Icon API?

The update adds new values to two existing parameters, three new parameters for outlines and shadows, and layout information in the response. Here is the summary:

Existing URLs are not affected. All parameters are optional except apiKey, and a request with only apiKey still returns the default 42 px Material-style pin. The full parameter list is in the Marker Icon API reference, and you can try every option in the API Playground.

If you are new to custom markers, start with our earlier guide on using custom map marker icons in Google Maps, Leaflet, and MapLibre. This post focuses on what changed.

Which Icon Libraries Can You Use?

The iconType parameter selects one of eight values backed by seven open-source icon libraries. Material Symbols comes in two styles, Outlined and Rounded:

Libraries differ in drawing style: filled or outlined, rounded or sharp, thin or heavy strokes. The grid below draws the same six place categories with each iconType on the same blue Material pin, so you can compare them directly.

Each marker in the grid comes from a URL like this one. Only iconType and icon change between cells:

https://api.geoapify.com/v2/icon?type=material&iconType=tabler&icon=coffee&color=%231565c0&contentColor=%23ffffff&noWhiteCircle&size=64&contentSize=28&scaleFactor=2&apiKey=YOUR_API_KEY

Icon names differ between libraries. A hospital, for example, may be called differently in Tabler, Phosphor, and Material Symbols. Look up the exact name in the catalog of the library you selected; the icon value accepts up to 100 letters, digits, _, or - characters.

Which Marker Shapes Are Available?

The type parameter sets the background shape, and there are now nine values:

• material (default) is a Material-style pin, and awesome is a Font Awesome-style pin.
• circle is a circle, and plain renders only the icon or text, with no background shape.
• tabler, phosphor, lucide, material-symbols, material-symbols-rounded use the map-pin shape of that icon library.

When you omit iconType, the library follows the shape: material for material, circle, and plain markers, awesome for awesome markers, and the library of the same name for the five new pin types. So type=tabler&icon=coffee draws a Tabler coffee cup on a Tabler pin without any extra parameter.

Text works on every shape: when both text and icon are set, text is used. This is the usual choice for numbered route stops or search results.

Matched Sets: One Library for Shape and Icons

Because the new pin types pick their own library by default, you get a visually consistent set with very short URLs: the pin shape and the icons come from the same library. The grid shows six categories in each of the five library-matched sets.

For example, a green Phosphor pin with a Phosphor tree:

https://api.geoapify.com/v2/icon?type=phosphor&icon=tree&color=%232e7d32&size=64&contentSize=26&scaleFactor=2&apiKey=YOUR_API_KEY

Set contentSize together with size for larger markers. When contentSize is omitted, the icon uses a fixed default size that does not grow with size.

Can You Combine a Pin Shape with Icons from Another Library?

Yes. type and iconType are independent, so any shape can carry icons from any of the eight iconType values. The documentation example puts a Material Design Icons bicycle on a Font Awesome pin:

https://api.geoapify.com/v2/icon?type=awesome&iconType=mdi&icon=bicycle&color=%23332288&size=64&contentSize=26&apiKey=YOUR_API_KEY

This is useful when you like one library's pin but another library has the icon you need, or when you add new categories to an existing Material or Font Awesome marker set without changing its look.

How Do Outlines Work?

strokeWidth adds an opaque outline around the shape. Its rules come straight from the API reference:

• Range: 0 to 10 CSS pixels, and at most size / 6.
• Constant size: the outline is drawn outside the shape, and the shape shrinks so the marker keeps its size.
• Default: when strokeWidth is omitted, the marker gets a thin semi-transparent outline.
• Color: strokeColor sets the outline color.
• Exception: outlines are ignored for type=plain.

A white outline separates a marker from a busy basemap, a dark outline helps on light or satellite tiles, and a darker shade of the fill gives a subtle, flat look.

The size / 6 limit matters for small markers. A 30 px marker allows an outline of at most 5 px, so size=30&strokeWidth=8 returns HTTP 400:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "strokeWidth should be a number between 0 and 10, and at most size / 6"
}

Which Shadow Styles Are There?

shadowType selects one of six shadow styles. Each one changes both the look and the image size:

Three related rules: shadowColor sets the shadow color, noShadow removes the shadow, and shadowType is ignored for type=plain. Circle markers have no shadow unless you set shadowType.

Colored Glow

A glow is usually a dark halo, but with shadowColor set to the marker's fill color it becomes a colored light around the marker. This works on light basemaps and stands out even more on dark ones.

https://api.geoapify.com/v2/icon?type=phosphor&icon=tree&color=%232e7d32&contentColor=%23ffffff&noWhiteCircle&shadowType=glow&shadowColor=%232e7d32&size=64&contentSize=26&scaleFactor=2&apiKey=YOUR_API_KEY

shadowColor accepts the same formats as other colors: HEX, named colors, rgb(), and rgba() for semi-transparent shadows. Remember to URL-encode # as %23.

Which Ready-to-Use Marker Styles Can You Start With?

The new parameters combine into distinct visual themes. The four sets below are our suggestions, not presets built into the API: each is a group of parameters you add to size, color, icon, and apiKey.

noWhiteCircle removes the white circle behind the icon. Without it, a white contentColor would be invisible, because the icon would sit on a white background.

Why Do Shadows Move the Marker Anchor, and How Do the New Headers Fix It?

A map marker touches the map at one exact point, its anchor: the tip of a pin, or the center of a circle. The Marker Icon API returns a PNG that includes the shadow, so the image is larger than the size you request. The pin tip is not at the bottom edge, and the circle center is not at the image center. drop and glow shadows also make the image wider.

Most code anchors pins at the bottom center and circles at the image center. With a shadow, that hardcoded anchor places the marker off its location.

How Much Does a Shadow Move the Anchor?

We sent HEAD requests for a Material pin and a circle, both with icon=coffee&size=48, and recorded the headers. All values are CSS pixels:

ellipse is the default for pins; circles have no shadow by default. Anchor values are rounded to two decimals.

Two patterns stand out:

• A drop-shadow pin anchored at the bottom center points to a spot about 15 px above its location (71 − 56.42 = 14.58 px).
• Ground shadows move a circle's anchor down, so the circle stands above the location like a pin, while drop and glow keep the anchor at the circle center but shift it inside a larger image.

Read the Layout Headers

Every marker response now carries its layout, so you never measure images or hardcode offsets. The headers are documented in the API reference:

Here is what a teal Tabler pin returned in our test, type=tabler&icon=coffee&color=%230b7285&size=64&contentSize=26:

Icon-Width: 59
Icon-Height: 75
Icon-Anchor-X: 29.5
Icon-Anchor-Y: 66.5205781619119
Icon-Marker-Style: type:tabler;size:64;icontype:tabler;icon:coffee;color:#0b7285;contentsize:26

Display this marker at 59 × 75 CSS pixels and put the point 29.5 px from the left and about 66.52 px from the top on the location.

scaleFactor (from 0.5 to 10) only changes the PNG resolution, not the display size. The docs example type=material&size=60&scaleFactor=2 returns an 85 × 130 px PNG with Icon-Width: 42.5, Icon-Height: 65, Icon-Anchor-X: 21.25, and Icon-Anchor-Y: 58.92: a 60 px pin plus a 5 px shadow, displayed at half the PNG size.

The headers are listed in Access-Control-Expose-Headers, so browser code can read them with fetch().

Get Only the Headers with a HEAD Request

A HEAD request with the same parameters returns the Icon-* headers without the image body:

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

The icon and color do not change the layout. In our tests, type=tabler&size=64&contentSize=26 returned the same 59 × 75 size and 29.5, 66.52 anchor with icon=coffee&color=%230b7285 and with icon=tree&color=%23d55e00, and a drop-shadow Material pin returned identical headers for a coffee and a hotel icon in different colors. What does change the layout is the shape and shadow: type, size, strokeWidth, shadowType, noShadow, and scaleFactor.

That means one request per marker style is enough. The helper below, from the Geoapify quickstart examples, sends a HEAD request with the style parameters only and caches the result in a Map:

const apiKey = "YOUR_API_KEY";
const layoutCache = new Map();

// styleParams: URLSearchParams with type, size, contentSize,
// strokeWidth, shadowType or noShadow, and scaleFactor
async function getMarkerLayout(styleParams) {
  const key = styleParams.toString();

  if (!layoutCache.has(key)) {
    const response = await fetch(
      `https://api.geoapify.com/v2/icon?${key}&apiKey=${apiKey}`,
      { method: "HEAD" }
    );

    layoutCache.set(key, {
      width: Number(response.headers.get("Icon-Width")),
      height: Number(response.headers.get("Icon-Height")),
      anchorX: Number(response.headers.get("Icon-Anchor-X")),
      anchorY: Number(response.headers.get("Icon-Anchor-Y"))
    });
  }

  return layoutCache.get(key);
}

A HEAD request is a full API request. When a style is used with a single image, you can also fetch() the PNG once and read the same headers from that response. Responses carry Cache-Control: public, max-age=3600, and you are free to store generated markers, so a build script can compute layouts and images once and ship them with your app.

The three snippets below take that layout object and place a marker on a map. They are simplified from the quickstart examples; markerUrl is the full icon URL for one place.

Leaflet

Leaflet's iconAnchor is the pixel of the image that Leaflet puts on the coordinate, so it takes the header values unchanged. See the Leaflet L.icon reference.

const layout = await getMarkerLayout(styleParams);

const icon = L.icon({
  iconUrl: markerUrl,
  iconSize: [layout.width, layout.height],
  iconAnchor: [layout.anchorX, layout.anchorY],
  // Relative to iconAnchor: opens the popup above the top edge of the marker
  popupAnchor: [layout.width / 2 - layout.anchorX, -layout.anchorY]
});

L.marker([lat, lon], { icon }).addTo(map);

iconSize displays a scaleFactor=2 PNG at its CSS size, so it stays sharp on retina screens.

MapLibre GL

A MapLibre Marker aligns one of nine named positions of an HTML element with the coordinate. None of them is a pin tip above a shadow, so align the top-left corner and shift the element back by the anchor:

const layout = await getMarkerLayout(styleParams);

const image = document.createElement("img");
image.src = markerUrl;
image.style.width = `${layout.width}px`;
image.style.height = `${layout.height}px`;

new maplibregl.Marker({
  element: image,
  anchor: "top-left",
  offset: [-layout.anchorX, -layout.anchorY]
})
  .setLngLat([lon, lat])
  .addTo(map);

The built-in "bottom" anchor only fits pins without a shadow. For many points in a symbol layer, the same idea applies with "icon-anchor": "top-left" and "icon-offset": [-anchorX, -anchorY], adding the image with pixelRatio equal to scaleFactor.

OpenLayers

In OpenLayers, a pixel anchor refers to the source image, not the displayed size. Multiply the header values by scaleFactor and display the image at scale: 1 / scaleFactor. See the OpenLayers Icon reference.

const scaleFactor = 2; // the same value as in the marker URL
const layout = await getMarkerLayout(styleParams);

const style = new ol.style.Style({
  image: new ol.style.Icon({
    src: markerUrl,
    crossOrigin: "anonymous",
    anchor: [layout.anchorX * scaleFactor, layout.anchorY * scaleFactor],
    anchorXUnits: "pixels",
    anchorYUnits: "pixels",
    scale: 1 / scaleFactor
  })
});

Alternatively, pass the anchor as fractions, [anchorX / width, anchorY / height], which do not depend on scaleFactor.

Try the Examples

The Geoapify quickstart repository has a runnable demo for each library. Six places in downtown Chicago are shown with Lucide icons; you switch the marker shape and shadow, and red dots mark the exact coordinates. Uncheck "Use the anchor from the response headers" to see where a guessed anchor puts the markers.

• Leaflet: marker shadows and anchor headers
• MapLibre GL: marker shadows and anchor headers
• OpenLayers: marker shadows and anchor headers

Open src/index.html in a browser; no build step or local server is required. For a broader walkthrough, see How to Add Markers to a Map.

Do the New Options Work in Static Maps?

Yes. The Static Maps API marker parameter accepts the new options in its semicolon-separated format: shadowtype, strokewidth (0–10, at most marker size / 6), and the new type and icontype values. strokecolor and shadowcolor set the outline and shadow colors. The map below shows five places in downtown Chicago, each with a different shape, library, and shadow.

https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=1000&height=600&center=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_KEY

Icon-Marker-Style bridges the two APIs. Design a marker with the Marker Icon API, copy the header value, prefix it with lonlat:LON,LAT;, and URL-encode # as %23. The Tabler pin from the previous section becomes:

marker=lonlat:-87.6237,41.8796;type:tabler;size:64;icontype:tabler;icon:coffee;color:%230b7285;contentsize:26

In our tests, the header spelled out icontype whenever an icon was set, so the static marker uses the same icon library even if you change its type later. Static Maps also follows the same icontype defaults as the Marker Icon API when icontype is omitted. For more marker patterns, see How to Add Markers to a Static Map.

To design markers visually, open the Marker Icon API Playground, or read about the Map Marker Icon API and the marker icons generator.

Frequently Asked Questions