Distance & travel time

distance() measures from one origin. To a single Location it returns a Distance. To MultipleLocations it returns MultipleDistances: one separate trip from the origin to each destination — not a chained route, so there is no total. Choose the mode with the TravelMode enum:

use RoundlyConsulting\GooglePlaces\DataTransferObjects\DistanceQuery;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\Location;
use RoundlyConsulting\GooglePlaces\DataTransferObjects\MultipleLocations;
use RoundlyConsulting\GooglePlaces\Enums\TravelMode;
use RoundlyConsulting\GooglePlaces\Facades\GooglePlaces;

$distance = GooglePlaces::distance(new DistanceQuery(
    from: new Location(48.1486, 17.1077),  // Bratislava
    to: new Location(48.2082, 16.3738),    // Vienna
    type: TravelMode::Driving,             // Driving | Walking | Bicycling | Transit
    departureAt: now()->addHour(),         // optional; enables traffic-aware driving ETAs
));

echo $distance->humanReadableDistance; // e.g. "79.8 km" (formatted by the package)
echo $distance->distanceInMeters;      // e.g. 79800
echo $distance->humanReadableDuration; // e.g. "1h 5m"
echo $distance->durationInSeconds;     // e.g. 3900
echo $distance->type->value;           // "driving"

// One origin, several destinations → MultipleDistances, in destination order:
$fromBratislava = GooglePlaces::distance(new DistanceQuery(
    from: new Location(48.1486, 17.1077),
    to: new MultipleLocations([
        new Location(48.2082, 16.3738),    // Vienna
        new Location(50.0755, 14.4378),    // Prague
    ]),
));

foreach ($fromBratislava->distances as $i => $trip) {
    echo "Bratislava → destination {$i}: {$trip->humanReadableDistance}";
}

MultipleDistances->distances lists one Distance per destination, in the order you gave them, and ->type carries the travel mode. A single-element MultipleLocations still returns a plain Distance. For several origins at once, use matrix() — see Distance matrix. A destination with no available route raises a PlacesException.

Fluent queries

DistanceQuery is immutable and fluent — switch mode or departure time without rebuilding it:

$query = (new DistanceQuery(new Location(48.1486, 17.1077), new Location(48.2082, 16.3738)))
    ->transit()                         // or ->driving() / ->walking() / ->bicycling()
    ->departingAt(now()->addMinutes(30));

$distance = GooglePlaces::distance($query);  // single destination → Distance

$distance->isDriving();  // false
$distance->isWalking();  // false

A departure time is sent for every mode; for driving it also switches Google to traffic-aware routing.

Human-readable values

The Routes API does not return human-readable strings, so humanReadableDistance (kilometres, rounded to one decimal) and humanReadableDuration (a short interval such as “3h 20m”) are formatted by the package. The raw distanceInMeters and durationInSeconds are always there for your own formatting.

The TravelMode enum

TravelMode carries its Routes API value plus the enum helpers from enums-for-laravel — handy for a mode picker in a form:

use RoundlyConsulting\GooglePlaces\Enums\TravelMode;

TravelMode::Walking->routesValue();   // "WALK" — the Routes API value
TravelMode::values();                 // Collection: driving, walking, bicycling, transit
TravelMode::Transit->readable();      // "Transit"
TravelMode::options();                // {value, label, name} options for a select
TravelMode::validationRule();         // "in:driving,walking,bicycling,transit"

$request->validate(['mode' => ['required', TravelMode::validationRule()]]);

$query = $query->travellingBy(TravelMode::from($request->input('mode')));

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