Geocoding

Reverse geocoding

geocode() returns a collection of ReverseGeocodingResult for a coordinate. A ZERO_RESULTS answer is an empty collection, not an exception:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

$results = GooglePlaces::geocode(48.1486, 17.1077);   // lat/lng shorthand
// or GooglePlaces::geocode(new Location(48.1486, 17.1077));
// or GooglePlaces::geocode(new ReverseGeocodingQuery(...));

$result = $results->first();

echo $result->address;
echo $result->placeId;

foreach ($result->components as $component) {
    echo "{$component->longName} ({$component->shortName})";
}

Use a ReverseGeocodingQuery to filter result and location types or to localise the response:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\ReverseGeocodingQuery;

$results = GooglePlaces::geocode(new ReverseGeocodingQuery(
    location: new Location(48.1486, 17.1077),
    resultTypes: ['street_address'],   // sent as result_type
    locationTypes: ['ROOFTOP'],        // sent as location_type
    language: 'sk',
));

$result = $results->first();
$result->geometry->location;           // Location
$result->geometry->viewportNorthEast;  // Location
$result->geometry->viewportSouthWest;  // Location
$result->types;                        // list<string>

Forward geocoding

geocodeAddress() turns an address string into a collection of results, each with coordinates, place id, types and components. GeocodingQuery adds inLanguage(), inRegion() and filterBy() component filters:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\GeocodingQuery;
use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

$results = GooglePlaces::geocodeAddress('1600 Amphitheatre Pkwy');

$first = $results->first();
echo $first->placeId;
echo $first->geometry->location->latitude;

// Full query with region + component filters:
$results = GooglePlaces::geocodeAddress(
    (new GeocodingQuery('Parliament'))->inRegion('sk')->filterBy('country:SK'),
);

Typed address components

Both geocoding and place results expose typed accessors over their raw address components via components():

$components = GooglePlaces::geocodeAddress('1600 Amphitheatre Pkwy')->first()->components();

echo $components->streetNumber(); // "1600"
echo $components->street();       // "Amphitheatre Parkway"
echo $components->city();         // "Mountain View"
echo $components->state();        // "California"
echo $components->postalCode();   // "94043"
echo $components->country();      // "United States"
echo $components->countryCode();  // "US"

$components->has('sublocality');                                // bool
$components->first('administrative_area_level_2')?->longName;   // any component type

Accessor	Google component type
`streetNumber()`	street_number
`street()`	route
`city()`	locality → postal_town → sublocality → sublocality_level_1
`postalCode()`	postal_code
`state()`	administrative_area_level_1
`country()`	country (long name)
`countryCode()`	country (short name)

On a Place, components() is populated only when addressComponents is included in the field mask.

Recipe: an address form

Pair autocomplete with forward geocoding to normalise a user-entered address into structured fields — here stored through addresses-for-laravel’s HasAddresses. This is plain host-app code; the packages are not wired together:

use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

// While the user types — suggest addresses:
$predictions = GooglePlaces::autocomplete($request->input('q'));

// On submit — normalise the chosen address into structured fields:
$result = GooglePlaces::geocodeAddress($request->input('address'))->first();

$model->addAddress([
    'street'      => $result?->components()->street(),
    'city'        => $result?->components()->city(),
    'postal_code' => $result?->components()->postalCode(),
    'country'     => $result?->components()->countryCode(),
    'latitude'    => $result?->geometry->location->latitude,
    'longitude'   => $result?->geometry->location->longitude,
]);

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages