google-maps for Laravel: web service clients with a fluent API

One fluent client, several services, one facade

This package provides a convenient way of setting up and making requests to Google Maps APIs from your Laravel application, and it covers a set of web services: the Routes API, Elevation, Geocoding, Geolocation, Roads, Time Zone and the Places API Web Services.

The interface is the standard Laravel service provider and facade arrangement, which means the calling code reads like a chain rather than like an HTTP client:

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

Three methods carry the design. `load($serviceName)` loads the configuration for the web service you name, `setParam` or `setParamByKey` set the request parameters, and then you execute. The available methods list in the README is explicit that each of these returns `$this`, which is what makes the chain work.

There are two ways to set parameters, and the difference is a practical one. `setParam` takes an array of key and value pairs, and required parameters can be specified that way. `setParamByKey` sets one key at a time, and for deeply nested arrays it uses dot notation, as the example shows:

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

The `//return $this` comment in that example is the author's own note and it is the kind of detail that separates a wrapper written for daily use from one written for a demo.

The response format is configurable too. `setEndpoint` sets the desired response format, json or xml, for the APIs using get(), with json as the default, and `getEndpoint` returns what is currently configured. By default the output parameter is set to JSON where appropriate, and the README reminds you to decode the JSON string into a PHP variable.

The Routes API is the one that behaves differently

The most important thing in the README is the deprecation notice, and it changes how you use the package rather than just what you can use.

The Google Maps Directions API and Distance Matrix API are deprecated. The package now includes support for the new Google Maps Routes API, which is the recommended replacement for calculating routes and route matrices, and the README says to update application code to use the `routes` and `routematrix` services instead of the deprecated `directions` and `distancematrix` services.

That is a two-part change: two new services to call, and a different calling convention for them. The general pattern in the README is stated as `->get()` for all APIs except the Routes API, and `->fetch()` only for the Routes API, for the routes and routematrix services.

The reason is in the response handling. The Routes API uses the fetch method and returns a PHP array directly, with no JSON decoding needed, while the older services return a JSON string you have to decode yourself. The compute route example is the clearest illustration:

$responseArray = \GoogleMaps::load('routes') // Use 'routes' service
    ->setParam($routeParams)
    ->setFieldMask('routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline') // optional - used to specify fields to return 
    ->fetch(); // Use fetch() for Routes API

// $responseArray is already a PHP array
if (!empty($responseArray['routes'])) {
    // Process the route data
} else {
    // Handle errors or no routes found
}

Two details in that example are worth copying. The `setFieldMask` call is optional and is how you ask the Routes API for only the fields you need, which on a billed API is a cost question and not only a convenience. And the route parameters themselves are arrays, with origin and destination as nested structures rather than as strings, since the Routes API takes coordinates or place identifiers with explicit fields.

The matrix variant is the same shape with origins and destinations:

$responseArray = \GoogleMaps::load('routematrix') // Use 'routematrix' service
    ->setParam($matrixParams)
    ->setFieldMask('originIndex,destinationIndex,duration,distanceMeters,status,condition') // optional - used to specify fields to return 
    ->fetch(); // Use fetch() for Routes API

// $responseArray is already a PHP array
// Process the matrix data

The matrix field mask lists the per-element fields including status and condition, so an element that could not be routed is distinguishable from one that routed quickly.

There is one more Routes-specific configuration detail. The config for routes includes a decodePolyline parameter, default true, which adds a decodedPolyline key to the response if a polyline is present. That is a decoding step done for you, and it is a place where the response shape differs from what the API sent, so it is worth knowing it is there before you compare an array you got with one you expected.

Installation, the service provider, and where the key goes

Setting the package up is four steps, and two of them are the standard Laravel registration dance.

The install is a composer require:

composer require alexpechkarev/google-maps

Then you register the service provider and the facade in `config/app.php`:

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

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

Then you publish the configuration file:

php artisan vendor:publish --tag=googlemaps

And finally you add the API key by opening `config/googlemaps.php` and filling in the service key:

/*
|----------------------------------
| Service Keys
|------------------------------------
*/

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

