Custom Map Styles in Bing Maps

Bing
 

Depending on which API or service you are using there are two different ways to specify a custom style in Bing Maps. The Bing Maps V8 web and Windows 10 UWP controls use a JSON style object, while the Bing Maps REST services and map tiles use a formatted string.

The JSON style schema is very comprehensive. The Windows 10 UWP map control makes full use of the schema while the Bing Maps V8 Web control and REST services support a subset of the schema. A JSON style created for the Windows 10 UWP map control will work with the V8 Web Control and vice-versa. Any unsupported style settings will simply be ignored.

This documentation will focus on custom map styles in Bing Maps V8 Web Control and the Bing Maps REST services. Documentation on using custom map styles in the Windows 10 UWP control can be found here.

The Bing Maps V8 control has a new map option called customMapStyle which can be set when loading the map. This property expects a JSON map ICustomMapStyle object. Here is an example of how to add a custom map style to Bing Maps V8.

<!DOCTYPE html>
<html>
<head>
    <title></title>
    <meta charset="utf-8" />
    <script type='text/javascript'>
        var map;

        var myStyle = {
            "elements": {
                "water": { "fillColor": "#a1e0ff" },
                "waterPoint": { "iconColor": "#a1e0ff" },
                "transportation": { "strokeColor": "#aa6de0" },
                "road": { "fillColor": "#b892db" },
                "railway": { "strokeColor": "#a495b2" },
                "structure": { "fillColor": "#ffffff" },
                "runway": { "fillColor": "#ff7fed" },
                "area": { "fillColor": "#f39ebd" },
                "political": { "borderStrokeColor": "#fe6850", "borderOutlineColor": "#55ffff" },
                "point": { "iconColor": "#ffffff", "fillColor": "#FF6FA0", "strokeColor": "#DB4680" },
                "transit": { "fillColor": "#AA6DE0" }
            },
            "version": "1.0" 
        };

        function GetMap()
        {
            map = new Microsoft.Maps.Map('#myMap', {
                credentials: 'Your Bing Maps Key',
                customMapStyle: myStyle
            });
        }
    </script>
    <script type='text/javascript' src='http://www.bing.com/api/maps/mapcontrol?callback=GetMap' async defer></script>
</head>
<body>
    <div id="myMap"></div>
</body>
</html>

Running this code will produce a map that looks like this:

Pink Map Style

Tip: TypeScript definitions for the Bing Maps V8 Web Control do include definitions for custom style schema. You can access the Bing Maps TypeScript definitions here.

Custom map styles can be used with the Bing Maps REST imagery service and when directly accessing Bing Maps tiles in a supported manner. To add a custom map style, a formatted string version of the style can be added as a URL parameter to the image/tile request. The URL parameter that can be added to the request is &style= or &st=.

The style string has the following format:

[elementName]|[styleParam1]:[value];[styleParam2]:[value];

The above format is for a single element in the custom map style. You can combine multiple elements and the settings value by joining them with an underscore (_). The element name can either be the full element name (i.e. road) or the short form version (i.e. rd).

For example, take the following JSON style which colors water areas red and their labels green, makes roads blue, and sets the global land color to white:

{
    "elements": {
        "water": {
            "fillColor": "#FF0000",
            "labelColor": "#00FF00"
        },
        "road": { "fillColor": "#0000FF" }
    },
    "settings": { "landColor": "#FFFFFF" },
    "version": "1.0"
}

The string formatted version of this style looks like this (long form):

water|fillColor:FF0000;labelColor:00FF00_road|fillColor:0000FF_global|landColor:FFFFFF 

Here is the same style using the short form version:

wt|fc:FF0000;lbc:00FF00_rd|fc:0000FF_g|landColor:FFFFFF

This can then be appended to a REST Static Image request or a tile URL. For example:

http://dev.virtualearth.net/REST/V1/Imagery/Map/Road/Bellevue%20Washington?&key=[YOUR_BING_MAPS_KEY]&st=wt|fc:FF0000;lbc:00FF00_rd|fc:0000FF_g|landColor:FFFFFF

Here is the image this request would return:

Red Blue Map Style

