How to Add Markers to a Static Map

You have one or more locations and need a non-interactive map image that clearly identifies them. The Static Maps API accepts marker definitions together with the map style and image dimensions.

Each marker starts with lonlat:<longitude>,<latitude> and can specify its shape, size, color, icon, or text. Separate multiple marker definitions with |. If the request has markers but no explicit center or area, the API automatically frames the marker locations.

Add one marker to a static map

This request adds a purple Material-style marker at the Brandenburg Gate. The # in the marker color is URL-encoded as %23.

https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=800&height=500&scaleFactor=2&zoom=15&marker=lonlat:13.3777,52.5163;type:material;color:%23623aff;size:42&format=png&apiKey=YOUR_API_KEY

Image size: with scaleFactor=2, the generated bitmap is 1600 × 1000 pixels (800 × 2 by 500 × 2).

Result:

The marker coordinates define the image position because the request does not include center or area. Set center explicitly when the marker should appear away from the middle of the image.

The API scales the rendering for the higher pixel density, so keep the marker at its intended size instead of doubling size manually.

Add multiple markers to a static map

Separate marker definitions with |. This request shows three Material-style markers in different colors and uses a fixed center and zoom with space around the outer markers.

https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=800&height=500&scaleFactor=2&center=lonlat:13.39,52.52&zoom=13&marker=lonlat:13.3777,52.5163;type:material;color:%23623aff;size:42|lonlat:13.4010,52.5169;type:material;color:%23ff5a5f;size:42|lonlat:13.3694,52.5251;type:material;color:%2300a86b;size:42&format=png&apiKey=YOUR_API_KEY

Image size: with scaleFactor=2, the generated bitmap is 1600 × 1000 pixels (800 × 2 by 500 × 2).

Result:

Use consistent sizes and shapes for related locations. Use different colors only when they communicate categories or status. For large marker sets, build the parameter with URLSearchParams so reserved characters and color values are encoded correctly.

The Static Maps API supports up to 150 structured markers in a POST request. Prefer POST when a long marker definition makes a GET URL difficult to generate, store, or transmit reliably.

Add markers with a POST request

Use a POST request when markers come from structured application data or when many marker definitions would produce a long URL. Each marker has explicit lat and lon fields, so coordinate order is unambiguous.

POST https://maps.geoapify.com/v1/staticmap?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "style": "osm-bright",
  "width": 800,
  "height": 500,
  "scaleFactor": 2,
  "format": "png",
  "center": {
    "lat": 52.52,
    "lon": 13.39
  },
  "zoom": 13,
  "markers": [
    {
      "lat": 52.5163,
      "lon": 13.3777,
      "type": "material",
      "color": "#623aff",
      "size": 42
    },
    {
      "lat": 52.5169,
      "lon": 13.4010,
      "type": "material",
      "color": "#ff5a5f",
      "size": 42
    },
    {
      "lat": 52.5251,
      "lon": 13.3694,
      "type": "material",
      "color": "#00a86b",
      "size": 42
    }
  ]
}

Image size: with scaleFactor: 2, the generated bitmap is 1600 × 1000 pixels (800 × 2 by 500 × 2).

Result:

The explicit center and zoom keep space around the outer markers and produce the same viewport on repeated requests. Omit them when the API should derive the image extent from the markers, but check that the automatically fitted image leaves enough visual space for the chosen marker size.