---
title: "Events — Geolocation for Laravel | Roundly"
description: "Listen for LocationResolved, DistanceResolved, LocationResolutionFailed and DistanceResolutionFailed to log, audit or react to lookups."
url: https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/events
language: en
---

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

[Geolocation for Laravel](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel.md)

# Events

While events.enabled is true (the default), the manager dispatches an event for every resolution:

| Event | Properties | Dispatched |
| --- | --- | --- |
| `LocationResolved` | query, location, provider | A provider returned a Location (provider = its pipeline name). |
| `DistanceResolved` | query, distance, provider | A distance provider returned a Distance. |
| `LocationResolutionFailed` | query, provider, error | A lookup ended without a location. Every provider missed: provider and error name the last unreachable provider and its redacted ProviderUnavailableException, or are both null when no provider had an answer. A provider threw: that provider and its exception, which is then rethrown. |
| `DistanceResolutionFailed` | query, provider, error | distance() or distanceBetween() ended without a distance. provider and error follow the same rules as LocationResolutionFailed — a request Google refused arrives as a redacted ProviderUnavailableException naming its status. |

```php
use Illuminate\Support\Facades\Event;
use RoundlyConsulting\Geolocation\Events\LocationResolved;

Event::listen(function (LocationResolved $event): void {
    logger()->info("Resolved {$event->location->city} via {$event->provider}");
});
```

More listeners — tracking routes and logging misses:

```php
use RoundlyConsulting\Geolocation\Events\DistanceResolutionFailed;
use RoundlyConsulting\Geolocation\Events\DistanceResolved;
use RoundlyConsulting\Geolocation\Events\LocationResolutionFailed;

Event::listen(function (DistanceResolved $event): void {
    logger()->info("Route of {$event->distance->distanceInMeters} m via {$event->provider}");
});

Event::listen(function (LocationResolutionFailed $event): void {
    logger()->warning('Geolocation miss', [
        'ip' => $event->query->ipAddress,
        'provider' => $event->provider,          // the last unreachable provider, or null
        'error' => $event->error?->getMessage(), // redacted — never carries credentials
    ]);
});

Event::listen(function (DistanceResolutionFailed $event): void {
    logger()->warning('Distance failed', [
        'provider' => $event->provider,          // e.g. 'google', or null
        'error' => $event->error?->getMessage(), // e.g. "Geolocation provider [google] is unavailable: PERMISSION_DENIED: …"
    ]);
});
```

- Cache hits dispatch no event — the result was already announced when it was first resolved.
- LocationResolutionFailed fires whenever a lookup ends without a location — including when every provider was unreachable. Once you configure a default location, the default provider answers whatever reaches it, so the event then fires only when a provider throws.
- DistanceResolutionFailed is its distance counterpart: it fires whenever distance() or distanceBetween() ends without a distance, naming the provider and error the same way — a key without the Routes API enabled shows up here.
- Their error never carries credentials: a ProviderUnavailableException message is redacted.
- distanceMatrix() dispatches no events.

```bash
GEOLOCATION_EVENTS=false   # stop dispatching all four events
```

## 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/geolocation-for-laravel.md)