Data API

Namespaces and data

It is instructive to look at the Data API from the point of view of the namespaces and data classes involved. To run a search based on a search term, you need functions defined in the namespace nokia.places.search.manager, while the functions in the namespace nokia.places.manager retrieve place details (except for one function that posts place ratings to the back-end server).

Each function in both namespaces takes one argument, which is an object with a number of properties, and each of these input objects includes a property named onComplete. This is because the functions are asynchronous and you need to use onComplete to provide a callback that can receive and process the results (the place data).

The results from searchManager functions (except for getCategories()) are instances of nokia.places.objects.SearchResponseView.

A SearchResponseView has a member element named results, which is an array with elements defined by the class nokia.places.objects.SearchResult.

A member of SearchResult called place is an instance of nokia.places.objects.Place. It contains a place id (placeId) with which you can invoke placeManager functions to obtain specific place data.

Here is a list of the placeManager functions and the types of data they obtain (again via their onComplete functions):

• getPlaceData() –nokia.places.objects.Place
• getMedia() – nokia.places.objects.List, a list of nokia.places.objects.Media
• getReviews() – nokia.places.objects.List, a list of nokia.places.objects.Review
• getRating() – nokia.places.objects.Review
• postRating() – nokia.places.objects.Review

After this quick tour, the following articles offer examples showing how to use the Data API classes to perform searches and then how to obtain the detailed places data.

The last article in this section offers a very brief explanation of what you need to write server-side node.js scripts that make use of the Data API.

Search using a search center

The function findPlaces(), as its name suggests, allows you to search for places. It requires as an argument an object with a number of parameters, among them a search term, an optional searchCenter, and onComplete, whose value is a function that handles the search results when they become available.

Determining a search term is a matter specific to the application. It can be hard-coded, or more realistically, you can base it on user input.

searchCenter is an object that contains the latitude and longitude of a location. It acts as the origin for the search, which runs in increasingly widening circles, trying to match the supplied search term. The returned results, if any, include information about the distance of each item (place) from the search center. Here is an example of the search center object that represents a location in Berlin in Germany:

var searchCenter = {
    latitude: 52.516274,
    longitude: 13.377678
}; //Berlin    

The code below calls findPlaces(), using term as the value of searchTerm (we assume that it is a meaningful text string), an onComplete function (empty) and the search center object we defined earlier.

nokia.places.search.manager.findPlaces({
    searchTerm: term,
    onComplete: function(data, status){
        // handle/process data here
        
    },
    searchCenter: searchCenter
});

Search with geolocation (HTML5)

Browsers that support HTML 5, allow you to share your current location and the findPlaces() supports this via the parameter useGeoLocation. If this parameter is included in the argument to the function and set to true, the user's current location is used as the search center. If searchCenter is not provided and useGeoLocation is not defined or set to false, then a global search is performed.

The code example below demonstrates a call to findPlaces() with useGeoLocation set to true:

nokia.places.search.manager.findPlaces({
    searchTerm: term,
    useGeoLocation: true,
    onComplete: function(data, status){
        // handle/process data here
    }
});

Search with a bounding box

A further possibility is that instead of using a search center or sharing your location you can use a bounding box, which is a rectangular area defined by the coordinates of its top left and bottom right corners. To provide a bounding box, use the parameter boundingBox as shown in the following code:

nokia.places.search.manager.findPlaces({
    searchTerm: term,
    onComplete: function(data, status){
        // handle/process data here
    },
    boundingBox: {
        topLeft: {
            latitude: 52.33812,
            longitude: 13.08835
        },
        bottomRight: {
            latitude: 52.6755,
            longitude: 13.76134
        }
    }
});   

Search by category

This option has to do with Point of Interest categories (POIs) that are defined in the system. You can use the searchManager function getCategories() to obtain a complete up-to-date list of supported categories. If you do, you will get a list of objects, each containing the fields name, categoryId and iconURL. Either name or categoryId can be passed to another nokia.places.search.manager function, findPlacesByCategory() to obtain a list of Place objects representing locations that match the category.

The code below uses a hard-coded category id "eat-drink" to locate restaurants:

nokia.places.search.manager.findPlacesByCategory({
    category: 'eat-drink',
    searchCenter: searchCenter,
    onComplete: function(data, status){
        // handle/process data here
    }
});

The following list shows the names and ids of currently supported categories:

Reverse geo-code search

The API class nokia.places.search.manager offers a method named reverseGeoCode(). A typical use case for it is to retrieve the address of a place on the basis of a set of geographical coordinates. The method is asynchronous, takes one argument, which is an object containing three parameters: latitude, longitude, and a callback function. The callback needs to be able to accept two arguments: responseData, which is a Place object with the results of reverse geo-coding, and status, which is a string constant indicating success ('OK') or failure ('ERROR') of the call.

Here is an example showing revereseGeoCode() being invoked:

nokia.places.search.manager.reverseGeoCode({
    latitude: 52.33812,
    longitude: 13.08835,
    onComplete: function(responseData, status){
        if (status == 'ERROR') {
            // handle error condition
        }
        else {
            // process responseData
        }
});   

Getting place data (full)

The function getPlaceData() retrieves detailed information about a single place. Its argument is an object that, at a minimum, must identify the place for which to obtain data and provide a function that processes the data:

nokia.places.manager.getPlaceData({
    placeId: placeId,
    onComplete: function(data, status){
        // handle/process data
    }
});

Getting basic info

getPlaceData() can be called with the parameter basicInfo set to true to retrieve only core data for a place. Core data is a subset of the complete information that may be available. It includes place name and id, address, contact details, rating and alternative names, but no place description, rating or premium or business data.

nokia.places.places.manager.getPlaceData({
    placeId: placeId,
    basicInfo: true,
    onComplete: function(data, status){
        // handle/process data
    }
});

Getting place data in a different language

The default language of the Places API is set to British English denoted by the string 'en-gb' (a combination of the ISO 369 language code and ISO 3166 Alpha 2 country code). If you would like to receive data in a different language, you need to call the method nokia.places.settings.setLocale(), passing to it the appropriate language designation, before you submit a request for place-related data. If the language is supported, the back end returns the data in it, otherwise the data arrives in the closest matching language or the default language.

The code below demonstrates how to select Czech as the language for the back-end response.

nokia.places.settings.setLocale('cs-cz');
        
nokia.places.places.manager.getPlaceData({
    placeId: placeId,
    onComplete: function(data, status){
        // handle/process data
    }
});

Getting place reviews

To obtain only a list of reviews for a particular place, you can use the function call shown below, providing the place id and a callback to handle the retrieved data:

nokia.places.places.manager.getReviews({
    placeId: placeId,
    onComplete: function(data, status){
        // handle/process data
    }
});

Getting images/media

getMedia() is a function that helps you retrieve the contents of the media element of a Place object. This typically includes images. The functions argument is an object that must include the place id and the callback that is to process the retrieved data:

nokia.places.places.manager.getMedia({
    placeId: placeId,
    onComplete: function(data, status){
        // handle/process data
    }
});

Posting a new rating

Finally, you can update a palce's ratings by calling postRating(). The function argument object must inlcude the place id, a rating value (an integer) and a callback to process the results, which is a rating object containing the calculated rating for a place, for example, {value:4,count: 120}.

nokia.places.places.manager.postRating({
    placeId: placeId,
    ratingValue: ratingValue,
    onComplete: function(){
        // handle/process data
    }
});