The key handling is the part with a real operational dimension. There is a master key, and if you would like to use different keys for any of the services you can overwrite the master API key by specifying it in the `service` array for the selected web service. For a production deployment that is the difference between one bill you can attribute and several you cannot, since Google bills per API and a single key for everything tells you nothing about which service is costing what.

The dependency list is short, which is worth noting for a package that makes network calls: PHP cURL and PHP 7.3.0 or newer. The project is MIT licensed, the default branch is master, and the recent releases are v12.16 and v12.15 both from 2026-06-19 with v12.14 from 2026-03-16, so the package is still being released and the last push was on 2026-06-19.

The Places API deprecations that will break a call quietly

The README has a section on API deprecation notes, and the Places entries in it are the kind of change that causes a silent failure rather than an error.

Removed features are the straightforward case. Requests attempting to use Place Add, Place Delete, or Radar Search will receive an error.

Deprecated parameters and fields are the awkward case, because the request still succeeds and the result is subtly different from what the code expects.

For Nearby Search, the `types` parameter is deprecated and the `type` parameter, a string, should be used instead. For Place Details, the `reference` field is deprecated and `placeid` should be used, and the README notes that this package uses `placeid` by default. And for Place Add and Place Autocomplete, the `types` parameter should still be used, as per Google's documentation.

That last one is the sort of instruction that saves an afternoon. A parameter that another endpoint has deprecated is still correct for this one, and reading the deprecated-features list without the exception would lead you to change working code.

The practical advice for anyone maintaining an existing integration is to check which of your calls use `types` on a Nearby Search request and switch them to `type`, and to confirm that nothing is relying on the `reference` field in a Place Details response. The package defaults to the new behaviour, so a fresh installation will not hit these, but code that predates the change and constructs the request by hand will.

The rest of the README's guidance is the same in spirit. For service documentation, API key usage limits, and terms of service, it refers you to the official Google Maps documentation, and it links the Maps API Terms of Service and License Restrictions directly, which is the right thing for a wrapper around a billed third-party API to point at rather than paraphrase.

What this package is not, and where the boundary sits

The comparison worth making is with the alternative of talking to the API yourself, because for a single endpoint that is often the right answer.

Talking to the web services directly from Laravel is a cURL call with a query string. For one geocoding lookup in a small application, that is maybe fifteen lines, and it gives you exactly the response shape Google returns with no translation layer. The package earns its place when the number of endpoints grows, when you want the same key management and error handling everywhere, and when several people would otherwise each write their own request code differently.

The boundary is that this is a client for the web services only. It is not a maps rendering library, it does not place markers on a map, and it does not handle the Maps JavaScript API, which is a different product with different terms and a different pricing model. A Laravel application that wants a map on a page needs the JavaScript API in the browser, and a Laravel application that wants to geocode an address needs one of these web services. The two coexist in most projects and the package is only about the second.

The other alternative worth naming is a full geocoding or routing package that abstracts the provider away. Those are useful when you intend to switch providers, and they are a poor fit when you specifically want Google's data, because Google's routing, its place identifiers and its pricing are what you are paying for. This package stays close to the wire format on purpose, which is why you see a field mask and a dot notation for nested parameters in its examples: the abstraction does not try to hide what Google actually wants.

The cost of staying that close is that you inherit Google's breaking changes, which is exactly what the deprecation section is about. The package tracks them, and the Places notes show it doing so, but a wrapper cannot protect you from a field that stops being returned.

Editorial conclusion

Adopt google-maps for Laravel if your application needs the Google Maps web services and you want one fluent client for geocoding, places, elevation and routing rather than separate request code per endpoint. Do not start new work on the deprecated Directions and Distance Matrix services, because the package documents them as replaced by the Routes API, and check first which HTTP method you are on, since the Routes API is called with fetch() while every other service uses get(), and mixing them up returns a different response shape than you expect.

Frequently asked questions

Official sources

1. alexpechkarev/google-maps on GitHub
2. License: MIT
3. Project website
4. README
5. Releases