---
title: "Locating — Geolocation for Laravel | Roundly"
description: "Resolve a Location from an IP, the current request, an address or coordinates — plus the Location object, JSON output and batch lookups."
url: https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/locating
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)

# Locating

Use the Geolocation facade — every method is also available on an injected GeolocationManager. The one-liner helpers cover the common cases:

```php
use RoundlyConsulting\Geolocation\DataTransferObjects\Coordinates;
use RoundlyConsulting\Geolocation\Facades\Geolocation;

$location = Geolocation::locateIp('8.8.8.8');
$location = Geolocation::locateRequest();                              // auto-detects the client IP

$location?->city;           // "Mountain View"
$location?->region;         // "California"
$location?->postalCode;     // "94043"
$location?->countryIsoCode; // "US"
$location?->timezone;       // "America/Los_Angeles" (IP providers only)
$location?->latitude;       // 37.4056

$location = Geolocation::locateAddress('1600 Amphitheatre Pkwy, Mountain View');

$location?->city;           // "Mountain View"
$location?->timezone;       // "" (Google geocoding returns no timezone)
$location?->latitude;       // 37.4224

$location = Geolocation::locateCoordinates(new Coordinates(48.1486, 17.1077));   // reverse geocoding
```

locateRequest() reads the IP from the current request (or the one you pass) and returns null when there is none. Behind a load balancer, configure Laravel’s trusted proxies so the request IP is the visitor’s, not the proxy’s.

Every helper returns null when no provider answers. A Location you do get back always places something — an empty answer ($location->isEmpty(): no address part, no country, 0,0 coordinates) is treated as a miss — though a coarse IP match can still lack a city or a country.

## Named queries

Every helper builds a GeolocationQuery and calls locate(). Build the query yourself when you already have one to pass around:

```php
use RoundlyConsulting\Geolocation\DataTransferObjects\Coordinates;
use RoundlyConsulting\Geolocation\DataTransferObjects\GeolocationQuery;
use RoundlyConsulting\Geolocation\Facades\Geolocation;

Geolocation::locate(GeolocationQuery::forIp('203.0.113.7'));
Geolocation::locate(GeolocationQuery::forAddress('Main Street 1, Springfield'));
Geolocation::locate(GeolocationQuery::forCoordinates(new Coordinates(48.1486, 17.1077)));
```

## Dependency injection

Every helper works the same on an injected GeolocationManager — type-hint it wherever Laravel resolves dependencies (see DI and actions):

```php
use Illuminate\Http\Request;
use RoundlyConsulting\Geolocation\GeolocationManager;

final class CheckoutController
{
    public function show(Request $request, GeolocationManager $geolocation)
    {
        $country = $geolocation->locateRequest($request)?->countryIsoCode;

        // ...
    }
}
```

## The Location object

| Property | Type | Contents |
| --- | --- | --- |
| `humanReadable` | `string` | Display label, e.g. a formatted address or “City, Region Country”. |
| `street` | `string` | Street — filled by Google only; empty for IP providers. |
| `city` | `string` | City name. |
| `region` | `string` | Region / state; defaults to ''. |
| `postalCode` | `string` | Postal code; defaults to ''. |
| `countryIsoCode` | `string` | ISO country code, e.g. US. |
| `latitude` | `float` | Latitude. |
| `longitude` | `float` | Longitude. |
| `timezone` | `string` | IANA timezone, e.g. America/Los\_Angeles — filled by the IP providers only; defaults to ''. |
| `type` | `GeolocationType` | Ip, Geolocation (Google) or Default (the fallback). |

Location and Distance implement Arrayable and JsonSerializable, so you can return them straight from a controller:

```php
return response()->json($location);   // Location is Arrayable + JsonSerializable

$location->toArray();
// ['humanReadable' => ..., 'street' => ..., 'city' => ..., 'region' => ..., 'postalCode' => ...,
//  'countryIsoCode' => ..., 'latitude' => ..., 'longitude' => ..., 'timezone' => ..., 'type' => 'IP']

$location->coordinates();   // a Coordinates value object
```

## Batch lookups

Resolve many IPs at once. The result is keyed by IP, and failures are isolated per item — any exception on one IP becomes null for that IP and the batch carries on. A scope or override chained before batch() applies to every IP:

```php
$results = Geolocation::batch(['8.8.8.8', '1.1.1.1', '203.0.113.7']);

$results['8.8.8.8']?->city;   // a Location or null per IP

foreach ($results as $ip => $location) {
    // $location is null when that one lookup failed — the batch never aborts
}

// A scope or override chained before batch() applies to every IP
Geolocation::using('maxmind_database', 'ipinfo')->batch($ips);
```

Each item runs through the normal pipeline, cache and events. HTTP providers pace a batch automatically under their rate-limit budget.

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