Documentation


Getting Started

Building more interactive maps with MapMarker.io is easy and a fairly straight forward process. To use our map markers in your project, you do not need to pay or register any api keys.

Just make sure that whatever you are building your maps with supports creating custom map markers from .png image files. Most web based mapping SDKs like Google Maps or Bing Maps support this out of the box. Take a closer look at our integrations section to learn more.

Did you know?

We have an interactive marker creator that allows you to create pixel-perfect map markers for your map or application.

Launch the Marker Creator


Font-Awesome (v5)


MapMarker.io now supports explicit Font Awesome versions to ensure you can build the markers that match your application. Since class names can vary from version to version, we have included a complete list of available icons in version v5.

MapMarker.io Pin with Text

Pin (with Text)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v5/pin?text=P&size=40&background=D94B43&color=FFF&hoffset=-1


The pin is the simplest form of map marker and the first type of marker supported by the API. There are a few parameters to configure the pin for your use case:

Parameter Description
size 30, 35, 40 You can size your pin by passing in the size attribute. The image will be scaled according to the aspect ratio, so distortion is not possible.
background 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's background color to make it stand out / match your design colors.
text 1, 2, AA, AB, A1(optional) Add some text to your map marker! Pretty straight forward. If both the icon and text parameter are passed, the icon is rendered on the marker but no text is shown.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's font color to make sure your custom label is readable!
voffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin horizontally.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Pin with Icon

Pin (with Icon)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v5/pin?icon=fa-star-solid&size=50&hoffset=0&voffset=-1


The pin is the simplest form of map marker and the first type of marker supported by the API. There are a few parameters to configure the pin for your use case:

Parameter Description
size 30, 35, 40 You can size your pin by passing in the size attribute. The image will be scaled according to the aspect ratio, so distortion is not possible.
iconSize 30, 35, 40 You can size the icon to be layered onto the pin by passing in the iconSize attribute.
background 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's background color to make it stand out / match your design colors.
icon fa-truck, fa-globe, fa-home, ... (optional) Add some context to your map markers with using Font-Awesome Icons. If both the icon and text parameter are passed, the icon is rendered on the marker but no text is shown.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's font color to make sure your custom label is readable!
voffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin horizontally.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Icon Marker

Icon (powered by Font-Awesome)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v5/icon?icon=fa-star-solid&size=50&color=DC4C3F


The Icon (Font Awesome) is an awesome way of adding context to your maps. The fact that colors & sizes can be changed is just an added bonus.

Parameter Description
size 30, 35, 40 Since all font awesome icons are rendered as squares, the size parameter is both the height and the width (in pixels) of the generated file.
icon fa-star, fa-flag Pass along any Font Awesome (v4.4.0) class name to generate your icon map marker. If an invalid icon name is passed, it simply returns the fa-map-marker icon. Check out the full list of available icons here.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Icon Stack

Icon Stack (powered by Font-Awesome)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v5/icon-stack?size=50&color=DC4C3F&icon=fa-star-solid


The Icon Stack (another Font Awesome feature) is an awesome way of customizing your map marker icons even more. Layer any combination of icons and colors.

Parameter Description
size 30, 35, 40 Since all font awesome icons are rendered as squares, the size parameter is both the height and the width (in pixels) of the generated file.
icon fa-star, fa-flag Pass along any Font Awesome (v4.4.0) class name to generate your icon map marker. If an invalid icon name is passed, it simply returns the fa-map-marker icon. Check out the full list of available icons here.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
on fa-star, fa-flag, ... Pass along any Font Awesome (v4.4.0) class name to generate your icon stack background "fa" class. If an invalid icon name is passed, it simply returns the fa-circle-o icon. Check out the full list of available icons here.
oncolor 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
voffset Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset Pass along any offset (interger) to shift the text rendered in the pin horizontally.
iconsize 30, 35, 40 Size the font awesome icon that is rendered on top of the on icon. This allows you to adjust relative sizes of the two icons rendered.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

Font-Awesome (v4)


MapMarker.io now supports explicit Font Awesome versions to ensure you can build the markers that match your application. Since class names can vary from version to version, we have included a complete list of available icons in version v4.

MapMarker.io Pin with Text

Pin (with Text)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v4/?text=P&size=40&background=D94B43&color=FFF&hoffset=-1


The pin is the simplest form of map marker and the first type of marker supported by the API. There are a few parameters to configure the pin for your use case:

Parameter Description
size 30, 35, 40 You can size your pin by passing in the size attribute. The image will be scaled according to the aspect ratio, so distortion is not possible.
background 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's background color to make it stand out / match your design colors.
text 1, 2, AA, AB, A1(optional) Add some text to your map marker! Pretty straight forward. If both the icon and text parameter are passed, the icon is rendered on the marker but no text is shown.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's font color to make sure your custom label is readable!
voffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin horizontally.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Pin with Icon

