Maps

Note
All maps-service APIs have been deprecated since Tizen 8.0 and will be removed after two releases without any alternatives.

Map service features include geocoding, reverse geocoding, place searching, route calculation, and view widgets.

The main features of Tizen.Maps namespace include the following:

Discovering and selecting a map provider

You can also specify basic map preferences.
Geocoding and reverse geocoding

You can get the geocode (geographical coordinates) of a place from an address, or the reverse geocode (address) from the geographical coordinates (latitude and longitude).
Searching places

You can query place information, corresponding to specified search keys and filters.
Searching routes

You can query a route that defines a path between a start and destination point, passing optionally through specific intermediate locations and calculated using a specified transportation method.
Managing a map view widget

With the map view widget feature, you can create a map view widget and set various properties (such as theme, language, and traffic).

You can create objects, such as markers, polylines, and polygons, in the widget. You can also receive responses about events over the widget, and get various data from the events. You can also customize service requests.

The following map providers are supported:

HERE Maps based on the HERE REST APIs.

To use the HERE Maps, set the provider name to “HERE” and get the HERE API keys.

Note
To use the map service, you must get an access key to the map provider from the provider developer site. The service must be used according to the provider’s Terms of Use.

Geocodes

The following geocode request types are provided:

Get place coordinates from a free text address.
Get place coordinates from a free text address within a specified geographical area.
Get place coordinates from a structured address (a structure with fields, such as city, street, and building number).

After performing the geocode service request, you receive the geocode response, which is a geographical location, specified with latitude and longitude values.

Only 1 type of reverse geocode request is provided:

Get a structured address from place coordinates.

You can parse the reverse geocode response to use its details. The response contains structured address information consisting of, for example, a street name, building number, city name, postal code, district name, state name, and country.

Place search

The following place search request types are provided:

Query place information within a specific distance around a specified geographical location.
Query place information within a specified geographical area.
Query place information from a free text address within a specified geographical area.

After performing the place service request, you receive the place search response. You can parse the place search response to use its details. The response contains structured place information consisting of, for example, a place ID, name and URL, address, geographical location and distance from the center of the search area, place category, rating, review, and image.

Note
Depending on the map provider, some types of place information can be unavailable.

Route search

The following route search request types are provided:

Query a route from a starting point to a destination specified as a geographical location.
Query a route passing through a number of geographical locations.

After performing the route service request, you receive the route search response. You can parse the route calculation response to use its details. The response contains structured route information consisting of, for example, a route ID, geographical coordinates of the start and destination points, route bounding box, transportation mode, and total distance and duration.

Note
Depending on the map provider, the route can be presented as a list of geographical points or segments. The segment list can also be presented as a list of geographical points or maneuvers.

The map view widget feature includes drawing a map image on the map port, which is a specified rectangular area of the map application UI.

With the widget, you can do the following:

Show, move, and resize the widget.
Set the map view widget theme.
Enable a 3D building.
Enable traffic information.
Enable a scalebar.
Set a language for the widget.

You can create objects in the widget. The following view object types are provided:

Marker based on a specified geographical location, image, and marker type.
Polyline based on specified geographical locations, color, and width.
Polygon based on specified geographical locations and color.

The object properties can be changed after the object has been created.

The map view and map object can handle events. Each object has handlers to invoke callbacks for selected events of the Tizen.Maps.MapObject and Tizen.Maps.MapView classes. The events of each handler are described below:

Gestures
- Tizen.Maps.MapView.Scrolled: Scroll gesture is detected over the widget.
- Tizen.Maps.MapView.TwoFingerZoomed: Two-finger zoom gesture is detected over the widget.
- Tizen.Maps.MapView.Clicked: Click gesture is detected over the widget.
- Tizen.Maps.MapView.DoubleClicked: Double-click gesture is detected over the widget.
- Tizen.Maps.MapView.TwoFingerClicked: Two-finger click gesture is detected over the widget.
- Tizen.Maps.MapView.TwoFingerRotated: Two-finger rotation gesture is detected over the widget.
- Tizen.Maps.MapView.LongPressed: Long-press gesture is detected over the widget.
Others
- Tizen.Maps.MapView.ViewReady: Map view widget is ready.

Note
To use the map view on Xamarin.Forms, use Xamarin.Forms.Maps.

Prerequisites

To enable your application to use the map service functionality, follow the steps below:

To use the Tizen.Maps namespace, the application has to request permission by adding the following privileges to the tizen-manifest.xml file:


                XML
                
                    Copy
                    
                
            
<privileges>
   <privilege>http://tizen.org/privilege/mapservice</privilege>
   <privilege>http://tizen.org/privilege/internet</privilege>
   <privilege>http://tizen.org/privilege/network.get</privilege>
</privileges>

To use the methods and properties of the Tizen.Maps namespace, include it in your application:


                C#
                
                    Copy
                    
                
            
using Tizen.Maps;

Start the map service

To start using the map service, follow the steps below:

The Tizen.Maps.MapService instance relies on a particular map provider. To get a list of available map providers, use the Providers property of the Tizen.Maps.MapService class:


                C#
                
                    Copy
                    
                
            
var providerList = MapService.Providers;

foreach (var provider in providerList)
{
    Log.Info("Tizen.Maps", $"Available Provider Name = {provider}");
}

Create a Tizen.Maps.MapService class instance using the provider name and provider key issued by the map provider:


                C#
                
                    Copy
                    
                
            
var maps = new MapService("MAPS_PROVIDER_NAME", "Your-Maps-Provider-Key");

You must make sure that the device user has consented to allow the map provider to use their location information. Depending on the map provider, a UI window to get user consent can be shown on the screen.

If the consent request returns false, you cannot use most of the methods and properties of the Tizen.Maps namespace:


                C#
                
                    Copy
                    
                
            
bool isConsented = await maps.RequestUserConsent();
Log.Info("Tizen.Maps", $"User consent = {isConsented}");

Check which services are supported by the selected map provider using the IsSupported() method of the Tizen.Maps.MapService class:


                C#
                
                    Copy
                    
                
            
/// Check whether routing is available
bool isRoutingSupported = maps.IsSupported(ServiceRequestType.SearchRoute);

/// Check whether routing through specified waypoints is available
bool isRoutingWaypointsSupported = maps.IsSupported(ServiceRequestType.SearchRouteWithWaypoints);

To check for the availability of other services, follow the same approach using the keys from the Tizen.Maps.ServiceRequestType enumerator.

Optionally, check which data features are available for the desired services using the same IsSupported() method:


                C#
                
                    Copy
                    
                
            
/// Check whether route path data is supported
bool isRoutePathSupported = maps.IsSupported(ServiceData.RoutePath);

/// Check whether segment path data is supported
bool isRouteSegmentsPathSupported = maps.IsSupported(ServiceData.RouteSegmentsPath);

/// Check whether segment maneuver data is supported
bool isRouteSegmentsManeuversSupported = maps.IsSupported(ServiceData.RouteSegmentsManeuvers);

To check the availability of other data features, follow the same approach using the keys from the Tizen.Maps.ServiceData enumerator.

Use geocode and reverse geocode services

To retrieve a geocode of a specified place, or the place information corresponding to given geographic coordinates, use one of the following approaches. The service requests can be customized.

To retrieve a geocode, follow the steps below:

To retrieve a geocode, use a string of free-formed address for the CreateGeocodeRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreateGeocodeRequest("Seoul, Seoul R&D Campus");
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", result.ToString());
    }
}
catch (Exception e)
{
    /// Error handling
}

To retrieve a geocode inside a specified area, use a string and an instance of the Tizen.Maps.Area object for the CreateGeocodeRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var area = new Area(new Geocoordinates(12.980260, 77.60653), new Geocoordinates(12.96738, 77.697405));
    var request = maps.CreateGeocodeRequest("Bangalore", area);
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", result.ToString());
    }
}
catch (Exception e)
{
    /// Error handling
}

