Distance matrix

For many origins against many destinations, use matrix(). The travel-mode method runs the request and returns a DistanceMatrix you can index by pair:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

$matrix = GooglePlaces::matrix(
    origins: [new Location(48.1486, 17.1077), new Location(48.2082, 16.3738)],
    destinations: [new Location(50.0755, 14.4378), new Location(47.4979, 19.0402)],
)->driving();                       // ->driving() / ->walking() / ->bicycling() / ->transit()

$element = $matrix->for(0, 1);      // origin 0 → destination 1
if ($element?->hasRoute()) {
    echo $element->distance->humanReadableDistance;
    echo $element->distance->durationInSeconds;
}

$matrix->origin(0);                 // Collection<MatrixElement> keyed by destination index
$matrix->destination(1);            // Collection<MatrixElement> keyed by origin index

// Traffic-aware driving ETAs:
GooglePlaces::matrix($origins, $destinations)->departingAt(now()->addHour())->driving();

Unlike distance(), a matrix never throws for an unreachable pair — that element simply has no route. Check hasRoute() before reading its distance. Each MatrixElement carries originIndex, destinationIndex, condition, distance (a Distance or null) and Google’s status code.

Example: the nearest driver

Compare every driver against every order in one request, then pick the fastest driver for an order:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\MatrixElement;

$matrix = GooglePlaces::matrix($drivers, $orders)->driving();

// Index of the fastest driver for order 0:
$fastest = $matrix->destination(0)
    ->filter(fn (MatrixElement $element) => $element->hasRoute())
    ->sortBy(fn (MatrixElement $element) => $element->distance->durationInSeconds)
    ->keys()
    ->first();

Using a MatrixQuery directly

matrix() is a fluent shortcut over computeMatrix() — its travellingBy(TravelMode) and departingAt() match the query’s. Build a MatrixQuery yourself when you want to pass the whole query around:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\MatrixQuery;
use RoundlyConsulting\GooglePlaces\Enums\TravelMode;

$matrix = GooglePlaces::computeMatrix(
    (new MatrixQuery($origins, $destinations))
        ->travellingBy(TravelMode::Bicycling)
        ->departingAt(now()->addHour()),
);

$matrix->elements;          // list<MatrixElement>, sorted by origin then destination
$matrix->originCount;       // int
$matrix->destinationCount;  // int
$matrix->type;              // TravelMode

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages