Nokia Places API for Windows Phone

In this post I will demonstrate way to begin using the Nokia RESTful Places API and display places data in your Windows Phone application.

Nokia’s RESTful Places API is a web service API that allows you to offer your application’s users Nokia’s Places service as available in Nokia Maps and other applications within the look & feel of your own application. The Places service supports a variety of use cases that center around two major features:

• Place discovery – Help users find the places relevant to them
• Place information retrieval – Provide detailed information about places users are interested in

 

When you use the Places API to build an application, your users can find individual locations in

• over 200 countries
• over 1.5 million different areas (cities, districts, regions)
• over 25 million streets split into 90 million and more individual segments
• over 120 million point addresses within 15 countries
• over 75 million named and categorized places in more than 200 countries

 

Several million of those places come with rich attribution/content like

• editorial information for trusted content partners like Lonely Planet and Michelin
• ratings, reviews and images aggregated from a variety of online communities
• additional business information, often provided by the owner

In following scenario I will create WP7 app that will explore Nokia Places in your neighborhood, display them as pushpins on Bing Map, and show additional data (like images) on each pushpin tap. But first, in order to use API’s, you have to register as a Nokia Developer and retrieve your API Key. Also, you should register for Bing Maps Account, to submit credential data to your Bing Maps control:

1. Register as a Nokia Developer
2. Register Nokia Places API key
3. Register Bing Maps application

Also, to consume Nokia Places API data you need an HTTP client and some Json framework for data deserialization. In this scenario I used RestSharp and Json.NET, and you can easily download nuget packages from following links:

• RestSharp
• Json.NET

(note: Json.NET was part of RestSharp package, but since version 103, Json.NET was removed from RestSharp as a dependency).

So, in this demo, we will collect current GPS location and ask Nokia Places service for nearby places:

private GeoCoordinateWatcher watcher;
private GeoCoordinate myLocation;
private string nokiaPlacesUrl = "http://demo.places.nlp.nokia.com/places/v1/discover/explore";
private string nokiaPlaceUrl = "http://demo.places.nlp.nokia.com/places/v1/places/";
private string nokiaPlacesAppID = "YOUR_APP_ID";
private string nokiaPlacesAppCode = "YOUR_APP_CODE";
private List<Place> places;
private bool ignoreMapTap = false;

public MainPage()
{
    InitializeComponent();
    watcher = new GeoCoordinateWatcher(GeoPositionAccuracy.High);watcher.PositionChanged += new EventHandler<GeoPositionChangedEventArgs<GeoCoordinate>>(watcher_PositionChanged);
    watcher.Start();
}

private void watcher_PositionChanged(object sender, GeoPositionChangedEventArgs<GeoCoordinate> e)
{
    if (watcher.Status != GeoPositionStatus.Ready) return;
    myLocation = e.Position.Location;
    mapPlaces.SetView(myLocation, 14);
    watcher.Stop();
    this.GetPlaces(myLocation);
}

private void GetPlaces(GeoCoordinate location)
{
    string url = string.Format("{0}?at={1},{2}&app_id={3}&app_code={4}&tf=plain&pretty=true", nokiaPlacesUrl, location.Latitude, location.Longitude, nokiaPlacesAppID, nokiaPlacesAppCode);
    var client = new RestClient(url);
    var request = new RestRequest(string.Empty, Method.GET);
    client.ExecuteAsync<RestRequest>(request, (response) =>
    {
        places = this.ParsePlaces(response.Content);
        this.AddPushpins(places);
    });
}

Resulting Json response from service looks like this:

 

In following method we deserialize result to list of Places objects:

private List<Place> ParsePlaces(string json)
{
    List<Place> places = new List<Place>();
    if (json == string.Empty)
        return places;

    JToken jToken = JObject.Parse(json)["results"]["items"];
    if (jToken == null)
        return places;

    IList<JToken> jlList = jToken.Children().ToList();
    foreach (JToken token in jlList)
    {
        Place place = JsonConvert.DeserializeObject<Place>(token.ToString());

        if (place.type == "urn:nlp-types:place")
        {
            IList<JToken> jTokenListPosition = token["position"].ToList();
            GeoCoordinate position = new GeoCoordinate();
            position.Latitude = double.Parse(jTokenListPosition[0].ToString());
            position.Longitude = double.Parse(jTokenListPosition[1].ToString());
            place.position = position;

            places.Add(place);
        }
    }

    return places;
}

 

Places are added to map in following method:

private void AddPushpins(List<Place> places)
{
    mapPlaces.Children.Clear();

    Pushpin pushpinMe = new Pushpin();
    pushpinMe.Background = new SolidColorBrush(Colors.Green);
    pushpinMe.Location = myLocation;
    pushpinMe.Content = "You";
    mapPlaces.Children.Add(pushpinMe);

    foreach (Place place in places)
    {
        Pushpin pushpin = new Pushpin();
        pushpin.Background = new SolidColorBrush(Colors.Blue);
        pushpin.Opacity = 0.6;
        pushpin.Location = place.position;
        pushpin.Tap += new EventHandler<GestureEventArgs>(pushpin_Tap);
        pushpin.Content = place.title;
        mapPlaces.Children.Add(pushpin);
    }
}

This is how it looks in our app:

When user taps one of pushpins, another call to service is requested.

private void pushpin_Tap(object sender, System.Windows.Input.GestureEventArgs e)
{
    ignoreMapTap = true;
    Pushpin pushpin = (sender as Pushpin);
    Place place = places.Where(p => p.position == pushpin.Location).FirstOrDefault();
    this.DataContext = place;

    stackPanelDetail.Visibility = Visibility.Visible;
    image.Source = null;
    string url = string.Format("{0}{1}?app_id={2}&app_code={3}", nokiaPlaceUrl, place.id, nokiaPlacesAppID, nokiaPlacesAppCode);
    var client = new RestClient(url);
    var request = new RestRequest(string.Empty, Method.GET);
    client.ExecuteAsync<RestRequest>(request, (response) =>
    {
        try {
            string firstImageUrl = JObject.Parse(response.Content)["media"]["images"]["items"].First["src"].ToString();
            image.Source = new BitmapImage(new Uri(firstImageUrl, UriKind.Absolute));
        }
        catch { }
    });
}

 

This call will return place’s details like alternative names, contact phones, fax, emails, websites, categories, rating, images etc (see image below):

In our scenario, we will display place data and first of images in media collection:

Conclusion

You can use Nokia Places API in various scenarios. For example, you can create some kind on City Explorer application and use various data together with Windows Phone platform features like Bing Maps Direction Task, Email Compose Task, Phone Call Task, Share Link Task and Web Browser Task to provide great app experience. Nokia also provide more robust maps services like Nokia Maps, Nokia Directions and Nokia Traffic which can be easily combined with WP Browser control (see Nokia Places API Blog for more information about this integration).

Additional resources and references about Nokia RESTful Places API can be found in following links:

Nokia RESTful Places Overview

Nokia RESTful Places Quick Start

Nokia RESTful Places User Guide

Nokia RESTful Places API Reference

Complete working zip solution can be downloaded from here (don’t forget to put your Bing Maps credentials in MainPage.xaml and nokiaPlacesAppID and nokiaPlacesAppCode in MainPage.xaml.cs).

About these ads