To retrieve places specified as a structured address, use an instance of the Tizen.Maps.PlaceAddress object for the CreateGeocodeRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var address = new PlaceAddress
    {
        Building = "Ub City", City = "Bengaluru", PostalCode = "560025", Country = "India"
    };
    var request = maps.CreateGeocodeRequest(address);
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", result.ToString());
    }
}
catch (Exception e)
{
    /// Error handling
}

To retrieve a reverse geocode, follow the steps below:

To retrieve a reverse geocode of specified geographic coordinates, use latitude and longitude for the CreateReverseGeocodeRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreateReverseGeocodeRequest(12.975491, 77.697182);
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", result.ToString());
    }
}
catch (Exception e)
{
    /// Error handling
}

To retrieve reverse geocodes of specified multiple geographic coordinates, use the CreateMultiReverseGeocodeRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreateMultiReverseGeocodeRequest(new List<Geocoordinates>
    {
        new Geocoordinates(12.975491, 77.697182),
        new Geocoordinates(48.85784, 2.29516),
    });
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", result.ToString());
    }
}
catch (Exception e)
{
    /// Error handling
}

Use the place search service

To search for a place with a diversity of search parameters, use one of the following approaches. The service requests can be customized.

To retrieve places within a specified distance around the center coordinates, use an instance of the Tizen.Maps.Geocoordinates object for the CreatePlaceSearchRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreatePlaceSearchRequest(new Geocoordinates(48.85784, 2.29516), 50);
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", string.Format("Name=\"{0}\", Distance={1}m, Position={2}",
                                             result.Name, result.Distance, result.Coordinates));
    }
}
catch (Exception e)
{
    /// Error handling
}

To retrieve places within a specified geographic boundary, use an instance of the Tizen.Maps.Area object for the CreatePlaceSearchRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreatePlaceSearchRequest(new Area(new Geocoordinates(12.980260, 77.697405), 500));
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", string.Format("Name=\"{0}\", Distance={1}m, Position={2}",
                                             result.Name, result.Distance, result.Coordinates));
    }
}
catch (Exception e)
{
    /// Error handling
}

To retrieve places based on an address within a specified geographic boundary, use a string of free-formed address and an instance of the Area object for the CreatePlaceSearchRequest() method of the Tizen.Maps.MapService object:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreatePlaceSearchRequest("The Taj Mahal Palace", new Area(new Geocoordinates(18.921729, 72.833031), 50));
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", string.Format("Name=\"{0}\", Distance={1}m, Position={2}",
                                             result.Name, result.Distance, result.Coordinates));
    }
}
catch (Exception e)
{
    /// Error handling
}

Use the routing service

To query a route from point A to point B, use one of the following approaches. The service requests can be customized.

To query a route from one set of geographic coordinates to another:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreateRouteSearchRequest(new Geocoordinates(12.975491, 77.697182),
                                                new Geocoordinates(12.990647, 77.687907));
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", $"From={result.Origin}");
        foreach (var path in result.Path)
        {
            Log.Info("Tizen.Maps", $"Path={path.ToString()}");
        }
        Log.Info("Tizen.Maps", $"To  ={result.Destination}");
    }
}
catch (Exception e)
{
    /// Error handling
}

To query a route passing through a specified set of waypoints:


                C#
                
                    Copy
                    
                
            
try
{
    var request = maps.CreateRouteSearchRequest(new Geocoordinates(12.975491, 77.697182),
                                                new Geocoordinates(12.990647, 77.687907));
    request.Waypoints = new List<Geocoordinates>()
    {
        new Geocoordinates(12.985043, 77.691285)
    };
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", $"From={result.Origin}");
        foreach (var path in result.Path)
        {
            Log.Info("Tizen.Maps", $"Path={path.ToString()}");
        }
        Log.Info("Tizen.Maps", $"To  ={result.Destination}");
    }
}
catch (Exception e)
{
    /// Error handling
}

Customize service requests

All map service requests can be customized with additional preferences. Preparing and sending the preference parameter with the service request allows the map provider to generate more accurate results.

To customize the service request, follow the steps below:

The example from using the place search service can be modified as follows to include the customized preferences:


                C#
                
                    Copy
                    
                
            