Pin (with Icon)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v4/pin?icon=fa-star&size=50&hoffset=0&voffset=-1


The pin is the simplest form of map marker and the first type of marker supported by the API. There are a few parameters to configure the pin for your use case:

Parameter Description
size 30, 35, 40 You can size your pin by passing in the size attribute. The image will be scaled according to the aspect ratio, so distortion is not possible.
iconSize 30, 35, 40 You can size the icon to be layered onto the pin by passing in the iconSize attribute.
background 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's background color to make it stand out / match your design colors.
icon fa-truck, fa-globe, fa-home, ... (optional) Add some context to your map markers with using Font-Awesome Icons. If both the icon and text parameter are passed, the icon is rendered on the marker but no text is shown.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's font color to make sure your custom label is readable!
voffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin horizontally.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Icon Marker

Icon (powered by Font-Awesome)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v4/icon?icon=fa-star&size=50&color=DC4C3F


The Icon (Font Awesome) is an awesome way of adding context to your maps. The fact that colors & sizes can be changed is just an added bonus.

Parameter Description
size 30, 35, 40 Since all font awesome icons are rendered as squares, the size parameter is both the height and the width (in pixels) of the generated file.
icon fa-star, fa-flag Pass along any Font Awesome (v4.4.0) class name to generate your icon map marker. If an invalid icon name is passed, it simply returns the fa-map-marker icon. Check out the full list of available icons here.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Icon Stack

Icon Stack (powered by Font-Awesome)

Example URL: https://cdn.mapmarker.io/api/v1/font-awesome/v4/icon-stack?size=50&color=DC4C3F&icon=fa-star&hoffset=1&voffset=-1


The Icon Stack (another Font Awesome feature) is an awesome way of customizing your map marker icons even more. Layer any combination of icons and colors.

Parameter Description
size 30, 35, 40 Since all font awesome icons are rendered as squares, the size parameter is both the height and the width (in pixels) of the generated file.
icon fa-star, fa-flag Pass along any Font Awesome (v4.4.0) class name to generate your icon map marker. If an invalid icon name is passed, it simply returns the fa-map-marker icon. Check out the full list of available icons here.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
on fa-star, fa-flag, ... Pass along any Font Awesome (v4.4.0) class name to generate your icon stack background "fa" class. If an invalid icon name is passed, it simply returns the fa-circle-o icon. Check out the full list of available icons here.
oncolor 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
voffset Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset Pass along any offset (interger) to shift the text rendered in the pin horizontally.
iconsize 30, 35, 40 Size the font awesome icon that is rendered on top of the on icon. This allows you to adjust relative sizes of the two icons rendered.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.


Map Markers (Legacy)


MapMarker.io Pin with Text

Pin (with Text)

Example URL: https://cdn.mapmarker.io/api/v1/pin?text=P&size=40&background=D94B43&color=FFF&hoffset=-1


The pin is the simplest form of map marker and the first type of marker supported by the API. There are a few parameters to configure the pin for your use case:

Parameter Description
size 30, 35, 40 You can size your pin by passing in the size attribute. The image will be scaled according to the aspect ratio, so distortion is not possible.
background 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's background color to make it stand out / match your design colors.
text 1, 2, AA, AB, A1(optional) Add some text to your map marker! Pretty straight forward. If both the icon and text parameter are passed, the icon is rendered on the marker but no text is shown.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's font color to make sure your custom label is readable!
voffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin horizontally.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Pin with Icon

Pin (with Icon)

Example URL: https://cdn.mapmarker.io/api/v1/pin?icon=fa-star&size=50&hoffset=0&voffset=-1


The pin is the simplest form of map marker and the first type of marker supported by the API. There are a few parameters to configure the pin for your use case:

Parameter Description
size 30, 35, 40 You can size your pin by passing in the size attribute. The image will be scaled according to the aspect ratio, so distortion is not possible.
iconSize 30, 35, 40 You can size the icon to be layered onto the pin by passing in the iconSize attribute.
background 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's background color to make it stand out / match your design colors.
icon fa-truck, fa-globe, fa-home, ... (optional) Add some context to your map markers with using Font-Awesome Icons. If both the icon and text parameter are passed, the icon is rendered on the marker but no text is shown.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the pin's font color to make sure your custom label is readable!
voffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset -n, -3, -2, -1, 0, 1, 2, 3, ... n Pass along any offset (interger) to shift the text rendered in the pin horizontally.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Icon Marker

Icon (powered by Font-Awesome)

Example URL: https://cdn.mapmarker.io/api/v1/fa?icon=fa-star&size=50&color=DC4C3F


The Icon (Font Awesome) is an awesome way of adding context to your maps. The fact that colors & sizes can be changed is just an added bonus.

Parameter Description
size 30, 35, 40 Since all font awesome icons are rendered as squares, the size parameter is both the height and the width (in pixels) of the generated file.
icon fa-star, fa-flag Pass along any Font Awesome (v4.4.0) class name to generate your icon map marker. If an invalid icon name is passed, it simply returns the fa-map-marker icon. Check out the full list of available icons here.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.

