*! version 0.0.1 12FEB2016
help ggeocode

Title

ggeocode -- a Java based Stata interface with the Google geocode
API. This program requires Java 8 or above and handles all of the parsing of
the data on the JVM (e.g., requires no dependencies on other packages). This
is being packaged with the jsonio package and is the first
deserializer. User's are welcome to submit pull requests to add additional
customized deserializers for popular JSON based API's, and more general tools
for JSON deserialization will be added in the future.

Syntax

ggeocode [varlist] [[if] [in]] , [
return(string)
apikey(string)]

Description

ggeocode is an alternative to the existing geocoding tools
available in the Stata ecosystem. One of the biggest differences between this
tool and others that interface with Google's geocoding API is the flexibility
it provides to users both in terms of providing the data needed and in
returning results from the API call.

Options

return this parameter is used to specify which values to return from the API call and can be any combination of:

Argument Result

location Returns the point coordinates
bbox Returns the bounding box around the geographical area
viewport Returns the viewport surround the address
address Returns the formatted address string from the JSON Payload
geotype Returns the geocode type
placeid Returns Google's geocode API place identifier
types Returns the type of address

Each of these options creates a different set of mutually exclusive variables listed below:

Return type Variables Created

location lat lon
bbox bbox_max_lat, bbox_max_lon, bbox_min_lat, bbox_min_lon
viewport viewport_max_lat, viewport_max_lon, viewport_min_lat, viewport_min_lon
address formatted_address
geotype geo_type
placeid place_id
types google_types

All of the potential string data are returned as
strLs. This is for two purposes, the first of which
is providing a more generic input type for the return values of the JSON data
(e.g., the length of a strL does not need to be known apriori) and the second
is that it may provide a more efficient means of storing the datum since the
.dta specification suggests that the values of strLs are unqiue with 8-byte
values that serve as pointers for the string value in the observations.

Additionally, unlike other tools, ggeocode will automatically handle
missing/null values in a smart way for you. For example, if batch geocoding,
you may find that some data elements (e.g., viewports, bounding boxes, etc...)
are non-existent for some observations in the raw JSON payloads. ggeocode
uses the extended missing value of .n (e.g., No Data Found) to handle these
observations when pushing the data back into Stata or using an empty string
in the case of string data.

apikey if you have an API key ggeocode will default to using
the https protocol for the API call and the datum is stored with private access
in the javaclass used to make the class and process the data.

Examples

Create some data to geocode

input int housenum str13 street str10 city str2 state str5 zip

4287 "46th Ave N" "Robbinsdale" "MN" "55422"

6675 "Old Canton Rd" "Ridgeland" "MS" "39157"

12313 "33rd Ave NE" "Seattle" "WA" "98125"

310 "Cahir St" "Providence" "RI" "02903"

22 "Oaklawn Ave" "Cranston" "RI" "02920"

61 "Pine St" "Attleboro" "MA" "02703"

10 "Larkspur Rd" "Warwick" "RI" "02886"

91 "Fallon Ave" "Providence" "RI" "02908"

195 "Arlington Ave" "Providence" "RI" "02906"

end

Geocode the data and return the point, bounding box, geocode type, and the cleaned/formatted address string

ggeocode housenum street city state zip in 1/2, ret(bbox location
geotype address location)

The default behavior if no return types are specified is to return the point coordinates only.

ggeocode housenum street city state zip if state == "RI"

Additional examples are available at http://github.com/wbuchanan/StataJSON

Author

William R. Buchanan, Ph.D.

Data Scientist

Minneapolis Public Schools

William.Buchanan at mpls [dot] k12 [dot] mn [dot] us