URI scheme for Bing Maps app

The Bing Maps app that is included with Windows 8 and later can be opened by other Windows apps by using the Uniform Resource Identifier (URI) scheme that is described herein. By providing the appropriate parameters to the URI scheme, apps can display a location or route on a map as well as the results of a location or business search. The URI scheme also provides options to show detailed aerial imagery and traffic information.

The URI scheme

The following URI opens the Bing Maps app and displays a map centered over New York City.

bingmaps:?cp=40.726966~-74.006076

A map centered over New York City

Here is a description of the URI scheme:

bingmaps://?query

In this URI scheme, query is a series of parameter name/value pairs:

&param1=value1&param2=value2 …

The parameters are defined in the Parameters table and examples are provided in Sample URI parameter usage.

Setting the map view

There are several ways to control the map center point and the zoom level. Using cp (center point) and lvl (zoom level) parameters are the most straightforward methods and they produce predictable results. Using bb parameter (specifies an area bounded by latitude and longitude values) is less predictable because it takes into account the screen resolution and determines the map center point and zoom level based on the coordinates provided. The bb parameter is ignored when all three parameters (bb, cp, and lvl) are present.

Performing searches

We recommend when doing a business search using the q parameter, make the terms specific as possible and use it in conjunction with either the cp or the where parameter to specify a location. If the user has not given the Maps app permission to use their location and you do not specify a location for a business search, the search may be performed at the country level and not return meaningful results. Search results are displayed in the most appropriate map view, so unless there is a need to set the lvl (zoom level), we recommend to allow the Maps app to decide.

Collections

Collections are used to show a custom set of points on the map. If there is more than one point, a list of points is displayed. There can be up to 25 points in a collection and they are listed in the order provided. The first one in the list is selected by default. The collection takes precedence over search and directions requests.

Parameters

The syntax for each parameter in this table is shown by using Augmented Backus–Naur Form (ABNF).

ParameterDefinition ABNF Definition and ExampleDetails
cpCenter point

cp = “cp=” cpval

cpval = degreeslat “~” degreeslon

degreeslat = [“-“] 1*3DIGIT [“.” 1*7DIGIT]

degreeslon = [“-“] 1*2DIGIT [“.” 1*7DIGIT]

Example:

cp=40.726966~-74.006076

Both values must be expressed in decimal degrees and separated by a tilde(~).

Valid longitude values are between -180 and +180 inclusive.

Valid latitude values are between -90 and +90 inclusive.

bb Bounding box

bb = "bb=“ southlatitude “_” westlongitude “~” northlatitude “_” eastlongitude

southlatitude = degreeslat

northlatitude = degreeslat

westlongitude = degreeslon

eastlongitude = degreeslon

Example:

bb=39.719_-74.52~41.71_-73.5

A rectangular area that specifies the bounding box expressed in decimal degrees, using a tilde (~) to separate the lower left corner from the upper right corner. Latitude and longitude for each are separated with an underscore (_).

Valid longitude values are between -180 and +180 inclusive.

Valid latitude values are between -90 and +90 inclusive.

where Location

where = “where=” whereval

whereval = 1*( ALPHA / DIGIT / "-" / "." / "_" / pct-encoded / "!" / "$" / "'" / "(" / ")" / "*" / "+" / "," / ";" / “:” / “@” / “/” / “?”)

Example:

where=1600%20Pennsylvania%20Ave,%20Washington,%20DC

Search term which is a location, landmark or place.

qQuery Term

q = “q=” qval

qval = whereval / “~”

Example:

q=mexican%20restaurants

Search term for local business or category of businesses.

lvlZoom Level

