Title

googleplaces -- Using Google Places API to return search results from Google Places

Syntax

googleplaces
[varlist]
[in],
[textsearch nearbysearch]
[apikey(stringasis)]
[options]

Description

googleplaces uses the Google Places API Web Service to retrieve search results from Google Places,
the database of places that supports Google Maps, Google+ and many other location-based web services.
googleplaces returns detailed place information for each search and can execute a regular text search
using keywords that you would enter into the Google search webpage or a nearby search using a set of coordinates
to retrieve results for places within a specified radius. Each search result provides the full place name,
geocoded coordinates, and full address, with the capability to gather additional data such as
phone number, price level, customer rating and website of that place if applicable.

Getting an API key for Google Places

To query the Google Places API, users must register for an API key from the Google Places API Web Service
by clicking here. The API key must be included in any
googleplaces command requesting search results. The Google Places Web Service can be accessed for free,
but requires a credit card for account validation. The free service provides 15,000 searches a day.
Paid services offer more searches per day, which can be explored through the link to usage limits and pricing.

Required Library

googleplaces users must have insheetjson and libjson installed,
both of which are available from SSC using the following commands:

ssc install insheetjson, ssc install libjson

Options

Main

varlist is a list of one or more variables that contain text to be submitted as search queries.
All variables in the varlist must be formatted as strings.
For nearbysearch the varlist can contain only one variable formatted as described below.
varlist should not be included when using the cleanup option.

textsearch or nearbysearch must be chosen when submitting search requests
to specify to Google what kind of query to make. When using nearbysearch,
the varlist must contain only a single string variable containing a latitude and longitude
seperated by a single comma and no space (example: "00.0000000,-11.1111111").

apikey(stringasis) allows the user to enter an API key for submitting search requests.
After registering with Google, each user will copy and paste the API key between parenthesis.
The command will not initiate search requests without an APIkey.

Supplemental

advanced submits a two-part search to capture the default search returns
(full place name, geocoded coordinates, and full address) and submit a follow-up search
on each return to capture phone number, price level, customer rating, and website (if applicable).
Choosing the advanced search option causes googleplaces to use up the
availble daily search quota more rapidly, although the follow-up queries are
weighted at 1/10th the value of a normal search query against a user's daily quota
(15,000 daily searches for free accounts).

results(integer) controls the maximum number of results to capture for a textsearch or nearbysearch.
The default is 1 if not listed. The maximum number of results a user can specify is 20.
Some queries may produce fewer than the specified maximum number of results in which case
googleplaces returns the number of search results actually found.

radius(string asis) sets the radius for a nearbysearch. The default is 0 if not listed.
Note, the search radius must be measured in meters. To set a radius of 5km, enter radius(5000).

keyword(string asis) can be included for a nearbysearch to filter out results with matching keyword.

type(string asis) limits the results for a nearbysearch to a specified type using
Google Places predetermined list of type categories. To view the available types to choose from on Google's website, click
here.

cleanup If the command is interrupted or terminated before the search completes,
the data returned to the Stat dataset will be unsorted and in an incorrect format.
Run the command with only the cleanup option and no other inputs to finish sorting and reformating the data to it's original form.
NOTE: If googleplaces terminates without finishing the search,
the command will not run on the same dataset until after the user submits googleplaces, cleanup.

Examples

Conducting a text search using two variables: business_name and address

. googleplaces business_name address, textsearch apikey(yourapikeyhere)

Conducting a nearby search to identify up to 20 police locations within a 10km radius of each geocoded location in the dataset

. googleplaces coordinates, nearbysearch apikey(yourapikeyhere) results(20) radius(10000) type(police)

Limiting a nearby search to return up to 5 results within a 5km radius related to health using the keyword option

. googleplaces coordinates, nearbysearch apikey(yourapikeyhere) results(5) radius(5000) keyword(health)

Conducting a nearby search to identify up to 10 restaurants within 1km and requesting extended search results

. googleplaces coordinates, nearbysearch apikey(yourapikeyhere) results(10) radius(1000) type(restaurant) advanced

If the command terminates before completing a search, the dataset will need to be cleaned up as follows using the cleanup option

. googleplaces, cleanup

Authors

Taylor Crockett (tcrockett53@gmail.com)

Stephen Barnes (barnes@lsu.edu)

Chris Schmidt (chris.m.schmidt@utexas.edu)

Acknowledgements

Developed with support from the LSU Economics & Policy Research Group