If the style is too long for a URL, when using the REST imagery service, the style can be passed in using a POST request. The POST data object format is: style=[Your custom style]

The following defines the JSON objects that are used for creating custom map styles. All color values are specified as a hex #RRGGBB or #AARRGGBB string. When using the REST/Tile services, do not include hashtags.

Tip: Ensure that all colors have 6 or 8 characters. If there is any other number of characters, the style will be considered invalid.

ICustomMapStyle Object

The following properties are available in the custom map style object.

NameURL ParamTypeDescription
elementsIMapElementsA list of map elements to be styled.
settingsgISettingStyleGlobal settings.
versionstringThe version number of the style syntax.

IMapElements Object

The following is a list of map elements that can be styled to create a custom map style.

NameURL ParamTypeDescription
adminDistrictadIBorderedMapElementStyleAdmin1, state, province, etc.
adminDistrictCapitaladcIMapElementStyleIcon representing the capital of a state/province.
airportapIMapElementStyleArea of land encompassing an airport.
areaarIMapElementStyleArea of land use, not to be confused with Structure
arterialRoadardIMapElementStyleAn arterial road is a high-capacity urban road. Its primary function is to deliver traffic from collector roads to freeways or expressways, and between urban centers efficiently.
buildingbldIMapElementStyleA structure such as a house, store, factory.
businessbsIMapElementStyleRestaurant, hospital, school, etc.
capitalcpIMapElementStyleIcon representing the capital populated place.
cemeterycmIMapElementStyleArea of a cemetery
continentctIMapElementStyleArea of a whole continent
controlledAccessHighwaycahIMapElementStyleA controlled-access highway is a type of road which has been designed for high-speed vehicular traffic, with all traffic flow and ingress/egress regulated. Also known as a highway, freeway, motorway, expressway, interstate, parkway, autobahn.
countryRegioncrIBorderedMapElementStyleA country or independent sovereign state.
countryRegionCapitalcrcIMapElementStyleIcon representing the capital of a country/region.
districtdsIBorderedMapElementStyleAdmin2, county, etc.
educationedIMapElementStyleAn area of land used for educational purposes such as a school campus.
educationBuildingebIMapElementStyleA school or other educational building.
foodPointfpIMapElementStyleRestaurant, café, etc.
forestfrIMapElementStyleArea of forest land.
golfCoursegcIMapElementStyleAn area of land where the game of golf is played.
highSpeedRamphsrpIMapElementStyleLines representing ramps typically alongside ControlledAccessHighways
highwayhgIMapElementStyleAll other highways other than controlled access highways.
indigenousPeoplesReserveiprIMapElementStyleAn area of land reserved for Indigenous people.
islandisIMapElementStyleLabeling of area of an island.
majorRoadmrIMapElementStyleMajor roads.
mapElementmeIMapElementStyleThe base map element in which all other map elements inherit from.
medicalmdIMapElementStyleArea of land used for medical purposes. Generally, hospital campuses.
medicalBuildingmbIMapElementStyleA building which provides medical services.
militaryimaIMapElementStyleA military area.
naturalPointnpIMapElementStyleA natural point of interest.
nauticalntIMapElementStyleArea of land used for nautical purposes.
neighborhoodnhIMapElementStyleArea defined as a neighborhood.
parkprIMapElementStyleArea of any kind of park.
peakpkIMapElementStyleIcon representing the peak of a mountain.
playingFieldpfIMapElementStyleExtracted pitches such as a baseball
pointptIMapElementStyleAll point features that are rendered with an icon of some sort.
pointOfInterestpoiIMapElementStyleRestaurant, hospital, school, marina, ski area, etc.
politicalplIBorderedMapElementStyleA political border.
populatedPlaceppIMapElementStyleIcon representing size of populated place (city, town, etc).
railwayrlIMapElementStyleRailway lines
ramprmIMapElementStyleLine representing the connecting entrance/exit to a highway.
reserversvIMapElementStyleArea of nature reserve.
riverrvIMapElementStyleRiver, stream, or other passage. Note that this may be a line or polygon and may connect to non-river water bodies.
roadrdIMapElementStyleLines that represent all roads
roadExitreIMapElementStyleIcon representing the exit, typically from a controlled access highway.
runwayrwIMapElementStyleLand area covered by a runway. See also Airport for the land area of the whole airport.
sandsnIMapElementStyleArea generally used for beaches but could be used for sandy areas/golf bunkers in the future.
shoppingCentersctIMapElementStyleA shopping center or mall.
stadiumstaIMapElementStyleArea of a stadium.
streetstIMapElementStyleA street.
structurestrIMapElementStyleBuildings and other building-like structures
tollRoadtrIMapElementStyleA toll road.
trailtrlIMapElementStyleWalking trail, either through park or hiking trail
transittrnIMapElementStyleIcon representing a bus stop, train stop, airport, etc.
transitBuildingtbIMapElementStyleA transit building.
transportationtrsIMapElementStyleLines that are part of the transportation network (roads, trains, ferries, etc.)
unpavedStreetusIMapElementStyleAn unpaved street.
vegetationvgIMapElementStyleForests, grassy areas, etc.
volcanicPeakvpIMapElementStyleIcon representing the peak of a volcano.
waterwtIMapElementStyleAnything that looks like water.
waterPointwpIMapElementStyleIcon representing a water feature location such as a waterfall.
waterRoutewrIMapElementStyleFerry route lines