try
{
    maps.Preferences = new SearchPreference
    {
        MaxResults = 10, Unit = DistanceUnit.Yard
    };
    var request = maps.CreatePlaceSearchRequest("store", new Area(new Geocoordinates(37.5758418, 126.982763), 50));
    var response = await request.GetResponseAsync();
    foreach (var result in response)
    {
        Log.Info("Tizen.Maps", string.Format("Name=\"{0}\", Distance={1} yard(s), Position={2}",
                                             result.Name, result.Distance, result.Coordinates));
    }
}
catch (Exception e)
{
    /// Error handling
}

To prepare preferences for the routing service, use the Tizen.Maps.SearchPreference or Tizen.Maps.IRouteSearchPreference methods.

The example from using the routing service can be modified as follows to include the customized preferences:


                C#
                
                    Copy
                    
                
            
try
{
    maps.Preferences = new SearchPreference
    {
        Mode = TransportMode.Car
    };
    var request = maps.CreateRouteSearchRequest(new Geocoordinates(12.975491, 77.697182),
                                                new Geocoordinates(12.990647, 77.677907));
    var response = await request.GetResponseAsync();
    var route = response.First();
    foreach (var segment in route.Segments)
    {
        foreach (var maneuver in segment.Maneuvers)
        {
            Log.Info("Tizen.Maps", string.Format("Position={0}, Instruction={1} ",
                                                 maneuver.Position, maneuver.Instruction));
        }
    }
}
catch (Exception e)
{
    /// Error handling
}

If your map provider requires any specific preferences, use the Tizen.Maps.SearchPreference class with key-value pairs defined in the appropriate map provider documentation.

Use the map view

To use the map view, follow the steps below:

Before you use the view features, create a Tizen.Maps.MapView instance:


                C#
                
                    Copy
                    
                
            
try
{
    window = new Window("Test");
    mapview = new MapView(window, maps);

    mapview.Resize(w, h - 100);
    mapview.Move(0, 100);
    mapview.Show();
}
catch (Exception e)
{
    /// Error handling
}

To set the map view properties, proceed as follows:

Set the map view type with the MapType property of the Tizen.Maps.MapView class.

For other available types, see the Tizen.Maps.MapTypes enumerator:


                C#
                
                    Copy
                    
                
            
mapview.MapType = MapTypes.Satellite;

Set the 3D building of the map view with the BuildingsEnabled property:


                C#
                
                    Copy
                    
                
            
mapview.BuildingsEnabled = true;

Set the public transit information of the map view with the PublicTransitEnabled property:


                C#
                
                    Copy
                    
                
            
mapview.PublicTransitEnabled = true;

Set the map view traffic information with the TrafficEnabled property:


                C#
                
                    Copy
                    
                
            
mapview.TrafficEnabled = true;

Set the map view scalebar with the ScaleBarEnabled property:


                C#
                
                    Copy
                    
                
            
mapview.ScaleBarEnabled = true;

Set the map view language with the Language property:


                C#
                
                    Copy
                    
                
            
mapview.Language = "en-US";

Note
To check whether a feature is supported, use IsSupported() method of the Tizen.Maps.MapService class with the Tizen.Maps.ServiceData enumerator.

To set the map view location and size, follow as proceeds:

Set the map view location with the Resize() method of the Tizen.Maps.MapView class, inherited from the EvasObject class:


                C#
                
                    Copy
                    
                
            
mapview.Resize(400, 800);

You can also set the location with the Move() method of the Tizen.Maps.MapView class, inherited from the EvasObject class:


                C#
                
                    Copy
                    
                
            
mapview.Move(0, 0);

Set the map view visibility with the Show() method of the Tizen.Maps.MapView class, inherited from the EvasObject class:


                C#
                
                    Copy
                    
                
            
mapview.Show();

Set the map view center with the Center property:


                C#
                
                    Copy
                    
                
            
mapview.Center = new Geocoordinates(37.5758418, 126.982763);

Set the map view orientation with the Orientation property:


                C#
                
                    Copy
                    
                
            
mapview.Orientation = 45.0;

