Custom Map Styles in Bing Maps V8 and REST Services

Article
07/11/2017

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.

Custom Map Styles in the Bing Maps V8 Web Control

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='https://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 in the REST and Tile Services

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:

https://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]

Style Objects

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.

Name	URL Param	Type	Description
elements		IMapElements	A list of map elements to be styled.
settings	g	ISettingStyle	Global settings.
version		string	The 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.

Name	URL Param	Type	Description
adminDistrict	ad	IBorderedMapElementStyle	Admin1, state, province, etc.
adminDistrictCapital	adc	IMapElementStyle	Icon representing the capital of a state/province.
airport	ap	IMapElementStyle	Area of land encompassing an airport.
area	ar	IMapElementStyle	Area of land use, not to be confused with Structure
arterialRoad	ard	IMapElementStyle	An 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.
building	bld	IMapElementStyle	A structure such as a house, store, factory.
business	bs	IMapElementStyle	Restaurant, hospital, school, etc.
capital	cp	IMapElementStyle	Icon representing the capital populated place.
cemetery	cm	IMapElementStyle	Area of a cemetery
continent	ct	IMapElementStyle	Area of a whole continent
controlledAccessHighway	cah	IMapElementStyle	A 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.
countryRegion	cr	IBorderedMapElementStyle	A country or independent sovereign state.
countryRegionCapital	crc	IMapElementStyle	Icon representing the capital of a country/region.
district	ds	IBorderedMapElementStyle	Admin2, county, etc.
education	ed	IMapElementStyle	An area of land used for educational purposes such as a school campus.
educationBuilding	eb	IMapElementStyle	A school or other educational building.
foodPoint	fp	IMapElementStyle	Restaurant, café, etc.
forest	fr	IMapElementStyle	Area of forest land.
golfCourse	gc	IMapElementStyle	An area of land where the game of golf is played.
highSpeedRamp	hsrp	IMapElementStyle	Lines representing ramps typically alongside ControlledAccessHighways
highway	hg	IMapElementStyle	All other highways other than controlled access highways.
indigenousPeoplesReserve	ipr	IMapElementStyle	An area of land reserved for Indigenous people.
island	is	IMapElementStyle	Labeling of area of an island.
majorRoad	mr	IMapElementStyle	Major roads.
mapElement	me	IMapElementStyle	The base map element in which all other map elements inherit from.
medical	md	IMapElementStyle	Area of land used for medical purposes. Generally, hospital campuses.
medicalBuilding	mb	IMapElementStyle	A building which provides medical services.
military	ima	IMapElementStyle	A military area.
naturalPoint	np	IMapElementStyle	A natural point of interest.
nautical	nt	IMapElementStyle	Area of land used for nautical purposes.
neighborhood	nh	IMapElementStyle	Area defined as a neighborhood.
park	pr	IMapElementStyle	Area of any kind of park.
peak	pk	IMapElementStyle	Icon representing the peak of a mountain.
playingField	pf	IMapElementStyle	Extracted pitches such as a baseball
point	pt	IMapElementStyle	All point features that are rendered with an icon of some sort.
pointOfInterest	poi	IMapElementStyle	Restaurant, hospital, school, marina, ski area, etc.
political	pl	IBorderedMapElementStyle	A political border.
populatedPlace	pp	IMapElementStyle	Icon representing size of populated place (city, town, etc).
railway	rl	IMapElementStyle	Railway lines
ramp	rm	IMapElementStyle	Line representing the connecting entrance/exit to a highway.
reserve	rsv	IMapElementStyle	Area of nature reserve.
river	rv	IMapElementStyle	River, stream, or other passage. Note that this may be a line or polygon and may connect to non-river water bodies.
road	rd	IMapElementStyle	Lines that represent all roads
roadExit	re	IMapElementStyle	Icon representing the exit, typically from a controlled access highway.
runway	rw	IMapElementStyle	Land area covered by a runway. See also Airport for the land area of the whole airport.
sand	sn	IMapElementStyle	Area generally used for beaches but could be used for sandy areas/golf bunkers in the future.
shoppingCenter	sct	IMapElementStyle	A shopping center or mall.
stadium	sta	IMapElementStyle	Area of a stadium.
street	st	IMapElementStyle	A street.
structure	str	IMapElementStyle	Buildings and other building-like structures
tollRoad	tr	IMapElementStyle	A toll road.
trail	trl	IMapElementStyle	Walking trail, either through park or hiking trail
transit	trn	IMapElementStyle	Icon representing a bus stop, train stop, airport, etc.
transitBuilding	tb	IMapElementStyle	A transit building.
transportation	trs	IMapElementStyle	Lines that are part of the transportation network (roads, trains, ferries, etc.)
unpavedStreet	us	IMapElementStyle	An unpaved street.
vegetation	vg	IMapElementStyle	Forests, grassy areas, etc.
volcanicPeak	vp	IMapElementStyle	Icon representing the peak of a volcano.
water	wt	IMapElementStyle	Anything that looks like water.
waterPoint	wp	IMapElementStyle	Icon representing a water feature location such as a waterfall.
waterRoute	wr	IMapElementStyle	Ferry route lines

IMapElementStyle Object

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

JSON Name	URL Param	Type	Description
fillColor	fc	string	Color used for filling polygons, the background of point icons, and for the center of lines if they have split.
labelColor	lbc	string	The color of a map label.
labelOutlineColor	loc	string	The outline color of a map label.
labelVisible	lv	boolean	Species if a map label type is visible or not.
strokeColor	sc	string	Color used for the outline around polygons, the outline around point icons, and the color of lines.
visible	v	boolean	Specifies if the map element is visible or not.

IBorderedMapElementStyle Object

Extends the IMapElementStyle object.

JSON Name	URL Param	Type	Description
borderOutlineColor	boc	string	Secondary/casing line color of the border of a filled polygon.
borderStrokeColor	bsc	string	Primary line color of the border of a filled polygon.
borderVisible	bv	boolean	Specifies if a border is visible or not.

ISettingStyle Object

Defines the global settings that can be set.

JSON Name	URL Param	Type	Description
landColor	lc	string	A color value that all land is first flushed to before things are drawn on it.
shadedReliefVisible		boolean	Specifies whether or not to draw elevation shading on the map.

Map Element Style Hierarchy

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

Known Limitation

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.

Custom Map Style Samples

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

    {
        "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

Share via

Custom Map Styles in Bing Maps V8 and REST Services

Custom Map Styles in the Bing Maps V8 Web Control

Custom Map Styles in the REST and Tile Services

Style Objects

ICustomMapStyle Object

IMapElements Object

IMapElementStyle Object

IBorderedMapElementStyle Object

ISettingStyle Object

Map Element Style Hierarchy

Known Limitation

Custom Map Style Samples

Midnight Commander Style

Countries Only Style

Faded Map Style

Additional resources

Share via

Custom Map Styles in Bing Maps V8 and REST Services

Custom Map Styles in the Bing Maps V8 Web Control

Custom Map Styles in the REST and Tile Services

Style Objects

ICustomMapStyle Object

IMapElements Object

IMapElementStyle Object

IBorderedMapElementStyle Object

ISettingStyle Object

Map Element Style Hierarchy

Known Limitation

Custom Map Style Samples

Midnight Commander Style

Countries Only Style

Faded Map Style

Related Resources

Additional resources