URI scheme for the Windows Maps app

  • [アーティクル]

The Maps app that is included with Windows 10, Windows 8.1, and Windows 8 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 traffic information and detailed aerial imagery.

Note  In Windows 10, you can use this URI scheme to display aerial 3D imagery and street-level views in the Maps app.

 

The URI scheme

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

bingmaps:?cp=40.726966~-74.006076

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

Parameter Definition ABNF Definition and Example Details

cp

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

q

Query Term

q = "q=" qval

qval = whereval / "~"

Example:

q=mexican%20restaurants

Search term for local business or category of businesses.

lvl

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

sty

Style

sty = "sty=" ("a" / "r"/"3d")

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.
  • 3d: Display a 3D view of the map. Use in conjunction with the cp parameter and optionally with the rad parameter. [The 3d parameter value applies to Windows 10 only]
Note  Omitting the sty parameter produces the same results as sty=r.
 

rad

Radius

rad = "rad=" 1*8DIGIT

Example:

rad=1000

A circular area that specifies the desired map view. The radius value is measured in meters. [The rad parameter applies to Windows 10 only]

ss

Streetside

ss = "ss=" BIT

Example:

ss=1

Indicates that street-level imagery is shown when ss=1. Omitting the ss parameter produces the same result as ss=0. Use in conjunction with the cp parameter to specify the location of the street-level view. [The ss parameter applies to Windows 10 only]

Note  Street-level imagery is not available in all regions.
 

trfc

Traffic

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.

rtp

Route

rtp = "rtp=" (waypoint "~" [waypoint]) / ("~" waypoint)

waypoint = (("pos." cpval ["_" whereval]) / ("adr." whereval))

Examples:

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

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

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 pre-populated in the From field with focus.

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

Note  In Windows 10, a title can be used for a location if the location is specified by the pos parameter value. Rather than showing the latitude and longitude, the title will be displayed.
 

mode

Route mode

mode = "mode=" ("d" / "t" / "w")

Example:

mode=d

Defines the route mode. Valid values for this parameter include:

  • d: Displays route overview for driving directions
  • t: Displays route overview for transit directions
  • w: Displays route overview for walking directions

Use in conjunction with the rtp parameter for route directions. [The mode parameter applies to Windows 10 only]

collection

Collection

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.

point

Point

point = "point." pointval_title_notes_link URL_photo URL

pointval = degreeslat "_" degreeslon

title = whereval / _

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

name

Name

name = "name." whereval

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

You can open the Maps app without using any parameters, as shown here.

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

 

CP parameter samples

The cp parameter specifies a center point.

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:?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:?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 */

 

BB parameter samples

The bb parameter specifies a bounding box.

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

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 Seattle even though the bb was specified because bb is ignored when both cp+lvl are provided. */

 

WHERE parameter sample

The where parameter specifies a location, landmark, or place.

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

 

Q parameter sample

The q parameter specifies a query term.

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

 

LVL parameter sample

The lvl parameter specifies a zoom level.

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

 

RTP parameter samples

The rtp parameter specifies a route.

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 */

 

COLLECTION parameter samples

The collection parameter specifies a collection of entities to be added to the map and list.

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. */

 

Windows 10 parameter samples

The following parameter samples apply to Windows 10 only.

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

bingmaps:?rtp=adr.Mountain%20View,%20CA~adr.San%20Francisco%20International%20Airport,%20CA&mode=w /* Opens the Maps app with walking directions from Mountain View, CA to San Francisco International Airport, CA */

bingmaps:?rtp=adr.Mountain%20View,%20CA~adr.San%20Francisco%20International%20Airport,%20CA&mode=t /* Opens the Maps app with transit directions now from Mountain View, CA to San Francisco International Airport, CA */

bingmaps:?rtp=adr.One%20Microsoft%20Way,%20Redmond,%20WA~pos.45.23423_-122.1232_My%20Picnic%20Spot /* Opens the Maps app with directions from One Microsoft Way, Redmond, WA to My Picnic Spot */

bingmaps://?cp=47.6204~-122.3491&sty=3d /*Opens the Maps app with a 3D view of the Space Needle.*/

bingmaps://?cp=47.6204~-122.3491&ss=1 /*Opens the Maps app with a street-level view of the Space Needle.*/