Pair framework: GoogleGeocoder

Pair\Services\GoogleGeocoder is Pair's server-side wrapper for the Google Geocoding API.

It is the right class when you want to:

• geocode a free-form address on the server
• reverse geocode stored coordinates
• resolve a Google place_id into a geocoding result
• keep Google query normalization out of controllers and models

The service returns raw Google result arrays. It does not create Pair model objects or custom DTOs.

Constructor

__construct(?GoogleMapsClient $client = null)

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

Inject a client when you want shared timeout settings or when multiple Google services should reuse the same transport instance.

Main methods

geocode(string $address, array $options = []): array

Returns all matching results for a free-form address.

Common options:

• language
• region
• components
• bounds

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();

// Ask Google for the best matches for an Italian address.
$results = $geocoder->geocode('Via Roma 10, Milano', [
    'language' => 'it',
    'region' => 'IT',
]);

Using components and bounds to reduce ambiguity:

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();

// Narrow the search to Italy and bias it toward a known viewport.
$results = $geocoder->geocode('Via Garibaldi 12', [
    'components' => [
        'country' => 'IT',
        'postal_code' => '20121',
    ],
    'bounds' => [
        'south' => 45.4300,
        'west' => 9.1200,
        'north' => 45.5000,
        'east' => 9.2500,
    ],
]);

geocodeOne(string $address, array $options = []): ?array

Shortcut for the first geocoding result. This is the most common method in application code.

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();

// Convenient when you need only one best-match address.
$result = $geocoder->geocodeOne('Piazza Duomo, Milano', [
    'language' => 'it',
]);

geocodePlaceId(string $placeId, array $options = []): ?array

Looks up a Google place_id through the geocoding endpoint.

This is useful when a form stores a place ID through GoogleAddress and the application later wants the full Google result again on the server.

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();

// Rehydrate the geocoding result from a saved Google place ID.
$result = $geocoder->geocodePlaceId($customer->billingAddressPlaceId, [
    'language' => 'it',
]);

reverseGeocode(float $latitude, float $longitude, array $options = []): array

Returns all geocoding results that match a coordinate pair.

Common options:

• language
• region
• result_type
• location_type

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();

// Reverse geocode stored coordinates to a human-readable address.
$results = $geocoder->reverseGeocode(45.4642035, 9.189982, [
    'language' => 'it',
    'result_type' => ['street_address', 'premise'],
]);

reverseGeocodeOne(float $latitude, float $longitude, array $options = []): ?array

Returns only the first reverse-geocoding result.

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();

// Typical choice when the UI needs one label for a stored point.
$result = $geocoder->reverseGeocodeOne(45.4642035, 9.189982, [
    'language' => 'it',
    'location_type' => ['ROOFTOP'],
]);

Common result handling

ZERO_RESULTS is intentionally soft-failed:

use Pair\Services\GoogleGeocoder;

$geocoder = new GoogleGeocoder();
$result = $geocoder->geocodeOne('Address that probably does not exist');

// GoogleGeocoder returns null here instead of throwing.
if (!$result) {
    // Fall back to manual review or ask the user to refine the address.
}

Secondary methods

buildBaseQuery(array $options): array

Internal method that translates Pair-style options into Google query parameters.

normalizeComponents(string|array $components): string

Accepts either a raw Google components string or a Pair-friendly associative array and converts it to the country:IT|postal_code:20121 format expected by Google.

normalizeBounds(array $bounds): string

Converts a south/west/north/east array into Google's rectangular bounds syntax. It throws if one of the required keys is missing.

normalizePipeSeparatedValue(string|array $value): string

Used internally for options such as result_type and location_type.

extractResults(array $response): array

Normalizes Google status handling:

• OK returns the results array
• ZERO_RESULTS returns []
• other statuses throw PairException

Notes

• Empty addresses and empty place IDs are rejected before any HTTP request is sent.
• This class is intentionally small; if you need autocomplete or place details, use GooglePlacesService.
• For browser-driven address selection in forms, combine GoogleMaps with GoogleAddress.

See also: GoogleMaps, GoogleMapsClient, GooglePlacesService, GoogleAddress, Configuration file.