IMapElementStyle Object

The following properties can be used when styling a map element.

JSON NameURL ParamTypeDescription
fillColorfcstringColor used for filling polygons, the background of point icons, and for the center of lines if they have split.
labelColorlbcstringThe color of a map label.
labelOutlineColorlocstringThe outline color of a map label.
labelVisiblelvbooleanSpecies if a map label type is visible or not.
strokeColorscstringColor used for the outline around polygons, the outline around point icons, and the color of lines.
visiblevbooleanSpecifies if the map element is visible or not.

IBorderedMapElementStyle Object

Extends the IMapElementStyle object.

JSON NameURL ParamTypeDescription
borderOutlineColorbocstringSecondary/casing line color of the border of a filled polygon.
borderStrokeColorbscstringPrimary line color of the border of a filled polygon.
borderVisiblebvbooleanSpecifies if a border is visible or not.

ISettingStyle Object

Defines the global settings that can be set.

JSON NameURL ParamTypeDescription
landColorlcstringA color value that all land is first flushed to before things are drawn on it.
shadedReliefVisiblebooleanSpecifies whether or not to draw elevation shading on the map.

When styling map elements there is a hierarchy which can be used to apply styles at different levels. For example, if you wanted to make all roads red, you could go and style each road type, or you could simply apply the style to the road elements and all child elements would inherit that style. If you then wanted to only make toll roads green you could then add a style for that element and all other road types would continue to stay red.

Here is the map element hierarchy.

  • area
    • airport
    • cemetery
    • continent
    • education
    • golfCourse
    • indigenousPeoplesReserve
    • island
    • military
    • medical
    • nautical
    • neighborhood
    • runway
    • sand
    • shoppingCenter
    • stadium
    • vegetation
      • forest
      • park
      • playingField
      • reserve
  • point
    • naturalPoint
      • peak
        • volcanicPeak
      • waterPoint
    • pointOfInterest
      • business
        • foodPoint
    • populatedPlace
      • capital
        • adminDistrictCapital
        • countryRegionCapital
    • roadExit
    • transit
  • political
    • countryRegion
    • adminDistrict
    • district
  • structure
    • building
      • educationBuilding
      • medicalBuilding
      • transitBuilding
  • transportation
    • road
      • controlledAccessHighway
        • highSpeedRamp
      • highway
      • majorRoad
      • arterialRoad
      • street
        • ramp
      • unpavedStreet
      • tollRoad
    • railway
    • trail
    • waterRoute
  • water
    • river

The following are some known limitations of custom map styles.

  • Custom styles are not supported for all country maps. Custom maps styles require the use of vector map data. Some countries have strict regulations around vector map data which prevents the Bing Maps team from using it to create custom map styles on the fly. This effects China, South Korea, and Japan currently. If you zoom into one of these countries, you will see the default map tile style appear for these countries while surrounding areas will use the custom map style.

