The GooglePlaces facade

Everything goes through the GooglePlaces facade — RoundlyConsulting\GooglePlaces\Facades\GooglePlaces, auto-aliased as GooglePlaces. Flat methods run one request each; session(), matrix() and photo() return handles that call back into the same client:

use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

// Flat lookups — one request each:
$predictions = GooglePlaces::autocomplete('Coffee');
$place       = GooglePlaces::details('ChIJN1t_tDeuEmsRUsoyG83frY4');
$places      = GooglePlaces::textSearch('pizza in Bratislava');
$addresses   = GooglePlaces::geocode(48.1486, 17.1077);

// Handles — built by the client, every call goes back through it:
$session = GooglePlaces::session();                         // PlacesSession
$matrix  = GooglePlaces::matrix($origins, $destinations);   // PendingMatrix
$bytes   = GooglePlaces::photo($place->photos[0])->contents();

// Health check:
$health = GooglePlaces::check();                            // list<ApiCheckResult>

Area	GooglePlaces::…
Places lookups	`details(), autocomplete(), textSearch(), nearbySearch(), findPlace()`
Auto-pagination	`textSearchPaginated(), nearbySearchPaginated()`
Geocoding	`geocode(), geocodeAddress()`
Routes	`distance(), computeMatrix()`
Handles	`session(), matrix(), photo()`
Photo requests	`photoUri(), photoContents(), photoUrl()`
Health	`check()`
Testing	`fake()`

Shorthands and query objects

Common lookups take a scalar shorthand, or a full query object when you need options such as language, types or a location bias:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\AutocompleteQuery;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\DetailsQuery;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\ReverseGeocodingQuery;
use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

// Scalar shorthand…
GooglePlaces::autocomplete('Coffee');
GooglePlaces::details('ChIJN1t_tDeuEmsRUsoyG83frY4');
GooglePlaces::geocode(48.1486, 17.1077);

// …or a full query object when you need options:
GooglePlaces::autocomplete((new AutocompleteQuery('Coffee'))->inLanguage('sk'));
GooglePlaces::details(new DetailsQuery('ChIJN1t_tDeuEmsRUsoyG83frY4', language: 'sk'));
GooglePlaces::geocode(new ReverseGeocodingQuery(new Location(48.1486, 17.1077), language: 'sk'));

Query objects are immutable: every fluent method returns a new instance, so always use the returned value:

$query = new AutocompleteQuery('Coffee');

$query->inLanguage('sk');           // returns a NEW query — $query is unchanged
$query = $query->inLanguage('sk');  // reassign to keep the change

Handles

The three handles are built by the client and route every request back through it — so caching, rate limits, events and GooglePlaces::fake() all apply to them:

GooglePlaces::…	Handle methods	Notes
`session(?string $token = null)`	`autocomplete(), details(), token(), isFinished()`	One billing session; closed once details() resolves.
`matrix($origins, $destinations)`	`departingAt(), driving(), walking(), bicycling(), transit(), travellingBy()`	The travel-mode call runs computeMatrix() and returns a DistanceMatrix.
`photo($name, $maxWidth, $maxHeight)`	`url(), contents(), save($disk, $path)`	url() runs photoUri(), contents() and save() run photoContents().

The full method list with return types is in DI and actions — every facade method is a method on the injectable PlacesClient contract, except the facade-only fake().

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