GoogleMapsClient

Pair framework: GoogleMapsClient

Pair\Services\GoogleMapsClient is Pair's low-level HTTP client for Google Maps Platform web services.

You normally do not start here when building application features. In most code, you should prefer GoogleGeocoder or GooglePlacesService. This class is useful when you need:

• direct access to Google Geocoding or Places endpoints
• shared timeout and API-key handling across multiple Google services
• a reusable transport layer for custom Google Maps wrappers inside the project

Constructor

__construct(?string $apiKey = null, ?int $timeout = null, ?int $connectTimeout = null, ?string $geocodingBaseUrl = null, ?string $placesBaseUrl = null)

Builds the client from explicit parameters or environment values.

Relevant env keys:

• GOOGLE_MAPS_API_KEY
• GOOGLE_MAPS_TIMEOUT
• GOOGLE_MAPS_CONNECT_TIMEOUT
• GOOGLE_MAPS_GEOCODING_BASE_URL
• GOOGLE_MAPS_PLACES_BASE_URL

If the API key is missing, the constructor throws immediately. That is intentional: this class is server-side only and should never run without a valid Google server key.

Main methods

geocodingGet(string $path, array $query = []): array

Performs a GET request against the Google Geocoding API and automatically appends the API key as key=....

Use it when you want raw geocoding responses instead of the small helpers exposed by GoogleGeocoder.

use Pair\Services\GoogleMapsClient;

$client = new GoogleMapsClient();

// Call the Geocoding API directly and inspect the raw Google payload.
$response = $client->geocodingGet('/maps/api/geocode/json', [
    'address' => 'Via Roma 10, Milano',
    'language' => 'it',
    'region' => 'IT',
]);

placesGet(string $path, array $query = [], ?string $fieldMask = null): array

Performs a GET request against Places API (New).

Pair sends the API key through X-Goog-Api-Key and, when provided, the field mask through X-Goog-FieldMask.

use Pair\Services\GoogleMapsClient;

$client = new GoogleMapsClient();

// Fetch place details with an explicit field mask.
$place = $client->placesGet('/v1/places/' . rawurlencode($placeId), [
    'languageCode' => 'it',
], 'id,displayName,formattedAddress,location');

placesPost(string $path, array $payload = [], ?string $fieldMask = null): array

Performs a JSON POST request against Places API (New).

This is the method used internally by GooglePlacesService for autocomplete, but it is also useful when a project needs an endpoint that Pair does not yet wrap.

use Pair\Services\GoogleMapsClient;

$client = new GoogleMapsClient();

// Use the raw Places autocomplete endpoint.
$suggestions = $client->placesPost('/v1/places:autocomplete', [
    'input' => 'Via Roma 10',
    'languageCode' => 'it',
    'includedRegionCodes' => ['it'],
], 'suggestions.placePrediction.placeId,suggestions.placePrediction.text.text');

Common usage pattern

A common project-level pattern is to share one configured client between multiple Google services:

use Pair\Services\GoogleGeocoder;
use Pair\Services\GoogleMapsClient;
use Pair\Services\GooglePlacesService;

// Keep timeouts and credentials centralized in one client instance.
$client = new GoogleMapsClient(null, 10, 3);

$geocoder = new GoogleGeocoder($client);
$places = new GooglePlacesService($client);

Secondary methods

request(string $method, string $url, array $query = [], ?array $payload = null, array $headers = []): array

Internal transport method used by the public helpers. It:

• builds the final URL
• sends the cURL request
• decodes JSON responses
• throws PairException on HTTP-level Google errors

buildUrl(string $url, array $query = []): string

Internal utility that appends query-string parameters without duplicating ? or &.

resolveErrorMessage(array $response): string

Internal utility that extracts the most useful message from Google error payloads such as error.message, error_message, or status.

Notes

• GoogleMapsClient is intentionally thin. It does not normalize geocoding results or autocomplete suggestions into Pair-specific structures.
• Empty HTTP bodies are returned as empty arrays.
• Invalid JSON and HTTP 4xx / 5xx responses are converted into PairException.

See also: GoogleMaps, GoogleGeocoder, GooglePlacesService, Configuration file.