Maps and navigation for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

You can use the new Maps API in Windows Phone 8 to develop map-based apps and to incorporate location and search features. This topic introduces the new map control, map modes, and map views.

Note

The new Maps API in Windows Phone 8 is different from the Bing Maps available in Windows Phone OS 7.1. The Bing Maps control is still supported in Windows Phone 8, but is deprecated. Typically, the only time you should use the Bing Maps control is in an existing app that you have upgraded from Windows Phone OS 7.1 to Windows Phone 8.

For a sample that demonstrates some of the tasks described in this topic, download the Simple Map control sample.

For useful extensions to the Maps API, including a Pushpin, download the Windows Phone Toolkit.

This topic contains the following sections.

• Displaying a Map
• Specifying center and zoom level
• Converting a Geocoordinate to a GeoCoordinate
• Displaying landmarks and pedestrian features
• Setting the cartographic mode
• Setting the color mode
• Setting multiple properties and animating transitions by using map views
• Terms of use for map services
• Related Topics

Displaying a Map

To display a map in your Windows Phone 8 app, use the Map control. For more info, see How to add a Map control to a page in Windows Phone 8.

Important Note:
To use the control, you have to select the ID_CAP_MAP capability in the app manifest file. For more info, see How to modify the app manifest file for Windows Phone 8.

Displaying a Map with XAML

The following code example shows how you can use XAML to display a Map control in your Windows Phone 8 app.

<!--ContentPanel - place additional content here-->
<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <maps:Map />
</Grid>

If you add the control by writing XAML, you also have to add the following xmlns declaration to the phone:PhoneApplicationPage element. If you drag and drop the Map control from the Toolbox, this declaration is added automatically.

xmlns:maps="clr-namespace:Microsoft.Phone.Maps.Controls;assembly=Microsoft.Phone.Maps"

Displaying a Map with code

The following code example shows how you can use code to display a Map control in your Windows Phone 8 app.

using Microsoft.Phone.Maps.Controls;

...

    Map MyMap = new Map();
    ContentPanel.Children.Add(MyMap);

Displaying a Map by using a built-in launcher

This topic describes how to write code that displays a map inside your app. If you simply want to display a map, you can also use the Maps task, which launches the built-in Maps app. For more info, see How to use the Maps task for Windows Phone 8.

The following table lists all the built-in launchers that display or manage maps. For more info about launchers, see Launchers and Choosers for Windows Phone 8.

Launcher	More info
Maps task	Launches the built-in Maps app and optionally marks a location. How to use the Maps task for Windows Phone 8
Maps directions task	Launches the built-in Maps app and displays directions. How to use the Maps directions task for Windows Phone 8
MapDownloader task	Downloads maps for offline use. How to use the MapDownloader task for Windows Phone 8
MapUpdater task	Checks for updates for offline maps that the user has previously downloaded. How to use the MapUpdaterTask for Windows Phone 8

Specifying center and zoom level

One of the first things you may want to do after displaying a map is to set its center and zoom level.

Note

During initialization of the map control, the CenterChanged and the ZoomLevelChanged events are raised one time each after the initialization. If you handle these events, make sure that your code handles this first occurrence correctly when the events are raised after initialization of the control and before any user interaction.

Specifying the center of a map

You can set the center of the Map control by using its Center property. To set the property using XAML, assign a (latitude, longitude) pair to the Center property.

The following code example shows how you can set the center of Map by using XAML.

<!--ContentPanel - place additional content here-->
<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
   <maps:Map x:Name="MyMap" Center="47.6097, -122.3331" />
</Grid>

The following code example shows how can set the center of Map using code.

using Microsoft.Phone.Maps.Controls;
using System.Device.Location;

...

    Map MyMap = new Map();
    MyMap.Center = new GeoCoordinate(47.6097, -122.3331);
    ContentPanel.Children.Add(MyMap);
}

Warning

Don’t use the Latitude property and the Longitude property to set the center of the Map control. Instead, create a new GeoCoordinate object and assign it to the Center property as shown in the preceding code example.

Specifying the zoom level of a map

Use the ZoomLevel property to set the initial resolution at which you want to display the map. ZoomLevel property takes values from 1 to 20, where 1 corresponds to a fully zoomed out map, and higher zoom levels zoom in at a higher resolution. The following code examples show how you can set the zoom level of the map by using the ZoomLevel property in XAML and code.

The following code example shows how you can set the zoom level of the map by using the ZoomLevel property in XAML.

<!--ContentPanel - place additional content here-->
<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
   <maps:Map x:Name="MyMap" Center="47.6097, -122.3331" ZoomLevel="10"/>
</Grid>

The following code example shows how you can set the zoom level of the map by using the ZoomLevel property in code.

using Microsoft.Phone.Maps.Controls;
using System.Device.Location;

...

    Map MyMap = new Map();
    MyMap.Center = new GeoCoordinate(47.6097, -122.3331);
    MyMap.ZoomLevel = 10;
    ContentPanel.Children.Add(MyMap);
}

Converting a Geocoordinate to a GeoCoordinate

The Center property of the Map control requires a value of type GeoCoordinate from the System.Device.Location namespace. If you are using location services from the Windows.Devices.Geolocation namespace, you have to convert a Windows.Devices.Geolocation..::.Geocoordinate value to a System.Device.Location..::.GeoCoordinate value for use with the Map control.

You can get an extension method to do this conversion, along with other useful extensions to the Maps API, by downloading the Windows Phone Toolkit. If you want to write your own code, here is an example of a method that you can use to convert a Geocoordinate to a GeoCoordinate:

using System;
using System.Device.Location; // Contains the GeoCoordinate class.
using Windows.Devices.Geolocation; // Contains the Geocoordinate class.

namespace CoordinateConverter
{
    public static class CoordinateConverter
    {
        public static GeoCoordinate ConvertGeocoordinate(Geocoordinate geocoordinate)
        {
            return new GeoCoordinate
                (
                geocoordinate.Latitude,
                geocoordinate.Longitude,
                geocoordinate.Altitude ?? Double.NaN,
                geocoordinate.Accuracy,
                geocoordinate.AltitudeAccuracy ?? Double.NaN,
                geocoordinate.Speed ?? Double.NaN,
                geocoordinate.Heading ?? Double.NaN
                );
        }
    }
}

Displaying landmarks and pedestrian features

You can also display additional elements on your map, such as landmarks and pedestrian features.

• Landmarks. Set the LandmarksEnabled property to true to display landmarks on a Map control. Landmarks are visible on the map only when the ZoomLevel property is set to a value of 16 or higher.

• Pedestrian features. Set PedestrianFeaturesEnabled to true on a Map control to display pedestrian features such as public stairs. Pedestrian features are visible on the map only when the ZoomLevel property is set to a value of 16 or higher.

The following illustration displays a map with landmarks and pedestrian features.

The following example shows how you can set the PedestrianFeaturesEnabled property and the LandmarksEnabled property in XAML.

<!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <maps:Map Center="47.6097, -122.3331" ZoomLevel="16" LandmarksEnabled="true" PedestrianFeaturesEnabled="true"/>
        </Grid>

The following example shows how to set these properties in code.

using Microsoft.Phone.Maps.Controls;
using System.Device.Location;

...

    Map MyMap = new Map();
    MyMap.Center = new GeoCoordinate(47.6097, -122.3331);
    MyMap.ZoomLevel = 16;
    MyMap.LandmarksEnabled = true;
    MyMap.PedestrianFeaturesEnabled = true;
    ContentPanel.Children.Add(MyMap);
}

Setting the cartographic mode

Once you set the center and zoom level of a map, you You might may also want to set the cartographic mode of the map. The cartographic mode defines the display and the translation of coordinate systems from screen coordinates to world coordinates on the Map control. You can use the CartographicMode property of the Map control to set the cartographic mode of the map. This property takes accepts values from the MapCartographicMode enumeration. The following types of cartographic modes are supported in the MapCartographicMode enumeration:

• Road: displays the normal, default 2-D map.

• Aerial: displays an aerial photographic map.

• Hybrid: displays an aerial view of the map overlaid with roads and labels.

• Terrain: displays physical relief images for displaying elevation and water features such as mountains and rivers.

The following illustration displays the four cartographic modes.

The following example displays a map in the default Road mode. The buttons in the app bar can be used to view the map in Aerial, Hybrid, and Terrain modes.

Note

To test the following sample, you have to create an Images folder in your project and provide images for the app bar buttons.

<!--LayoutRoot is the root grid where all page content is placed-->
<Grid x:Name="LayoutRoot" Background="Transparent">
   <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
   </Grid.RowDefinitions>
   <!--TitlePanel contains the name of the application and page title-->
   <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
      <TextBlock x:Name="ApplicationTitle" Text="Maps" Style="{StaticResource PhoneTextNormalStyle}"/>
      <TextBlock x:Name="PageTitle" Text="map modes" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>
   </StackPanel>
   <!--ContentPanel - place additional content here-->
   <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
      <maps:Map x:Name="MyMap"  Center="13.0810, 80.2740" ZoomLevel="10"/>
   </Grid>
</Grid>
<!--Sample code showing usage of ApplicationBar-->
<phone:PhoneApplicationPage.ApplicationBar>
   <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
      <shell:ApplicationBarIconButton IconUri="/Images/appbar_button1.png" Text="Road" Click="Road_Click"/>
      <shell:ApplicationBarIconButton IconUri="/Images/appbar_button2.png" Text="Aerial" Click="Aerial_Click"/>
      <shell:ApplicationBarIconButton IconUri="/Images/appbar_button3.png" Text="Hybrid" Click="Hybrid_Click"/>
      <shell:ApplicationBarIconButton IconUri="/Images/appbar_button4.png" Text="Terrain" Click="Terrain_Click"/>
   </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

void Road_Click(object sender, EventArgs args)
{
   MyMap.CartographicMode = MapCartographicMode.Road;
}

void Aerial_Click(object sender, EventArgs args)
{
   MyMap.CartographicMode = MapCartographicMode.Aerial;
}

void Hybrid_Click(object sender, EventArgs args)
{
   MyMap.CartographicMode = MapCartographicMode.Hybrid;
}

void Terrain_Click(object sender, EventArgs args)
{
   MyMap.CartographicMode = MapCartographicMode.Terrain;
}

Setting the color mode

You can display the map in a light color mode or a dark mode by using the ColorMode property. The values that this property can take—Light or Dark—is accepts are specified contained in the MapColorMode enumeration. The default is Light.

In the following illustration, the first map is in the Light color mode and the second map is in the Dark color mode.

The following code example displays a map in the default Light mode. The buttons in the app bar can be used to view the map in Light or Dark modes.

Note

To test the following sample, you have to create an Images folder in your project and provide images for the app bar buttons.

<!--LayoutRoot is the root grid where all page content is placed-->
    <Grid x:Name="LayoutRoot" Background="Transparent">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>
        <!--TitlePanel contains the name of the application and page title-->
        <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
            <TextBlock x:Name="ApplicationTitle" Text="Maps" Style="{StaticResource PhoneTextNormalStyle}"/>
            <TextBlock x:Name="PageTitle" Text="color modes" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>
        </StackPanel>
        <!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <maps:Map x:Name="MyMap" />
        </Grid>
    </Grid>
    <!--Sample code showing usage of ApplicationBar-->
    <phone:PhoneApplicationPage.ApplicationBar>
        <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
            <shell:ApplicationBarIconButton IconUri="/Images/appbar_button1.png" Text="Light" Click="Light_Click"/>
            <shell:ApplicationBarIconButton IconUri="/Images/appbar_button2.png" Text="Dark" Click="Dark_Click"/>
        </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

void Light_Click(object sender, EventArgs args)
{
   MyMap.ColorMode = MapColorMode.Light;
}

void Dark_Click(object sender, EventArgs args)
{
   MyMap.ColorMode = MapColorMode.Dark;
}

Setting multiple properties and animating transitions by using map views

A common scenario in map apps is moving from one location in the map to another, or moving from one view to another. A new map view is defined any time the position of the map is changed as a result of panning, zooming, rotating, or tilting.

Use the SetView method to define a map view in code. The parameters that you can pass to the overloads of the SetView method include the center of the view, zoom level, heading, pitch, LocationRectangle, and the kind of animation used to go from one view to another.

SetView parameters

The following list explains the parameters of the SetView method.

• center: Use this parameter to pass the center of the map view. It is defined as a GeoCoordinate object.

• zoomLevel: This parameter represents different levels of detail available on the map. It takes values from 1 to 20. The maximum level of available detail is determined by the location you are zooming into. Some areas can be zoomed in further than other areas. Higher zoom levels represent views in the map that are more zoomed. A zoom level of 1 represents the view that is the most zoomed out.

• heading: This parameter specifies the directional heading that is pointing “up” on the map. It is represented in geometric degrees by a value that is between 0 and 360, indicating the number of degrees to rotate the map. For example, 0 or 360 represents north, 90 represents west, 180 represents south, and 270 represents east. The following diagram illustrates heading.

  

• pitch: This parameter specifies the degree to which the map is tilted. It is represented by a value that is between 0 and 180, indicating the number of degrees to tilt the map. The following diagram illustrates pitch.

  

• boundingRectangle: This parameter represents a LocationRectangle object that contains the Map control.

• animationKind: Use this parameter to set the kind of animation you want the user to see when the view changes. The available animation settings are found in the MapAnimationKind enumeration. If you pass None as the animationKind parameter, then the map snaps to the new view instead of animating the view change.

Animation example

The following example displays a map with default center and zoom level. When you click the Change button in the app bar, it displays a map with a new center and zoom level. When you click the Animate button, the map animates to a new center and zoom level.

<!--LayoutRoot is the root grid where all page content is placed-->
<Grid x:Name="LayoutRoot" Background="Transparent">
   <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
   </Grid.RowDefinitions>

   <!--TitlePanel contains the name of the application and page title-->
   <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
      <TextBlock x:Name="ApplicationTitle" Text="Maps" Style="{StaticResource PhoneTextNormalStyle}"/>
      <TextBlock x:Name="PageTitle" Text="MapView" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>
   </StackPanel>

   <!--ContentPanel - place additional content here-->
   <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
      <maps:Map x:Name="MyMap"  Center="13.0810, 80.2740" ZoomLevel="10"/>
   </Grid>
</Grid>

<!--Sample code showing usage of ApplicationBar-->
<phone:PhoneApplicationPage.ApplicationBar>
   <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
      <shell:ApplicationBarIconButton x:Name="BtnZoom"  IconUri="/Images/appbar_button2.png" Text="Change" Click="OnCenterZoom_Click"/>
      <shell:ApplicationBarIconButton x:Name="BtnCenter"  IconUri="/Images/appbar_button1.png" Text="Animate" Click="OnAnimate_Click"/>
   </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

void OnCenterZoom_Click(object sender, EventArgs args)
{
   MyMap.Center = new GeoCoordinate(47.6097, -122.3331);
   MyMap.ZoomLevel = 18;
}

void OnAnimate_Click(object sender, EventArgs args)
{
   MyMap.SetView(new GeoCoordinate(47.6097, -122.3331), 15, MapAnimationKind.Parabolic);
}

Terms of use for map services

To use map services in your app, you need a map service application ID and a token to include in your app’s code. For more info, see How to add a Map control to a page in Windows Phone 8.

Continued use of map services is governed by the Terms of Use. Microsoft may share with Nokia the developer IDs that are using the map services, because Nokia supplies some of these services.

See Also

Other Resources

How to add a Map control to a page in Windows Phone 8

How to display route and directions on a map in Windows Phone 8

Map control design guidelines for Windows Phone

The Windows Phone Map Control

Portal:Windows Phone Location & Maps

Benchmarking mobile maps