Set the map view zoom level with the ZoomLevel, MinimumZoomLevel, and MaximumZoomLevel properties:


                C#
                
                    Copy
                    
                
            
mapview.ZoomLevel = 12;

Create map view objects

You can create polyline, polygon, and marker objects for the map view.

To create a map view object, follow the steps below:

To create a polyline:


                C#
                
                    Copy
                    
                
            
try
{
    var coordinatesList = new List<Geocoordinates>
    {
        new Geocoordinates(37.15, 126.88), new Geocoordinates(37, 127.12),
        new Geocoordinates(36.523, 127.20)
    };
    var color = new ElmSharp.Color(255, 1, 1);
    var thick = 5;
    Polyline polyline = new Polyline(coordinatesList, color, thick);
}
catch (Exception e)
{
    /// Error handling
}

To create a polygon:


                C#
                
                    Copy
                    
                
            
try
{
    var coordinatesList = new List<Geocoordinates>
    {
        new Geocoordinates(37.15, 126.88), new Geocoordinates(37, 127.12),
        new Geocoordinates(36.85, 126.99), new Geocoordinates(37, 126.79)
    };
    var color = new ElmSharp.Color(50, 200, 50, 128);
    Polygon polygon = new Polygon(coordinatesList, color);
}
catch (Exception e)
{
    /// Error handling
}

To create a marker:


                C#
                
                    Copy
                    
                
            
Pin pin = new Pin(new Geocoordinates(28.64362, 77.19865));
Sticker sticker = new Sticker(new Geocoordinates(28.64362, 77.19865));

To create a marker using a customized image:


                C#
                
                    Copy
                    
                
            
Pin pin = new Pin(new Geocoordinates(28.64362, 77.19865), "image/marker_pin.png");
Sticker sticker = new Sticker(new Geocoordinates(28.64362, 77.19865), "image/marker_sticker.png");

To add a map view object to a map view widget, follow these steps:

Add the object instance to the map view with the Add() method of the Tizen.Maps.MapView class:


                C#
                
                    Copy
                    
                
            
mapview.Add(pin);

When no longer needed, remove the instance with the Remove() method of the Tizen.Maps.MapView class:


                C#
                
                    Copy
                    
                
            
mapview.Remove(pin);

Manage map view events

To handle map view events, follow these steps:


                C#
                
                    Copy
                    
                
            
EventHandler<MapGestureEventArgs> handler = (s, e) =>
{
    Log.Info("Tizen.Maps", $"DoubleClicked={e.Position} {e.Geocoordinates}");
};
mapview.DoubleClicked += handler; /// Double-click gesture is enabled

After the gesture handler is added, the gesture is enabled. Exceptionally, the click gesture is always enabled.

When no longer needed, unset the event handler:


                C#
                
                    Copy
                    
                
            
/// Double-click gesture is disabled, if there is no handler added
mapview.DoubleClicked -= handler;

To handle map object events, follow these steps:


                C#
                
                    Copy
                    
                
            
Pin pin = new Pin(new Geocoordinates(37, 127), s_imagePath);
EventHandler handler = (s, e) => {
    Pin myPin = (Pin)s;
    Log.Info("Tizen.Maps", $"Position={myPin.Coordinates.ToString()}");
};
pin.Clicked += handler;

When no longer needed, unset the event handler:


                C#
                
                    Copy
                    
                
            
/// When the pin object no longer needs to accept click gestures
pin.Clicked -= handler;

To handle map view ready events, follow these steps:


                C#
                
                    Copy
                    
                
            
EventHandler handler = (s, e) =>
{
    Log.Info("Tizen.Maps", "Map view is ready.");
};
mapview.ViewReady += handler;

When no longer needed, unset the event handler:


                C#
                
                    Copy
                    
                
            
/// Map view ready event is disabled
mapview.ViewReady -= handler;

Dependencies
- Tizen 4.0 and Higher

Maps

Geocodes

Place search

Route search

Map view widget

Prerequisites

Start the map service

Use geocode and reverse geocode services

Use the place search service

Use the routing service

Customize service requests

Use the map view

Create map view objects

Manage map view events

Related information