lvl = “lvl=” 1*2DIGIT [".“ 1*2DIGIT]

Example:

l

lvl=10.50

Defines the zoom level of the map view. Valid values are 1-20 where 1 is zoomed all the way out.

styStyle

sty = “sty=” (“a” / “r”)

Example:

sty=a

Defines the map style. Valid values for this parameter include:

• a: Display an aerial view of the map.

• r: Display a road view of the map.

Omitting the sty parameter produces the same results as sty=r.

trfcTraffic

trfc = “trfc=” BIT

Example:

trfc=1

Specifies whether traffic information is included on the map. Omitting the trfc parameter produces the same results as trfc=0. Note that Traffic data is not available in all regions.

rtpRoute

rtp = “rtp= (waypoint “~” [waypoint]) / (“~” waypoint)

waypoint = ((“pos.” cpval) / (“adr.” whereval))

Examples:

rtp=adr.Mountain%20View,%20CA~adr.SFO

rtp=adr.One%20Microsoft%20Way,%20Redmond,%20WA~pos.45.23423_-122.1232

Defines the start and end of a route to draw on the map, separated by a tilde (~). Each of the waypoints is defined by either a position using latitude and longitude (cp) or an address identifier (where).

A complete route contains exactly two waypoints. For example, a route with two waypoints is defined by the following: rtp="A"~"B" However, it is acceptable to specify an incomplete route. For example, you can define only the start of a route:

rtp="A"~

In this case, the driving directions input panel is displayed with the provided waypoint in the From: field and the To: field that has focus.

If only the end of a route is specified:

rtp=~"B"

The driving directions panel is displayed with the provided waypoint in the To: field. If location is enabled and with an accurate location fix, My location is prepopulated in the From field with focus.

No route line is drawn when an incomplete route is given.

collectionCollection

collection = “collection=”

Example:

collection=name.Custom%20List

Collection of entities to be added to the map and list.

Supported Entities are:

  • point

Separate multiple collections editor items with tildes (~).

If the item you specify contains a tilde, make sure the tilde is encoded as %7E. If not accompanied by Center point and Zoom Level parameters, the collection will provide the best map view.

pointpoint

point = “point.” pointval_title_notes_link URL_photo URL

pointval = degreeslat “_” degreeslon

title = whereeval / _

Example:

collection=point.40.726966_-74.006076_Pin%20Title

Note  The point parameter is supported for Maps app versions 1.2.0.135 (released in March, 2013) and later.

Specifies a point to add by using latitude and longitude. For points, the value includes the latitude, longitude, title, notes, link URL, and photo URL to display, each separated by an underscore (_):

If the item you specify contains an underscore, make sure the underscore is double encoded as %255F.

Max length of the title and notes parameters is 255 chars.

If a point is defined without a name, the title will be "Custom pin."

namename

name = “name.” whereeval

Example:

collection=name.Hotel%20List

Name of the collection. If a name is not provided and there is more than one entity in the collection, the default name is "Custom pins."

 

Sample URI parameter usage

bingmaps: /* Opens the Maps app centered over the user’s region */

bingmaps:?cp=40.726966~-74.006076 /* Opens the Maps app centered over New York City */

bingmaps:?cp=40.726966~-74.006076&lvl=10 /* Opens the Maps app centered over NYC at zoom level 10 */

bingmaps:?bb=39.719_-74.52~41.71_-73.5 /* Opens the map over NYC using the specified bounding box */

bingmaps:?where=1600%20Pennsylvania%20Ave,%20Washington,%20DC /* Opens the map and searches for an address */

bingmaps:?cp=40.726966~-74.006076&lvl=14.5&q=Pizza /* Opens the Maps app and searches for Pizza over NYC with the map at zoom level 14.5 */

bingmaps:?rtp=adr.One%20Microsoft%20Way,%20Redmond,%20WA%2098052~pos.45.23423_-122.1232 /* Opens the Maps app with driving directions from an address to a position on the map */

bingmaps:?rtp=adr.Mountain%20View,%20CA~adr.San%20Francisco%20International%20Airport,%20CA /* Opens the Maps app with driving directions from a city to a landmark */

bingmaps:?cp=40.726966~-74.006076&trfc=1&sty=a /* Opens the Maps app over NYC with Traffic on and Aerial map style */

bingmaps:?cp=40.726966~-74.006076&lvl=10&where=New%20York /* Opens the Maps app and searches for New York near the specified center point (cp) and shows results at zoom level 10 */

bingmaps:?cp=40.726966~-74.006076&lvl=10&q=coffee /* Opens the Maps app and searches for coffee around that location and sets zoom level 10 to show results */

bingmaps:?q=coffee&where=Omaha /* Opens the Maps app and searches for coffee near Omaha */

bingmaps:?bb=39.719_-74.52~41.71_-73.5&cp=47~-122 /* Opens the Maps app over NYC even though the center point (cp) was specified near Seattle */

bingmaps:?bb=39.719_-74.52~41.71_-73.5&cp=47~-122&lvl=8/* Opens the Maps app over New York even though the cp+lvl was specified because cp+lvl are ignored when bb is provided. */

bingmaps:?collection=point.36.116584_-115.176753_Caesars%20Palace /* Opens the Maps app with a pushpin named Caesars Palace in Las Vegas showing the best map view. */

bingmaps:?collection=point.36.116584_-115.176753_Caesars%20Palace&lvl=16 /* Opens the Maps app with a pushpin named Caesars Palace in Las Vegas and zooms to level 16. */

bingmaps:?collection=point.36.116584_-115.176753_Caesars%20Palace~point.36.113126_-115.175188_The%20Bellagio&lvl=16&cp=36.114902~-115.176669 /* Opens the Maps app with a pushpin named Caesars Palace and a pushpin named The Bellagio in Las Vegas and zooms to level 16.*/

bingmaps:?collection=point.40.726966_-74.006076_Fake%255FBusiness%255Fwith%255FUnderscore /* Opens the Maps app over New York with a pushpin named Fake_Business_with_Underscore.*/

bingmaps:?collection=name.Hotel%20List~point.36.116584_-115.176753_Caesars%20Palace~point.36.113126_-115.175188_The%20Bellagio&lvl=16&cp=36.114902~-115.176669 /* Opens the Maps app with a list named Hotel List and two pushpins for Caesars Palace and The Bellagio in Las Vegas and zooms to level 16. */

 

 

Show:
© 2014 Microsoft