Autocomplete

autocomplete() returns a collection of AutocompletePrediction — the suggestions you would see in the Google Maps search box. Pass a string, or an AutocompleteQuery for options:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\AutocompletePrediction;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\AutocompleteQuery;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\LocationDefinition;
use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

// String shorthand:
$predictions = GooglePlaces::autocomplete('Luxury Restaurant');

/** @var AutocompletePrediction $prediction */
$prediction = $predictions->first();

echo $prediction->description;
echo $prediction->placeId;
echo $prediction->mainText;       // structured label (nullable)
echo $prediction->secondaryText;  // structured label (nullable)
echo implode(', ', $prediction->types);

// Full query (immutable, fluent):
$query = (new AutocompleteQuery('Coffee'))
    ->ofType('cafe', 'restaurant')               // max 5 included primary types
    ->preferInArea((new LocationDefinition())->circle(new Location(48.1486, 17.1077), radius: 2000))
    ->inRegions('sk')                            // included region codes
    ->fromOrigin(new Location(48.1486, 17.1077))
    ->usingSessionToken('a-session-token');

$predictions = GooglePlaces::autocomplete($query);

Query options

Method	Effect
`withInput(string $input)`	Replace the input text.
`inLanguage(string $language)`	Response language (default en).
`ofType(string ...$types)`	Included primary types — max 5, otherwise a PlacesException.
`inRegions(string ...$codes)`	Included region codes — max 15.
`preferInArea(LocationDefinition $area)`	Location bias — results near the area rank higher.
`restrictTo(LocationDefinition $area)`	Location restriction — only results inside the area.
`nearby(float $lat, float $lng, int $radius = 5000)`	Shortcut for a circle bias.
`withinBounds(Location $low, Location $high)`	Shortcut for a rectangle restriction.
`fromOrigin(?Location $origin)`	Origin point sent with the request.
`usingSessionToken(string $token)`	Attach a billing session token (session() does it for you).

Bias or restrict by area

A bias prefers results near an area; a restriction limits results to it. Use the shortcuts, or build a LocationDefinition circle or rectangle yourself:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\AutocompleteQuery;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\LocationDefinition;

// Bias toward a circle (radius in metres, default 5000):
(new AutocompleteQuery('Coffee'))->nearby(48.1486, 17.1077, radius: 2000);

// Restrict to a rectangle between two corners:
(new AutocompleteQuery('Coffee'))->withinBounds(new Location(48.1, 17.0), new Location(48.2, 17.2));

// Or build the area yourself and pass it as a bias or a restriction:
$area = (new LocationDefinition())->circle(new Location(48.1486, 17.1077), radius: 2000);

(new AutocompleteQuery('Coffee'))->preferInArea($area);
(new AutocompleteQuery('Coffee'))->restrictTo($area);

Billing sessions

Tie an autocomplete burst plus the final details() call into one Google billing session. The session reuses a single token automatically and is consumed once details() resolves (calling it again throws a PlacesException):

$session = GooglePlaces::session();

$session->autocomplete('piz');
$session->autocomplete('pizza ne');   // same session token
$place = $session->details($placeId); // billed as one session, then closed

The token defaults to a fresh UUID; pass your own to resume a session across requests (for example, one token per form interaction):

$session = GooglePlaces::session();            // token defaults to a fresh UUID
$session = GooglePlaces::session($token);      // or resume with your own token

$session->token();       // the token sent to Google
$session->isFinished();  // true once details() has resolved

$session->autocomplete((new AutocompleteQuery('pizza'))->inLanguage('sk')); // query objects work too

Autocomplete is never cached — every keystroke you send is a live request, so debounce input on the client side.

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