---
title: "The GooglePlaces facade — Google Places for Laravel | Roundly"
description: "Every lookup, handle and health check on one facade — scalar shorthands or immutable query objects, and GooglePlaces::fake() for tests."
url: https://roundly-consulting.com/open-source/docs/google-places-for-laravel/client
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Google Places for Laravel](https://roundly-consulting.com/open-source/docs/google-places-for-laravel.md)

# 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:

```php
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:

```php
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:

```php
$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(), fresh(), 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](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## 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](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/google-places-for-laravel.md)