Pair framework: GooglePlacesService

Pair\Services\GooglePlacesService wraps Google Places API (New) for server-side use.

In Pair projects it is mainly used for two flows:

• backend autocomplete endpoints
• place-details lookup after the UI or API has selected a placeId

Unlike GoogleGeocoder, this service returns:

• normalized suggestion arrays for autocomplete
• raw decoded Google place objects for place details

Constructor

__construct(?GoogleMapsClient $client = null)

Creates the service with an injected GoogleMapsClient or with a default client built from .env.

Main methods

autocomplete(string $input, array $options = []): array

Calls Places API autocomplete and returns normalized suggestions.

Supported options:

• include_query_predictions
• included_primary_types
• included_region_codes
• language
• location_bias
• location_restriction
• origin
• region
• session_token

Returned suggestion shape:

• place suggestions expose type, placeId, text, mainText, secondaryText, types, distanceMeters
• query suggestions expose type = query and text

use Pair\Services\GooglePlacesService;

$places = new GooglePlacesService();

// Build suggestions for a custom autocomplete endpoint.
$suggestions = $places->autocomplete('Via Roma 10', [
    'language' => 'it',
    'included_region_codes' => ['it'],
]);

Autocomplete with a billing/session token and query predictions enabled:

use Pair\Services\GooglePlacesService;

$places = new GooglePlacesService();
$sessionToken = bin2hex(random_bytes(16));

// Reuse the same token across autocomplete and getPlace in one UX flow.
$suggestions = $places->autocomplete('farmacia milano', [
    'include_query_predictions' => true,
    'language' => 'it',
    'region' => 'IT',
    'session_token' => $sessionToken,
]);

Autocomplete biased around a user location:

use Pair\Services\GooglePlacesService;

$places = new GooglePlacesService();

// Bias suggestions toward the user's last known coordinates.
$suggestions = $places->autocomplete('via roma', [
    'origin' => [
        'latitude' => 45.4642035,
        'longitude' => 9.189982,
    ],
    'included_primary_types' => ['street_address'],
]);

getPlace(string $placeId, array $fields = [], array $options = []): array

Fetches place details for a selected placeId.

If $fields is empty, Pair requests a default essentials set:

• id
• displayName
• formattedAddress
• location
• addressComponents
• types
• viewport

use Pair\Services\GooglePlacesService;

$places = new GooglePlacesService();

// Fetch just the fields needed by the application.
$place = $places->getPlace('ChIJN1t_tDeuEmsRUsoyG83frY4', [
    'id',
    'displayName',
    'formattedAddress',
    'location',
]);

Typical flow after an autocomplete selection:

use Pair\Services\GooglePlacesService;

$places = new GooglePlacesService();
$sessionToken = $_POST['sessionToken'] ?? '';

// Reuse the same token used during autocomplete for Google billing consistency.
$place = $places->getPlace($_POST['placeId'], [
    'id',
    'formattedAddress',
    'addressComponents',
    'location',
], [
    'language' => 'it',
    'session_token' => $sessionToken,
]);

Common controller pattern

This service fits well in thin JSON endpoints:

use Pair\Api\ApiResponse;
use Pair\Services\GooglePlacesService;

$places = new GooglePlacesService();

// Keep the controller small and return Pair-friendly suggestion arrays.
ApiResponse::respond([
    'suggestions' => $places->autocomplete($_GET['q'] ?? '', [
        'language' => 'it',
        'included_region_codes' => ['it'],
    ]),
]);

Secondary methods

normalizeSuggestions(array $response): array

Internal method that converts Google's nested autocomplete payload into the flatter Pair-friendly structure returned by autocomplete().

normalizeFieldMask(array $fields): string

Internal method that:

• trims and deduplicates field names
• throws if the final field mask would be empty

Notes

• autocomplete() returns [] immediately when the input is empty.
• getPlace() throws when placeId is empty.
• For frontend forms that already use Google's own browser autocomplete through Pair, see GoogleMaps and GoogleAddress.

See also: GoogleMaps, GoogleMapsClient, GoogleGeocoder, GoogleAddress.