Marker Icon API
The Marker Icon API helps you easily create custom map marker icons.
You can define the icon color, choose a shape, set the icon size (by specifying height in pixels), and pick an icon from the Material Design Icons or Font Awesome v6 libraries.
Here’s an example of a generated marker icon:
The API returns a ready-to-use image that you can:
- Embed in HTML and CSS,
- Display directly on a map using a client-side map library (e.g., using GeoJSON with Mapbox).
Explore and test the Marker Icon API in the API Playground:
- Authentication and API key setup
- API reference
- API reference (V1)
- Attribution guidelines
- Pricing information
Key updates in v2:
- Now uses Font Awesome v6 icons.
- Size is defined in pixels (height) instead of preset keywords.
- Added support for setting content color (icon color separately from background).
- Added option to use plain icons — without a background shape — for a clean, minimalistic look.
Authentication and API key
To use Geoapify Static Maps API, you need an API key. If you don’t have one yet, create a free account in Geoapify MyProjects.
Need help getting started? Follow this step-by-step guide to create your first project and obtain your API key.
API Reference
The Marker Icon API lets you generate beautiful, fully customizable marker icons for your projects.
The API returns a PNG image that can be used in HTML, CSS, or directly in client-side map libraries.
Request URL
https://api.geoapify.com/v2/icon?PARAMS
Request parameters
| Name | Description |
|---|---|
| apiKey | Your Geoapify API key. |
| type | Marker style type. Possible values: material (Material Design shape), awesome (Font Awesome marker shape), circle, plain (no background shape). |
| size | Icon image height in pixels. Defines the total size of the marker. |
| contentSize | Height of the inner content (icon or text) in pixels. Optional. If not set, a default proportion based on the marker size is applied. |
| contentColor | Color of the inner icon or text. Accepts named colors (red), HEX (%23667789 for #667789), rgb(), or rgba() values. Must be URL encoded. |
| color | Background color of the marker (ignored for plain type). Same color formats as contentColor. |
| strokeColor | Color of the background shape border (ignored for plain type). Same color formats as contentColor. |
| shadowColor | Color of the marker’s shadow. Same color formats as contentColor. |
| iconType | Defines the icon library used for the inner content. Possible values: material (to use a Material Design icon) or awesome (to use a Font Awesome v6 icon). Default: material for material and circle marker types, awesome for awesome marker type. |
| icon | Name of the inner icon. Depending on the iconType, use Material Design icon names or Font Awesome v6 icon names. |
| text | Text to display instead of an icon. If set, the icon parameter is ignored. |
| noShadow | If present (no value needed), disables the default shadow under the marker. |
| noWhiteCircle | Add the parameter without value to remove the white circle. |
Important notes:
- If you use
type=plain, only the inner icon or text is shown — no background shape is rendered. - Colors must be properly URL encoded (for example,
#must be written as%23).
URL Examples
| Icon | Example | URL |
|---|---|---|
| Simple marker with Material Design icon | https://api.geoapify.com/v2/icon?type=material&color=%23ff5722&size=64&apiKey=YOUR_API_KEY |
|
| Font Awesome marker with custom color | https://api.geoapify.com/v2/icon?type=awesome&icon=coffee&color=%230099ff&size=64&apiKey=YOUR_API_KEY |
|
| Plain icon (no background) with content color | https://api.geoapify.com/v2/icon?type=plain&icon=car&iconType=awesome&contentColor=%232ecc71&size=64&contentSize=48&apiKey=YOUR_API_KEY |
|
| Text instead of icon (plain) | https://api.geoapify.com/v2/icon?type=plain&text=A&contentColor=%23e91e63&size=64&contentSize=48&apiKey=YOUR_API_KEY |
|
| Circle marker with custom stroke and shadow color | https://api.geoapify.com/v2/icon?type=circle&icon=star&color=%23ffffff&strokeColor=%23000000&shadowColor=%23888888&size=64&contentSize=40&apiKey=YOUR_API_KEY |
|
| Marker without shadow | https://api.geoapify.com/v2/icon?type=awesome&color=%23ff9800&size=64&noShadow&apiKey=YOUR_API_KEY |
Attribution
The Marker Icon API uses icons from Material Design and Font Awesome v6 libraries.
Depending on how you use the icons, certain attributions may be required.
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 (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:
3. Material Design attribution
Material Design icons are available under the Apache License Version 2.0.
No additional attribution is required when using Material Design icons.
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
| Name | Description |
|---|---|
| apiKey | Geoapify API key |
| type | Marker icon type. Possible values: material - based on the Material Design pin icon , awesome - based on the Font Awesome pin icon, circle. |
| size | Marker size. Possible values: small, medium, large, x-large, xx-large. By default, is medium. |
| icon | Inner icon name. Depending on iconType value can take a value of Material Design or Font Awesome icon names. |
| iconType | Inner icon type. Possible values: material, awesome. Default value is material - for material and circle type, awesome - for awesome type. |
| iconSize | Inner icon size. Possible values: small, medium, large. By default, is medium. |
| text | Icon text. Note, the icon parameter is ignored when the text set. |
| textSize | Text size. Possible values: small, medium, large. By default, is medium. |
| color | Icon color. Use text, fex, rgb, or rgba values here. For example, red, %23667789 (instead of #667789) , rgb(233,44,34), rgba(35,245,22,0.7). Note, the parameter must be URL encoded, so # is represented as %23. |
| strokeColor | Icon stroke color. The parameter requirements are the same as for the color parameter. |
| shadowColor | Icon shadow color. The parameter requirements are the same as for the color parameter. |
| noWhiteCircle | Add the parameter without value to remove the white circle. |
| noShadow | Add the parameter without value to remove the icon shadow. |
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,plaintype, or pixel-based size control (available in v2).