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
.png)
Here is a description of the URI scheme:
bingmaps://?query
In this URI scheme, query is a series of parameter name/value pairs:
¶m1=value1¶m2=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: llvl=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:
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
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 |
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: 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: 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:
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:
Separate multiple collections editor items with tildes (~). If the item you specify contains a tilde, make sure the tilde is encoded as |
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 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.*/ |