Bing Maps V8

  • If labels are styled, the map will go into liteMode as vector label styling is not currently supported.

REST/Tile Services

  • When using formatted string styles, do not end the style with a semi-colon (;).

  • When an invalid style is passed to the REST service, a blue image is returned.

Here are some sample custom map styles.

Midnight Commander Style

Midnight Commander Map Style

{
    "version": "1.0",
    "settings": {
        "landColor": "#0B334D"
    },
    "elements": {
        "mapElement": {
            "labelColor": "#FFFFFF",
            "labelOutlineColor": "#000000"
        },
        "political": {
            "borderStrokeColor": "#144B53",
            "borderOutlineColor": "#00000000"
        },
        "point": {
            "iconColor": "#0C4152",
            "fillColor": "#000000",
            "strokeColor": "#0C4152"
        },
        "transportation": {
            "strokeColor": "#000000",
            "fillColor": "#000000"
        },
        "highway": {
            "strokeColor": "#158399",
            "fillColor": "#000000"
        },
        "controlledAccessHighway": {
            "strokeColor": "#158399",
            "fillColor": "#000000"
        },
        "arterialRoad": {
            "strokeColor": "#157399",
            "fillColor": "#000000"
        },
        "majorRoad": {
            "strokeColor": "#157399",
            "fillColor": "#000000"
        },
        "railway": {
            "strokeColor": "#146474",
            "fillColor": "#000000"
        },
        "structure": {
            "fillColor": "#115166"
        },
        "water": {
            "fillColor": "#021019"
        },
        "area": {
            "fillColor": "#115166"
        }
    }
}

REST Style

me|lbc:ffffff;loc:000000_pl|bsc:144b53;boc:00000000_pt|ic:0c4152;fc:000000;sc:0c4152_trs|sc:000000;fc:000000_hg|sc:158399;fc:000000_cah|sc:158399;fc:000000_ard|sc:157399;fc:000000_mr|sc:157399;fc:000000_rl|sc:146474;fc:000000_str|fc:115166_wt|fc:021019_ar|fc:115166_g|lc:0b334d

Countries Only Style

Country Only Map Style

{
    "version": "1.0",
    "elements": {
        "mapElement": {
            "labelVisible": false
        },
        "area": {
            "visible": false
        },
        "transportation": {
            "visible": false
        },
        "countryRegion": {
            "borderStrokeColor": "#444444",
            "borderOutlineColor": "#00000000",
            "fillColor": "#888888",
            "visible": true
        },
        "adminDistrict": {
            "borderVisible": false
        },
        "water": {
            "fillColor": "#FFFFFF"
        },
        "point": {
            "visible": false
        }
    }
}

REST Style

me|lv:0_ar|v:0_trs|v:0_cr|bsc:444444;boc:00000000;fc:888888;v:1_ad|bv:0_wt|fc:ffffff_pt|v:0

Faded Map Style

Faded Map Style

{
    "version": "1.0",
    "settings": {
        "landColor": "#e7e6e5",
        "shadedReliefVisible": false
    },
    "elements": {
        "vegetation": {
            "fillColor": "#c5dea2"
        },
        "naturalPoint": {
            "visible": false,
            "labelVisible": false
        },
        "transportation": {
            "labelOutlineColor": "#ffffff",
            "fillColor": "#ffffff",
            "strokeColor": "#d7d6d5"
        },
        "water": {
            "fillColor": "#b1bdd6",
            "labelColor": "#ffffff",
            "labelOutlineColor": "#9aa9ca"
        },
        "structure": {
            "fillColor": "#d7d6d5"
        },
        "indigenousPeoplesReserve": {
            "visible": false
        },
        "military": {
            "visible": false
        }
    }
}

REST Style

vg|fc:c5dea2_np|v:0;lv:0_trs|loc:ffffff;fc:ffffff;sc:d7d6d5_wt|fc:b1bdd6;lbc:ffffff;loc:9aa9ca_str|fc:d7d6d5_ipr|v:0_ima|v:0_g|lc:e7e6e5;srv:0

Show: