Skip To Content ArcGIS for Developers Sign In Dashboard

ArcGIS Runtime SDK for .NET

Format coordinates

This code sample is available for these platforms:
View Sample on GitHub

Format coordinates in a variety of common notations.

Images of format coordinates

Use case

The coordinate formatter can format a map location in WGS84 in a number of common coordinate notations. Parsing one of these formats to a location is also supported. Formats include decimal degrees; degrees, minutes, seconds; Universal Transverse Mercator (UTM), and United States National Grid (USNG).

How to use the sample

Click on the map to see a callout with the clicked location's coordinate formatted in 4 different ways. You can also put a coordinate string in any of these formats in the text field. Hit Enter and the coordinate string will be parsed to a map location which the callout will move to.

How it works

  1. Get or create a MapPoint with a spatial reference.
  2. Use one of the static "to" methods on CoordinateFormatter such as CoordinateFormatter.ToLatitudeLongitude(point, CoordinateFormatter.LatitudeLongitudeFormat.DecimalDegrees, 4) to get the formatted string.
  3. To go from a formatted string to a Point, use one of the "from" static methods like CoordinateFormatter.FromUtm(coordinateString, map.SpatialReference, CoordinateFormatter.UtmConversionMode.NorthSouthIndicators).

Relevant API

  • CoordinateFormatter
  • CoordinateFormatter.LatitudeLongitudeFormat
  • CoordinateFormatter.UtmConversionMode

Tags

convert, coordinate, decimal degrees, degree minutes seconds, format, latitude, longitude, USNG, UTM

Sample Code

<UserControl
    x:Class="ArcGISRuntime.UWP.Samples.FormatCoordinates.FormatCoordinates"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:esriUI="using:Esri.ArcGISRuntime.UI.Controls">
    <UserControl.Resources>
        <Style TargetType="TextBlock">
            <Setter Property="VerticalAlignment" Value="Center" />
            <Setter Property="FontWeight" Value="SemiBold" />
            <Setter Property="HorizontalAlignment" Value="Right" />
            <Setter Property="Margin" Value="0,5,5,0" />
        </Style>
        <Style TargetType="TextBox">
            <Setter Property="Margin" Value="0,5,0,0" />
            <Setter Property="TextWrapping" Value="Wrap" />
            <Setter Property="Width" Value="210" />
        </Style>
    </UserControl.Resources>
    <Grid>
        <esriUI:MapView x:Name="MyMapView" />
        <Border Style="{StaticResource BorderStyle}">
            <Grid>
                <Grid.RowDefinitions>
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                </Grid.RowDefinitions>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="*" />
                    <ColumnDefinition Width="Auto" />
                </Grid.ColumnDefinitions>
                <TextBlock
                    Text="Tap on the map to see the coordinates in each format. Update any value and tap 'Recalculate' to see the updated coordinates."
                    Grid.Row="0" Grid.Column="0" Grid.ColumnSpan="2"
                    Margin="0,0,0,5" MaxWidth="400"
                    HorizontalAlignment="Stretch"
                    TextWrapping="Wrap" />
                <TextBlock Text="Decimal Degrees:"
                           Grid.Row="1" Grid.Column="0" />
                <TextBox x:Name="DecimalDegreesTextField"
                         Grid.Row="1" Grid.Column="1"
                         Tag="Decimal Degrees" />
                <TextBlock Text="DMS:"
                           Grid.Row="2" Grid.Column="0" />
                <TextBox x:Name="DmsTextField"
                         Grid.Row="2" Grid.Column="1"
                         Tag="Degrees, Minutes, Seconds" />
                <TextBlock Text="UTM:"
                           Grid.Row="3" Grid.Column="0" />
                <TextBox x:Name="UtmTextField"
                         Grid.Row="3" Grid.Column="1"
                         Tag="UTM" />
                <TextBlock Text="USNG:"
                           Grid.Row="4" Grid.Column="0" />
                <TextBox x:Name="UsngTextField"
                         Grid.Row="4" Grid.Column="1"
                         Tag="USNG" />
                <Button Content="Recalculate"
                        Grid.Row="5" Grid.Column="0" Grid.ColumnSpan="2"
                        HorizontalAlignment="Stretch"
                        Margin="0,5,0,0"
                        Click="RecalculateFields" />
            </Grid>
        </Border>
    </Grid>
</UserControl>
// Copyright 2018 Esri.
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
// You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
// language governing permissions and limitations under the License.

using Esri.ArcGISRuntime.Geometry;
using Esri.ArcGISRuntime.Mapping;
using Esri.ArcGISRuntime.Symbology;
using Esri.ArcGISRuntime.UI;
using System;
using System.Drawing;
using Windows.UI.Popups;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;

namespace ArcGISRuntime.UWP.Samples.FormatCoordinates
{
    [ArcGISRuntime.Samples.Shared.Attributes.Sample(
        name: "Format coordinates",
        category: "Geometry",
        description: "Format coordinates in a variety of common notations.",
        instructions: "Click on the map to see a callout with the clicked location's coordinate formatted in 4 different ways. You can also put a coordinate string in any of these formats in the text field. Hit Enter and the coordinate string will be parsed to a map location which the callout will move to.",
        tags: new[] { "USNG", "UTM", "convert", "coordinate", "decimal degrees", "degree minutes seconds", "format", "latitude", "longitude" })]
    public partial class FormatCoordinates
    {
        // Hold a reference to the text that was selected last
        private TextBox _selectedTextField;

        public FormatCoordinates()
        {
            InitializeComponent();

            Initialize();
        }

        private void Initialize()
        {
            // Set the initial selected text
            _selectedTextField = DecimalDegreesTextField;

            // Create the map
            MyMapView.Map = new Map(Basemap.CreateNavigationVector());

            // Add the graphics overlay to the map
            MyMapView.GraphicsOverlays.Add(new GraphicsOverlay());

            // Create the starting point
            MapPoint startingPoint = new MapPoint(0, 0, SpatialReferences.WebMercator);

            // Update the UI with the initial point
            UpdateUIFromMapPoint(startingPoint);

            // Subscribe to text change events
            UtmTextField.TextChanged += InputTextChanged;
            DmsTextField.TextChanged += InputTextChanged;
            DecimalDegreesTextField.TextChanged += InputTextChanged;
            UsngTextField.TextChanged += InputTextChanged;

            // Subscribe to map tap events to enable tapping on map to update coordinates
            MyMapView.GeoViewTapped += (sender, args) => { UpdateUIFromMapPoint(args.Location); };
        }

        private void InputTextChanged(object sender, TextChangedEventArgs e)
        {
            // Keep track of the last edited field
            _selectedTextField = (TextBox)sender;
        }

        private void UpdateUIFromMapPoint(MapPoint selectedPoint)
        {
            try
            {
                // Check if the selected point can be formatted into coordinates.
                CoordinateFormatter.ToLatitudeLongitude(selectedPoint, LatitudeLongitudeFormat.DecimalDegrees, 0);
            }
            catch (Exception e)
            {
                // Check if the excpetion is because the coordinates are out of range.
                if (e.Message == "Invalid argument: coordinates are out of range")
                {
                    // Set all of the text fields to contain the error message.
                    DecimalDegreesTextField.Text = "Coordinates are out of range";
                    DmsTextField.Text = "Coordinates are out of range";
                    UtmTextField.Text = "Coordinates are out of range";
                    UsngTextField.Text = "Coordinates are out of range";

                    // Clear the selectionss symbol.
                    MyMapView.GraphicsOverlays[0].Graphics.Clear();
                }
                return;
            }

            // Update the decimal degrees text
            DecimalDegreesTextField.Text =
                CoordinateFormatter.ToLatitudeLongitude(selectedPoint, LatitudeLongitudeFormat.DecimalDegrees, 4);

            // Update the degrees, minutes, seconds text
            DmsTextField.Text = CoordinateFormatter.ToLatitudeLongitude(selectedPoint,
                LatitudeLongitudeFormat.DegreesMinutesSeconds, 1);

            // Update the UTM text
            UtmTextField.Text = CoordinateFormatter.ToUtm(selectedPoint, UtmConversionMode.NorthSouthIndicators, true);

            // Update the USNG text
            UsngTextField.Text = CoordinateFormatter.ToUsng(selectedPoint, 4, true);

            // Clear existing graphics overlays
            MyMapView.GraphicsOverlays[0].Graphics.Clear();

            // Create a symbol to symbolize the point
            SimpleMarkerSymbol symbol = new SimpleMarkerSymbol(SimpleMarkerSymbolStyle.X, Color.Yellow, 20);

            // Create the graphic
            Graphic symbolGraphic = new Graphic(selectedPoint, symbol);

            // Add the graphic to the graphics overlay
            MyMapView.GraphicsOverlays[0].Graphics.Add(symbolGraphic);
        }

        private async void RecalculateFields(object sender, RoutedEventArgs e)
        {
            // Hold the entered point
            MapPoint enteredPoint = null;

            // Update the point based on which text sent the event
            try
            {
                switch (_selectedTextField.Tag.ToString())
                {
                    case "Decimal Degrees":
                    case "Degrees, Minutes, Seconds":
                        enteredPoint =
                            CoordinateFormatter.FromLatitudeLongitude(_selectedTextField.Text, MyMapView.SpatialReference);
                        break;

                    case "UTM":
                        enteredPoint =
                            CoordinateFormatter.FromUtm(_selectedTextField.Text, MyMapView.SpatialReference, UtmConversionMode.NorthSouthIndicators);
                        break;

                    case "USNG":
                        enteredPoint =
                            CoordinateFormatter.FromUsng(_selectedTextField.Text, MyMapView.SpatialReference);
                        break;
                }
            }
            catch (Exception ex)
            {
                // The coordinate is malformed, warn and return
                await new MessageDialog(ex.Message, "Invalid format").ShowAsync();
                return;
            }

            // Update the UI from the MapPoint
            UpdateUIFromMapPoint(enteredPoint);
        }
    }
}