In the earliest version of the application, I was using a hard
coded location (Pariser Platz in Berlin) for the search, however this made the
application quite useless, unless you were looking for places near Pariser
Platz.

So GPS Positioning was the first of the things that I thought of improving
after the Meeting Point application was more or less working.
The idea was to use the phone GPS to get the current location of the phone, and
then start every search for places in this current position.

To achieved that we needed two things:

- The geolocation  API of platform services

- The searchCenter property of the SearchBox.

The idea was pretty simple, we just had to get the position
using the API, put it in the right format and give it to the SearchBox, using
it’s searchCenter attribute. The following code does all this:

var position
= {latitude: 52.516274,longitude: 13.377678}; //default position is Berlin

// callback function for geolocation.
function fillPositionFromGPS(pos)
{
    //
position coordinates
    var
lng = pos.coords.longitude;
    var
lat = pos.coords.latitude;
       position
= {  latitude: lat, longitude: lng };
       alert("geolocation set
to: "+lng+"  ; "+lat);
}

function getPosition()
{     
       try
       {

              so
= nokia.device.load("geolocation");
              try {
                  // timeout at
60000 milliseconds (60 seconds)
                  var
options = {timeout:60000};
                  // get the
current position
                  so.getCurrentPosition(fillPositionFromGPS, errorCB, options);
              }
              catch(e) {
                  alert(extraDebug(e));
              }
       }
       catch(e){
              alert("cannot load geolocation service"+extraDebug(e));
       }
}

var sb
= new
nokia.places.SearchBox({
         targetNode: ‘searchContainer’,
         template: ‘nokia.mobileHTML5.searchbox’,
         locale: ‘en-gb’,
         suggestions: {
             showAddress: true
         },
         searchCenter: function
() {
             return position;
         },
         onResults: onResults
});

You can see that, in case the geolocation
doesn’t work or while we are waiting for an answer (as it’s an asynchronous
call we are doing), we are positioned by default in Berlin.
Note also that we can’t pass the position attribute directly to the SearchBox
searchCenter, we need a function that returns an object with the position
coordinates.
Both the geolocation API and the Places API use the coordinates in
international system. So everything just fits perfectly and we don’t have to
worry about any conversion.

If you went through the developer’s guide, you might have
come across two types of JavaScript objects, they can cause a little bit of
confusion, especially the ones with the same name (like the two Place objects), although they are in different namespaces. So let’s
take a look at the two types:

Headless API
objects : They are the ones with the information (the data) that
will be displayed. There are mainly three of them: Place,
Media
and Review.

And you’ll receive them as jSon objects, so when you read something about data,
or about a jSon object we are referring to one of these objects.

In the documentation you can see other objects in the
Headless API, but they are essentially combinations of these three.

Now that we know them, let’s use them:

This piece of code will put the names of every place we get
from the search. The search will be run around the searchCenter (Berlin in this
case), and with the term that we provide (pizza in this case). You can change
the location and search term as you please.

<div id="results"></div>

<script>

        var term="pizza";

        var searchCenter = {

                    latitude: 52.516274,

                    longitude: 13.377678

                }; //Berlin   

        nokia.places.searchManager.findPlaces({

            searchTerm: term,

            onComplete: function(data, status){

                // data is an array of searchResult objects

                var content = "<ul>";

                for(i in data.results)

                        content+=
"<li>"+
data.results[i].place.name;

                content+="</ul>";

                document.getElementById("results").innerHTML=content;

            },

            searchCenter: searchCenter

        });

</script>

Like it’s said on the documentation the search
results are just an array of objects with two elements in each object:  distance, and the previously mentioned Place
object, that holds the information for each place that the search has found.
As you saw the headless API just gives you the raw data, so the format and
behavior of the final web page had to be coded by us, although in this example
it was only adding a list of names, you can complicate it as much as you want.

Finally we can take a look at the Place object. But rather
than looking through the documentation sometimes is better to “see” the object
for yourself.

To see an example of the place
object use the “load data” on the Headless
API data fetch example and you will see the full detail of the object
corresponding to the headless API Place object.

In my case this headless data fetch example has been
surprisingly useful, it can ever be faster than using the console.log on
firebug, and setting a break point, I hope you’ll find it useful too.

The other type of JavaScript objects are the UI Widgets:

UI
Widgets: these objects are in charge of rendering. Essentially, they will
render (the data) somewhere in your web page (target element) ,
and they will do it in a certain way (template).

UIWidget ->  RENDER (data,
target, template);

The data will be one of the previously mentioned Headless
API objects.

The target can be any html element.

The template might be the more confusing thing here. It is
used to tell the widget how to render the data, by “how to” meaning the html
structure that will show up in the final web page.

There are three of them: Place,
PlaceList
and Searchbox.
And are the ones that you see all the time declared in the getting started and
developer’s guide examples. A note: actually each one is a subclass of the  Widget object.

As I told you before, we have two kinds of place objects, so
it’s important to know if we’re dealing with the headless API object or the UI
Widget in order to avoid confusion.
Here are examples of definition for both Place objects:

Headless API:

var pp = new nokia.places.objects.Place();

UI Widget:

var pp = new nokia.places.Place ({       
   targetNode: 'detail',       
   template: 'reviewsAndGallery',       
   events: [  
           {
               rel: 'eventGal',
               name: 'click',
               handler: function (jsonObj) {pp.setPlaceId(jsonObj.placeId);}
           }      
    ]
});

Usually you’ll only need to declare the UI Place Widget
objects, because the Headless API Place objects will be given to you by the
Headless API.

The first day in my Nokia internship was also my first contact with Places API, and my task was to use
the first week to “get to know each other”, so that’s what I did. The best way
to achieve it is to read both, the getting
started guide and the developer’s guide,
this last one at least until the attributes section, the following parts you
can leave them for later, when you get more familiar with the API.

After a first glance in the documentation you can see that
there are two big parts in the Places API:
The first is called the “Headless API”some
functions to access the Nokia servers and make searches and queries and for the
raw information about places.

The second are the templates:
the cool stuff! With them you can put everything that the API has quick and
easily in your web page, and it will look really nice! Well, more or less quick
an easy, we’re not talking about drag and drop here. It’s more like copy-paste
the code, then do some small tweaking and “voilà”!
To do that, you don’t need much, in my first contact I had this in my pocket: a
basic level of html, a very basic level of css, and almost 0 level on
javascript. And I managed pretty much everything. Although I have to say, that
due to my lack of javascript when I wanted to do more complicated things than
the ones in the developer’s guide, I advanced very slowly.
So don’t be scared, you don’t need to learn a whole new programming language to
use the API, apart from the basic web knowledge (html+css+javascript), you just
need to get familiar with this thing called “templates” and its “attributes”
and you’re ready to go.

If you decide to start with Places API, my advice is that
when following the developer’s guide, you shouldn’t just read it, but also copy
the code examples in your own test webpage to see that is working. You don’t
need to download anything to use the API, just a web browser and internet
connection is enough.

Some examples will require you to make small changes in the
code to make them work. For example in the “A
custom template”  section, to use the
custom template you will need this piece of code:

var place = new nokia.places.Place({
    template: "myTemplate",
    targetNode: "renderMyTemplateHereId"
});

place.setData (object); 

<script id="myTemplate" type="text/template">

<div>
    <p fill="{name}"></p>
    <p fill="{fullAddress()}"></p>

    <ul each="{media[supplier.name=='orange']}">

      <li fill="{URL}"></li>
    </ul>

</div>
</script>

But, for it to work you need to declare the object variable
used in place.setData (object).You
can just use the object defined at the beginning of the section, like this:

var object = {
    name: 'Le Marfil',
    contact: {

        description: 'Home away from home'
    },
    location: {
        address: {
        …
};

Or you could also use some standard place object. To do that
change the

		place.setData(object);

For the following line:

      place.setPlaceId('250u09tv-fc09ac6bdbe340e9b5e2ad78efc814d0');

That will get an object with all the place information, you
can change the placeId with any other valid one of your liking (get them here).

As you see, it’s with small tweaking like that you and the
API will start to “get to knodw each other”