---
title: "Distance matrix — Google Places for Laravel | Roundly"
description: "Compute many origins against many destinations in one call and index every pair, row or column of the result."
url: https://roundly-consulting.com/open-source/docs/google-places-for-laravel/distance-matrix
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Google Places for Laravel](https://roundly-consulting.com/open-source/docs/google-places-for-laravel.md)

# 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:

```php
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:

```php
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:

```php
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](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## 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](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/google-places-for-laravel.md)