URI Scheme for maps application

The Windows maps application can be launched by other applications that require a location aspect to show the location of an address anywhere in the world, provide directions between 2 points and fulfill a location or business search. Developers can use the optional parameters to extend their applications beyond basic mapping functionality to show detailed aerial imagery or traffic information.

Hier-part component

hier-part = path-empty

Query component

The ABNF for the query component is as follows:

query = parameter *( “&” parameter )

parameter = cp / bb / where / q / lvl / sty / trfc / rtp

ParameterDefinition ABNF Definition and ExampleDetails
cpCenter point

cp = “cp=” cpval

cpval = degreeslon “~” degreeslat

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.

Note  This is supported in version 2.

pointpoint

point = “point.” pointval_title_notes_link URL_photo URL

pointval = degreeslon “_” degreeslat

title = whereeval / _

notes = whereeval / _

link URL = URL / _

photo URL = URL / _

Example:

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

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”

Note  Link url, notes, and photo url are not supported in version 2.

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”.

 

If you invoke the Maps application with no parameters, for example, bingmaps:, it launches the map where the user was last viewing it or if the app was not running, it centers the map at the country level view over the user’s region.

Setting the map view

There are several ways to control the map center point and the zoom level. Using cp and lvl are the most straightforward methods and they produce predictable results. Using bb is less predictable because it takes into account the screen resolution and derives 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 location permissions are not enabled, invoking the protocol with just the q term may result in searches being performed at the country level which may not return meaningful results. Search results are displayed in the most appropriate map view, so unless there is a need to set the lvl, we recommend to allow the application to control the behavior.

Collections

Collections are used to pass a custom set of points that get plotted on the map and are shown in the list if there is more than one point. There can be up to 25 points passed as 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.

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 bounding box of the screen */

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 /* Searches for Pizza over NYC, set the map at zoom level 14.5 to show results */

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 /* Search for New York near CP and show results at zoom level 10 */

bingmaps:?lvl=10&where=New%20York /* Searches for New York and shows the result at zoom level 10 */

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

bingmaps:?q=coffee&where=Omaha /* 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 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 Seattle even though the bb was specified because bb is ignored when both cp+lvl are provided. */

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

bingmaps:?collection=point.36.116584_-115.176753_Caesars%20Palace&lvl=16 /* Opens the Maps app with a point 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 point named Caesars Palace and a point 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 point 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 points for Caesars Palace and The Bellagio in Las Vegas and zooms to level 16. */

 

 

Show:
© 2014 Microsoft. All rights reserved.