PHPackages                             mydaniel/laravel-geolocation - 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. mydaniel/laravel-geolocation

ActiveLibrary

mydaniel/laravel-geolocation
============================

A flexible, multi-driver geolocation package for Laravel.

v1.0.0(8mo ago)02MITPHPPHP ^8.1|^8.2|^8.3|^8.4

Since Aug 22Pushed 8mo agoCompare

[ Source](https://github.com/daniyousefifar/laravel-geolocation)[ Packagist](https://packagist.org/packages/mydaniel/laravel-geolocation)[ RSS](/packages/mydaniel-laravel-geolocation/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

Laravel GeoLocation
===================

[](#laravel-geolocation)

[![Latest Version on Packagist](https://camo.githubusercontent.com/fd678b5c344a84edae1657807b4f7434cdae1f72f2a280c8ef6278e052acd36d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d7964616e69656c2f6c61726176656c2d67656f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mydaniel/laravel-geolocation)[![Total Downloads](https://camo.githubusercontent.com/27aac2f05230b3a3fff9757fbd30f21467c683220c53f3d7a8af0157843354ff/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d7964616e69656c2f6c61726176656c2d67656f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mydaniel/laravel-geolocation)[![License](https://camo.githubusercontent.com/5ca7cd75af9d71364c6e2ab93af3e9af3c8f23f1a677704245290f40bce5703f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d7964616e69656c2f6c61726176656c2d67656f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/daniyousefifar/laravel-geolocation/blob/main/LICENSE.md)

A powerful, flexible, and multi-driver geolocation package for Laravel. It provides a simple yet robust way to retrieve geographical information for an IP address from various services.

This package is designed to be highly extensible and resilient, with built-in support for caching, fallback drivers, and an elegant, fluent API.

Features
--------

[](#features)

- **Multi-Driver Support**: Switch between services with a simple config change.
    - **ip-api.com** (`ipapicom`): Supports both free and Pro tiers.
    - **ipapi.co** (`ipapico`): Simple and free to use.
    - **IPQuery.io** (`ipquery`): A fast and reliable service.
    - **iplocate.io** (`iplocate`): Another excellent API-based driver.
    - **MaxMind** (`maxmind`): Use local GeoLite2/GeoIP2 databases for offline lookups.
    - **Chain Driver** (`chain`): Define a sequence of drivers to try until one succeeds.
    - **Null Driver** (`null`): Returns static data, perfect for testing.
- **Robust Caching**: Automatically caches results to reduce API calls and improve performance. Supports cache tags for easy clearing.
- **Fallback & Chain Logic**: Built-in support for a simple fallback driver or a more powerful chain of drivers to ensure high availability.
- **Rich `Location` Object**: Returns a well-structured DTO with fluent getters and useful helper methods like `distanceTo()`.
- **Artisan Commands**: Includes convenient commands to test lookups and clear the cache directly from your terminal.
- **Extensible Architecture**: Easily add your own custom geolocation driver.
- **IPv4 & IPv6 Support**: Validates and locates both IP address formats.

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

[](#installation)

You can install the package via Composer:

```
composer require mydaniel/laravel-geolocation
```

Next, publish the configuration file using the `vendor:publish` command:

```
php artisan vendor:publish --provider="MyDaniel\GeoLocation\GeoLocationServiceProvider" --tag="geolocation-config"
```

If you plan to use the MaxMind driver, you should also publish the database file. The package includes a placeholder GeoLite2 database.

```
php artisan vendor:publish --provider="MyDaniel\GeoLocation\GeoLocationServiceProvider" --tag="geolocation-database"
```

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

[](#configuration)

After publishing, the configuration file will be located at `config/geolocation.php`. Here you can define your default driver and configure each service.

### Driver Configuration

[](#driver-configuration)

Set your default driver and API keys in your `.env` file.

```
# The default driver to use (e.g., ipapico, ipapicom, ipquery, maxmind, chain)
GEOLOCATION_DRIVER=chain

# API keys for the services you use
IPAPI_KEY=your_ipapicom_pro_key
IPLOCATE_KEY=your_iplocate_key

# --- Chain Driver Example ---
# If GEOLOCATION_DRIVER=chain, it will use the drivers defined in the config.
# By default, it tries 'ipapico' then 'maxmind'.

# --- Fallback Driver ---
# Alternatively, you can define a single fallback driver.
GEOLOCATION_FALLBACK_DRIVER=maxmind
```

### Cache Configuration

[](#cache-configuration)

Caching is enabled by default. You can configure the cache settings in `config/geolocation.php` or via `.env` variables.

```
GEOLOCATION_CACHE_ENABLED=true
GEOLOCATION_CACHE_TTL=1440 # In minutes (1440 = 24 hours)
```

Usage
-----

[](#usage)

The package provides a simple and expressive API. Use the `GeoLocation` facade to perform lookups.

### Basic Lookup

[](#basic-lookup)

```
use MyDaniel\GeoLocation\Facades\GeoLocation;

$location = GeoLocation::locate('8.8.8.8');

echo $location->getCountry(); // "United States"
echo $location->getCity();     // "Mountain View"
echo $location->getLat();      // 37.422
echo $location->getLon();      // -122.084
```

### The `Location` Object

[](#the-location-object)

The `locate` method returns a `MyDaniel\GeoLocation\Location` object, which has the following getters:

- `getIp(): string`
- `getIsoCode(): ?string`
- `getCountry(): ?string`
- `getCity(): ?string`
- `getState(): ?string`
- `getPostalCode(): ?string`
- `getLat(): ?float`
- `getLon(): ?float`
- `getTimezone(): ?string`
- `getContinent(): ?string`
- `getCurrencyCode(): ?string`
- `getCurrencyName(): ?string`
- `getCurrencySymbol(): ?string`
- `getAsnNumber(): ?int`
- `getAsnOrganization(): ?string`
- `isFromCache(): bool`
- `toArray(): array`

### Calculating Distance

[](#calculating-distance)

You can easily calculate the distance between two locations using the `distanceTo` method.

```
$locationA = GeoLocation::locate('8.8.8.8');    // Google DNS
$locationB = GeoLocation::locate('1.1.1.1');    // Cloudflare DNS

// Calculate distance in kilometers (default)
$distanceInKm = $locationA->distanceTo($locationB);

// Calculate distance in miles
$distanceInMiles = $locationA->distanceTo($locationB, 'mi');
```

### Checking Cache Status

[](#checking-cache-status)

You can check if the result was retrieved from the cache.

```
$location = GeoLocation::locate('1.1.1.1');

if ($location->isFromCache()) {
    // This response was served from the cache.
}
```

### Using a Specific Driver

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

You can use a specific driver on the fly, overriding the default driver from your config file.

```
$location = GeoLocation::driver('maxmind')->locate('1.1.1.1');
```

Artisan Commands
----------------

[](#artisan-commands)

The package includes two helpful Artisan commands.

### Locate an IP

[](#locate-an-ip)

To quickly test a lookup from your terminal:

```
php artisan geolocation:locate 8.8.8.8
```

### Clear the Geolocation Cache

[](#clear-the-geolocation-cache)

This command will clear only the cache entries created by this package by flushing the `geolocation` tag.

```
php artisan geolocation:clear-cache
```

Extending the Package
---------------------

[](#extending-the-package)

You can easily add your own custom driver.

1. **Create your driver class** and implement the `MyDaniel\GeoLocation\Contracts\GeolocationDriver` interface.
2. **Register your driver** in the `boot` method of a service provider (e.g., `app/Providers/AppServiceProvider.php`) using the `extend` method.

```
// in a Service Provider's boot() method
use MyDaniel\GeoLocation\Facades\GeoLocation;
use App\Services\MyCustomGeoDriver; // Your custom driver class

public function boot()
{
    GeoLocation::extend('my_driver', function ($app) {
        return new MyCustomGeoDriver();
    });
}
```

3. Set your new driver in the `config/geolocation.php` file or your `.env` file: `GEOLOCATION_DRIVER=my_driver`.

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to fork the repository and submit a pull request.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

33

—

LowBetter than 74% of packages

Maintenance62

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

260d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d44388ec13369a9d7c4f7e3a81d5fb52269f260a77c10aad4ce6cbe3f2969942?d=identicon)[mydaniel](/maintainers/mydaniel)

---

Top Contributors

[![daniyousefifar](https://avatars.githubusercontent.com/u/38884107?v=4)](https://github.com/daniyousefifar "daniyousefifar (3 commits)")

---

Tags

laravelgeoipgeolocationIP

### Embed Badge

![Health badge](/badges/mydaniel-laravel-geolocation/health.svg)

```
[![Health](https://phpackages.com/badges/mydaniel-laravel-geolocation/health.svg)](https://phpackages.com/packages/mydaniel-laravel-geolocation)
```

###  Alternatives

[spatie/laravel-responsecache

Speed up a Laravel application by caching the entire response

2.8k8.2M51](/packages/spatie-laravel-responsecache)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[stevebauman/location

Retrieve a user's location by their IP Address

1.3k7.6M65](/packages/stevebauman-location)[torann/geoip

Support for multiple Geographical Location services.

2.2k14.2M76](/packages/torann-geoip)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[torchlight/torchlight-laravel

A Laravel Client for Torchlight, the syntax highlighting API.

120452.8k11](/packages/torchlight-torchlight-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)