MapMarker.io Icon Stack

Icon Stack (powered by Font-Awesome)

Example URL: https://cdn.mapmarker.io/api/v1/fa/stack?size=50&color=DC4C3F&icon=fa-star&hoffset=1


The Icon Stack (another Font Awesome feature) is an awesome way of customizing your map marker icons even more. Layer any combination of icons and colors.

Parameter Description
size 30, 35, 40 Since all font awesome icons are rendered as squares, the size parameter is both the height and the width (in pixels) of the generated file.
icon fa-star, fa-flag Pass along any Font Awesome (v4.4.0) class name to generate your icon map marker. If an invalid icon name is passed, it simply returns the fa-map-marker icon. Check out the full list of available icons here.
color 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
on fa-star, fa-flag, ... Pass along any Font Awesome (v4.4.0) class name to generate your icon stack background "fa" class. If an invalid icon name is passed, it simply returns the fa-circle-o icon. Check out the full list of available icons here.
oncolor 333333, 6E942A Pass along any hex-code (ommit the #) to set the icon's color to make sure your custom icon is easily visible!
voffset Pass along any offset (interger) to shift the text rendered in the pin veritcally.
hoffset Pass along any offset (interger) to shift the text rendered in the pin horizontally.
iconsize 30, 35, 40 Size the font awesome icon that is rendered on top of the on icon. This allows you to adjust relative sizes of the two icons rendered.
label Pass along any text to create a circular label in the bottom right hand side of the icon containing the label text.
labelColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's color
labelTextColor 333333, 6E942A Pass along any hex-code (ommit the #) to set the label's text color
labelOffset Pass along any offset (interger) to shift the text rendered in the label bubble horizontally. Use this to ensure your map markers are pixel perfect at any size.


Integrations

Here are a few examples on how to add our custom markers to the maps you are already working with.


Bing Maps (Web)

var map = new Microsoft.Maps.Map(document.getElementById('myMap'), {
    credentials: 'Your Bing Maps Key'
});

var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), { 
    icon: 'https://cdn.mapmarker.io/api/v1/pin?icon=fa-star&size=50&hoffset=0&voffset=-1',
    anchor: new Microsoft.Maps.Point(12, 39)
});

map.entities.push(pushpin);

Google Maps (Web)

function initMap() {
    var uluru = {lat: -25.363, lng: 131.044};
    var map = new google.maps.Map(document.getElementById('map-google'), {
        zoom: 4,
        center: uluru
    });
    
    // a more conventional map pin
    var marker = new google.maps.Marker({
        position: uluru,
        icon: 'https://cdn.mapmarker.io/api/v1/pin?icon=fa-star&size=50&hoffset=0&voffset=-1',
        map: map
    });
    
    // a square icon whose center is on the lat / long
    var circle = new google.maps.Marker({
        position: {lat: 37.827125, lng: -122.422844},
        map: map,
        icon: {
            size: new google.maps.Size(120, 120),
            scaledSize: new google.maps.Size(60,60),
            url: 'https://cdn.mapmarker.io/api/v1/fa?size=120&icon=fa-bullseye&color=%23D33115',
            anchor: new google.maps.Point(30, 30),
        },
        title: "Alert",
    });
    
}

Mapbox (Web)

var markerElement = document.createElement('div');
markerElement.style.backgroundImage = "url('https://cdn.mapmarker.io/api/v1/pin?icon=fa-star&size=50&hoffset=0&voffset=-1')";
markerElement.style.width = '50px';
markerElement.style.height = '50px';

var marker = new mapboxgl.Marker(markerElement, {offset: [-25, 50]})
    .setLngLat([-65.017, -16.457])
    .addTo(map);


Performance in Production Environments

MapMarker handles the demands of production applications right out of the box. Here is how we ensure that our markers are always available when your users need them.


Map Marker Life Cycle

To understand how MapMarker.io can handle high loads for very custom items, we are first going to talk about the lifecycle of the generated markers.

There are 2 lifecycle stages for any unique marker:

  1. A marker that has never been requested ~300ms
    a common case during development as you are tweaking options
    MapMarker Cache Miss Lifecycle
  2. A marker that has been requested before ~50ms
    a common case during QA and production as you are retrieving markers generated in development.
    MapMarker Cache Hit Lifecycle

The massive decrease in load time (~80%) is due to MapMarker's use of the Cloudflare CDN on the marker routes. Once a marker has been generated once, the resulting image is cached and distributed accross the Cloudflare Content-Delivery-Network and served directly from there to the client applications instead of being dynamically generated every time.


CDN Performance tested with Pingdom

~30ms
Melbourne, Australia

~55ms
Dallas, Texas

~41ms
San Jose, California

~105ms
Stockholm, Sweden