alexpechkarev/google-maps

The package follows a consistent pattern for making requests:

1. Load a service: Use \GoogleMaps::load('service-name').
2. Set parameters: Use setParam([...]) for arrays or setParamByKey('key', 'value') for single values. For nested arrays, use dot notation (e.g., components.country).
3. Execute the request:
   • Use ->get() for most APIs (Geocoding, Elevation, etc.). Note that get() returns a JSON string that you must decode into a PHP variable.
   • Use ->fetch() ONLY for the Routes API (routes and routematrix services). fetch() returns a PHP array directly.

// Standard API pattern
$response = \GoogleMaps::load('geocoding')
    ->setParam(['address' => 'santa cruz'])
    ->get();

// Routes API pattern
$response = \GoogleMaps::load('routes')
    ->setParam($params)
    ->fetch();

Install the package via Composer to add Google Maps API web services to your Laravel application.

Requirements:

• PHP >= 7.3.0
• PHP cURL extension

composer require alexpechkarev/google-maps

1. Publish the configuration file using Artisan:

   php artisan vendor:publish --tag=googlemaps

2. Open config/googlemaps.php and add your API key to the key field.

You can also specify unique keys for specific services by overwriting the master key within the service array in the config file.

'key' => 'ADD YOUR SERVICE KEY HERE',

To use the GoogleMaps facade, register the Service Provider and the Facade alias in your config/app.php file.

'providers' => [
    ...
    GoogleMaps\ServiceProvider\GoogleMapsServiceProvider::class,
]

'aliases' => [
    ...
    'GoogleMaps' => GoogleMaps\Facade\GoogleMapsFacade::class,
]

To customize the package settings, you can publish the configuration file to your application's config directory using the googlemaps tag. This allows you to manage your Google Maps API credentials and other settings within your Laravel application.

php artisan vendor:publish --tag=googlemaps

When using setParamByKey(), you can set deeply nested array values using dot notation.

$endpoint = \GoogleMaps::load('geocoding')
   ->setParamByKey('address', 'santa cruz')
   ->setParamByKey('components.administrative_area', 'TX');

For the Routes API (routes and routematrix services), use the fetch() method instead of get().

• fetch(): Executes the request and returns a decoded PHP array directly. It throws an ErrorException if the request fails.
• Polyline Decoding: The Routes API configuration includes a decodePolyline parameter which defaults to true. When enabled, the service attempts to decode polyline.encodedPolyline and adds the decodePolyline parameter to the response.

$response = \GoogleMaps::load('routes')
                ->setParam($reqRoute) // $reqRoute is an array of parameters from the Routes API spec
                ->fetch();

Use setEndpoint( $endpoint ) to specify the desired response format. Supported values are 'json' (default) or 'xml'.

Note: This method is not applicable to the Routes API when using fetch().

$response = \GoogleMaps::load('geocoding')
	->setEndpoint('json'); // returns $this

You can set request parameters using either a single key-value pair or an entire array of parameters.

• setParamByKey( $key, $value ): Sets a single parameter. You can use 'dot' notation for deeply nested arrays (e.g., 'components.country').
• setParam( $parameters ): Sets multiple parameters at once using an associative array.

// Using setParamByKey with dot notation
$endpoint = \GoogleMaps::load('geocoding')
   ->setParamByKey('address', 'santa cruz')
   ->setParamByKey('components.administrative_area', 'TX');

// Using setParam with an array
$response = \GoogleMaps::load('geocoding')
                ->setParam([
                   'address'     => 'santa cruz',
                   'components'  => [
                        'administrative_area'   => 'TX',
                        'country'               => 'US',
                     ]
                 ]);

The routematrix service is the recommended replacement for the deprecated Distance Matrix API. Like the routes service, it uses fetch() and returns a PHP array directly.

$matrixParams = [
    'origins' => [ /* ... array of origins ... */ ],
    'destinations' => [ /* ... array of destinations ... */ ],
    'travelMode' => 'DRIVE',
];

$responseArray = \GoogleMaps::load('routematrix')
    ->setParam($matrixParams)
    ->setFieldMask('originIndex,destinationIndex,duration,distanceMeters,status,condition')
    ->fetch();

Use load( $serviceName ) to initialize a specific web service configuration. The $serviceName must match a service name defined in your configuration file (e.g., 'geocoding', 'routes', or 'routematrix'). This method returns $this to allow for method chaining.

\GoogleMaps::load('geocoding');