Nearly every business, small and large, has a listing in Google Places. You would be most familiar with Google Places just by searching within Google Maps. Using Google Places requires some JavaScript code, but ViziApps makes this easy by providing a ready-to-use library.

This document describes how ViziApps gives you direct access to search and get results from Google Places. You can find out how to show the search results on a map in the companion document, Integrating Google Maps.

The first step is to install the ViziApps JavaScript library into your app's HTML Header. Use the document event GooglePlacesLoaded to guarantee that calls are only made after the library is installed and ready.

<script src="https://s3.amazonaws.com/viziapps/apps/google_places_1.0.2.js"></script>

<script>
var goomaps;
$(document).on( 'GooglePlacesLoaded', function() 
{
    // create an instance of the google maps api:
    goomaps = new v.googlePlaces();
});

function findBakeries() {
    // make calls to the google maps library, such as:
    if ( !goomaps ) return;
    goomaps.find( 'bakeries' )
    // ...
}
</script>

Search Google Places by calling the .find( searchTerm, optionSet ) method. Process the success or failure results with the jQuery Deferred Methods .done() and .fail().

• searchTerm is a string, such as the name of a store.
• optionSet is an optional object that may contain several options, described below.

var searchTerm = v.getFieldValue( 'searchTextField' );
var gpsloc = { 
    latitude: v.getFieldValue( 'gpsLatitude' ), 
    longitude: v.getFieldValue( 'gpsLongitude' ) 
};
var optionSet = { 
    location: gpsloc,
    pageLimit: 1
};

goomaps.find( searchTerm, optionSet )
.fail( function( errMessage )
{
    alert( 'Search error: ' + errMessage );
} )
.done( function( placeList )
{
    console.log( JSON.stringify( placeList, null, '  ' ) );
} );

The return placeList in the .done() method is an array of Place Objects, each containing descriptive information such as the place's name, address, coordinates, etc. The list of properties is fully documented: Place Search Results.

• If the optionSet includes a location, then the search will only return places that are nearby that location.
• If there is no location specified, then any search context will be based on the searchTerm, for example “pizza in New York”.

The following properties may be included in the optionSet parameter for .find(). If the types property is included, then the searchTerm parameter may be set to null or empty.

After making a search with .find(), use the .select() method to retrieve a specific list or subset of the search results. There are several ways to make this call:

Each Place Object returned from .find() gives a summary set of information about each place, but more detailed information is available. Use the .details( placeObject ) method to get these details about a specific place.

goomap.find( 'bakeries in Boston' )
.done( function( placeList )
{
    var details = goomap.details( placeList[0] );
    console.log( JSON.stringify( details, null, '  ' ) );
    v.setFieldValue( 'placeImageField', details.mainphoto );
});

The detailed properties that are available are fully documented: Place Details Responses. The ViziApps library adds one property: if at least one photo is available, a mainphoto property will contain a URL to the first photo in the list.