Geocoding (Address Lookups)

The concept of geocoding is fairly straightforward... it simply means we are using a text string to lookup the exact coordinates of a location. The text string can be as simple or complex as necessary, and Google will do its best to interpret that location as a set of real-world coordinates.

Say you want to take a partial address (ie: 123 Main St) and determine the precise details of that geographic location. This is commonly referred to as an address lookup.

You can perform a geocoding lookup to get a complete address (including latitude & longitude) based on a partial address or postal code. The basic geocoding process can be extremely simple:

• Twig
• PHP

{% set address = googleMaps.lookup('123 Main St').one() %}

There are three available methods (all, one, coords) which determine how the lookup results will be returned to you.

How it works

Here is a rough diagram of how a geocoding request flows through the plugin...

1. Prepare Lookup

The GoogleMaps::lookup method creates a Lookup Model, which contains everything the request will need to call the API. There isn't much you can do with a Lookup Model directly, until you append all()/one()/coords() onto the end of it. See the geocoding target for more information.

2. Specify Results Type

The subsequent chained method determines how you will receive the API results.

• If you want to get the complete set of results, use all(). The results will be an array of Address Models, sorted in order of what Google considers to be the best match.
• Generally (but not always), it's safe to assume that Google's hunch is correct, and the first result is likely to be the correct match. In this case, you may feel comfortable using one(), which returns only a single Address Model.
• And if all you really need are the coordinates of the best possible match, then it's probably safe to use coords(). This returns a pseudo-model (aka: a glorified array) of Coordinates.