PHPackages                             geolax/geolocate - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. geolax/geolocate

ActiveLibrary[Utility & Helpers](/categories/utility)

geolax/geolocate
================

Extensible geolocation lookup for Laravel — driver-based, addon-ready

v1.1.0(3mo ago)049↓90%[3 PRs](https://github.com/geolax/geolocate/pulls)1MITPHPPHP ^8.2CI passing

Since Apr 2Pushed 2mo agoCompare

[ Source](https://github.com/geolax/geolocate)[ Packagist](https://packagist.org/packages/geolax/geolocate)[ Docs](https://github.com/geolax/geolocate)[ GitHub Sponsors](https://github.com/Frolax)[ RSS](/packages/geolax-geolocate/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (2)Dependencies (9)Versions (8)Used By (1)

Geolax Geolocate
================

[](#geolax-geolocate)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4cf20619c63a8dd3452ecbda5989ea9dfe71923b6faf51c79f578e216b628601/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67656f6c61782f67656f6c6f636174652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/geolax/geolocate)[![Total Downloads](https://camo.githubusercontent.com/6925ed72e7a1f280a250469d43648965b3ab3c24239299ec764f24896f3361ec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f67656f6c61782f67656f6c6f636174652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/geolax/geolocate)

Extensible geolocation lookup for Laravel — driver-based, addon-ready.

Geolax Geolocate provides a clean, driver-based architecture for IP geolocation. Install the base package, pick an addon (or build your own), and start looking up IPs in seconds.

Installation
------------

[](#installation)

```
composer require geolax/geolocate
```

Publish the config file:

```
php artisan vendor:publish --tag="geolocate-config"
```

Configuration
-------------

[](#configuration)

```
// config/geolocate.php

return [
    'default' => env('GEOLOCATE_DRIVER', 'freeipapi'),

    'drivers' => [
        'freeipapi' => [
            'driver'   => 'freeipapi',
            'base_url' => env('GEOLOCATE_FREEIPAPI_URL', 'https://freeipapi.com'),
            'api_key'  => env('GEOLOCATE_FREEIPAPI_KEY'),
            'server'   => env('GEOLOCATE_FREEIPAPI_SERVER', 'free'),
            'timeout'  => 5,
        ],
    ],
];
```

Available Addons
----------------

[](#available-addons)

AddonDriver NamePackage[FreeIPAPI](https://freeipapi.com)`freeipapi`[`geolax/freeipapi`](https://github.com/geolax/freeipapi)> Install an addon alongside the base package. Addons are auto-discovered by Laravel — no manual registration needed.

Usage
-----

[](#usage)

### Via Facade

[](#via-facade)

```
use Geolax\Geolocate\Facades\Geolocate;

$result = Geolocate::lookup('1.1.1.1');

$result->ipAddress;    // "1.1.1.1"
$result->countryName;  // "Australia"
$result->countryCode;  // "AU"
$result->cityName;     // "Sydney"
$result->latitude;     // -33.8688
$result->longitude;    // 151.209
$result->timezone;     // "Australia/Sydney"
$result->currency;     // "AUD"
$result->driver;       // "freeipapi"
```

### Via Dependency Injection

[](#via-dependency-injection)

```
use Geolax\Geolocate\Contracts\Driver;

class GeoController extends Controller
{
    public function __construct(private Driver $geolocate) {}

    public function locate(Request $request)
    {
        $result = $this->geolocate->lookup($request->ip());

        return response()->json($result->toArray());
    }
}
```

### Lookup Current Request IP

[](#lookup-current-request-ip)

```
// Pass null or no argument to look up the caller's IP
$result = Geolocate::lookup();
```

### Use a Specific Driver

[](#use-a-specific-driver)

```
$result = Geolocate::driver('freeipapi')->lookup('8.8.8.8');
```

### Access Raw Provider Data

[](#access-raw-provider-data)

Each provider may return additional fields beyond the standard DTO. Access them via the `raw` property:

```
$result = Geolocate::lookup('1.1.1.1');

$result->raw['asn'];             // "13335"
$result->raw['asnOrganization']; // "Cloudflare, Inc."
$result->raw['isProxy'];         // false
$result->raw['timeZones'];       // ["Australia/Sydney", "Australia/Melbourne", ...]
```

### The GeolocationResult DTO

[](#the-geolocationresult-dto)

Every lookup returns an immutable `GeolocationResult` with these properties:

PropertyTypeDescription`ipVersion``?int`4 or 6`ipAddress``?string`Resolved IP address`latitude``?float`Geographic latitude`longitude``?float`Geographic longitude`countryName``?string`Full country name`countryCode``?string`ISO 3166-1 alpha-2`regionName``?string`State/province/region`regionCode``?string`Region code`cityName``?string`City name`zipCode``?string`Postal/ZIP code`timezone``?string`Primary timezone`continent``?string`Continent name`continentCode``?string`Continent code`currency``?string`Primary currency code`driver``?string`Driver that produced this result`raw``array`Full provider responseCreating Your Own Addon
-----------------------

[](#creating-your-own-addon)

Any developer can create a geolocation addon without modifying the base package.

### 1. Create a Driver

[](#1-create-a-driver)

```