Implemented Google Maps Geocoding API -> Location Data Enhancements

[Bob]

I've completely revamped the fetching of location data from the Google Maps Geocoding API.

Some things you might need to know if you use the advanced Google Maps APIs for Category Maps, whether you are just an Admin or are a developer or like to tinker with things and have been tinkering with fetching location data.

There is a new function in the Item Repository:

getLocationDataFromGoogleMapsGeocodingApi($location = null, $action = '')

This new function replaces 3 existing functions (which have all been removed). This function is called when Creating an Item that has a location being set, Editing an item that has a location being set or changed and when running the Rebuild Item Location Data. Each of those used to have a separate function (which no longer exist). This follows DNRY (Do Not Repeat Yourself). This allows me to make modifications in one place without having to update 3 functions in 3 different places. It also is a single point of entry for 3rd party extensibility.

The Best Part... the Location Data (stored in the location_data field) is now much more extensive (both for internal use and customization purposes).

Currently, the available data is pretty limited. There are only a couple bits of data stored ('latitude', 'longitude' and 'formatted_address'). Latitude and Longitude are used for the Category Map (those are the key elements that are used by the JavaScript API to plot markers on the category map). Formatted Address is what Google Maps determines is the BEST fully formatted address based on the data (location) that was provided via the SC Item location field.

WHATS NEW....

A whole heck of a lot more DATA is being stored (cached in the location_data field) for both internal use and customization purposes.

Address Components: 'address_components[]' is a multi dimensional array containing the various separate components applicable to an address.

Each address component typically contains the following fields:

• 'types[]' is an array indicating the type of the address component. See the list of supported types.
• 'long_name' is the full text description or name of the address component as returned by the Geocoder.
• 'short_name' is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation.

Note the following facts about the 'address_components[]' array:

• The array of address components may contain more components than the formatted_address.
• The array does not necessarily include all the political entities that contain an address, apart from those included in the formatted_address. To retrieve all the political entities that contain a specific address, you should use reverse geocoding, passing the latitude/longitude of the address as a parameter to the request.
• The format of the response is not guaranteed to remain the same between requests. In particular, the number of address_components varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the component can change. A particular component may be missing in a later response.

Formatted Address: 'formatted_address' is a string containing the human-readable address of this location (as determined by the Google Maps Geocding API, not the address typed into the location input).

City: 'city' is a string parsed out of the Address Components array based on (Political Locality OR Political Sublocality OR Political Postal Town). There is no "CITY" as far as Google Maps is concerned, its a complex set of Political "components" based on various regional scenarios. I do the BEST that I can to parse and store what I determine matches what @alfa1 wants when he says "City).

I first check to see of Political Locality is set (which 90% of the time, that is the equivalent of what we call a "City". If there is no Political Locality set, I then check for Political Sub Locality (which in some cases there are up to FIVE LEVELS of Sub Locality). If neither of those exist, I use the Political Post Town to set as the "City".

City Note: There are OTHER Political Components that MIGHT be added if people run into situations where there is no obvious usable data to set the City variable.

State and State Short: 'state' and 'state_short' are strings parsed out of the Address Components array based on Political Administrative Area Level 1 (there are five Political Administrative Area levels). RIGHT NOW, I am only using administrative_area_level_1 to set the "State" and "State Short" eg "Montana" and "MT". Note: _short is google maps way of abbreviations.

• 'administrative_area_level_1' indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 short names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.
• 'administrative_area_level_2' indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.
• 'administrative_area_level_3' indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
• 'administrative_area_level_4' indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
• 'administrative_area_level_5' indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.

Country and Country Short: 'country' and 'country_short' are strings parsed out of the Address Components array which indicates the national political entity, and is typically the highest order type returned by the Geocoder. This one is the least complex lol

Geometry: 'geometry[]' is a multi dimensional array that contains the following information:

• 'location[]' is an array that contains the geocoded latitude, longitude value. For normal address lookups, this field is typically the most important.
• 'location_type' stores additional data about the specified location. The following values are currently supported:
  • "ROOFTOP" indicates that the returned result is a precise geocode for which we have location information accurate down to street address precision.
  • "RANGE_INTERPOLATED" indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
  • "GEOMETRIC_CENTER" indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
  • "APPROXIMATE" indicates that the returned result is approximate.
• 'viewport[]' is an array that contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the southwest and northeast corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user.
• 'bounds[]' (optionally returned) is an array that stores the bounding box which can fully contain the returned result. Note that these bounds may not match the recommended viewport. (For example, San Francisco includes the Farallon islands, which are technically part of the city, but probably should not be returned in the viewport.)

Geometry Note: I don't use Geometry data other than to parse out Latitude and Longitude to store in their own variables, but for customization purposes, it could come in handy and doesn't take up a lot of storage so I decided to include it.

Latitude: 'latitude' is parsed out of geometry->location->lat and used by Category and Brand Maps for plotting markers.

Longitude: 'longitude' is parsed out of geometry->location->lng and used by Category and Brand Maps for plotting markers.

Place Id: 'place_id' is a unique identifier that can be used with other Google APIs. For example, you can use the place_id in a Places API request to get details of a local business, such as phone number, opening hours, user reviews, and more. See the place ID overview.

Place Id Note: SC does not use Place ID, I added it because I've seen a few people mention wanting to do some custom things with the Places API, so why not store the place_id so that its available if needed.

Plus Code: 'plus_code' (Not currently being used, but stored for customization purposes).

• 'plus_code' (see Open Location Code and plus codes) is an encoded location reference, derived from latitude and longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named).
  The plus code is formatted as a global code and a compound code:
  • 'global_code' is a 4 character area code and 6 character or longer local code (849VCWC8+R9).
  • 'compound_code' is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA).
  Typically, both the global code and compound code are returned. However, if the result is in a remote location (for example, an ocean or desert) only the global code may be returned.

IMPORTANT NOTE: The UPGRADE is going to run the Rebuild Showcase Item Location Data, so please let the JOB finish before running to the frontend to TEST.

 

[Bob]

For those of you that like to see what stored data actually looks like (or like "visuals"), here are a couple screen shots.

This is the output of $item->location_data (which as you can see, is a multi dimensional array (arrays within arrays). This is one level expanded (showing all the level 1 array elements, which each of these is explained above in the same order that they appear within the location_data array).




And in these 2 shots, all levels are expanded...