Retrieve a user's location by their IP Address

Installs: 2 361 861

Dependents: 40

Suggesters: 1

Security: 0

Stars: 809

Watchers: 26

Forks: 150

Open Issues: 10

v6.6.2 2023-02-27 14:26 UTC


Retrieve a user's location from their IP address using various services.

68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73746576656261756d616e2f6c6f636174696f6e2f72756e2d74657374732e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265 68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f73746576656261756d616e2f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265 68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73746576656261756d616e2f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265 68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f73746576656261756d616e2f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265


  • PHP >= 7.3
  • PHP cURL extension enabled
  • Laravel >= 5.0


Install location using composer require:

composer require stevebauman/location

Add the service provider in config/app.php:

Important: If you're using Laravel 5.5 or above, you can skip the registration of the service provider, as it is registered automatically.


Publish the configuration file (this will create a location.php file inside the config/ directory):

php artisan vendor:publish --provider="Stevebauman\Location\LocationServiceProvider"


Retrieve a client's location

use Stevebauman\Location\Facades\Location;

if ($position = Location::get()) {
    // Successfully retrieved position.
    echo $position->countryName;
} else {
    // Failed retrieving position.


  • This method retrieves the user's IP address via request()->ip().
  • In the default configuration, testing.enabled is active, the returned IP address is in the USA. Disable it to get the client's real IP address.

Retrieve the location of a specific IP address

$position = Location::get('');


Available Drivers

Available drivers:

Setting up MaxMind with a self-hosted database (optional)

We encourage setting up MaxMind as a fallback driver using a local database, as it allows you to bypass any throttling that could occur from using external web services.

To set up MaxMind to retrieve the user's location from your own server, you must:

  1. Create a maxmind account.
  2. Sign in.
  3. Click "Download Files" from the left-hand navigation menu.
  4. Download the GeoLite2-City.tar.gz or GeoLite2-Country.tar.gz GZIP file depending on how precisely you need to locate people.
  5. Extract the downloaded file (you may need to use an application such as 7zip if on Windows).
  6. Create a maxmind folder inside your Laravel application's database directory (database/maxmind).
  7. Place the GeoLite2-City.mmdb or GeoLite2-Country.mmdb file into the maxmind directory. You should end up with a folder path of:
    • my-laravel-app/database/maxmind/GeoLite2-*.mmdb.
  8. Inside config/location.php, set your default location driver to Stevebauman\Location\Drivers\MaxMind::class.
  9. If you opted for the country database, edit maxmind.local.type to country and update maxmind.local.path.
  10. That's it, you're all set!

Note: Keep in mind, you'll need to update this file on a regular basis to retrieve the most current information from clients.

Fallback Drivers

In the config file, you can specify as many fallback drivers as you wish. It is recommended to install the MaxMind database .mmdb file, so you are always retrieving some generic location information for the user.

If an exception occurs trying to grab a driver (such as a 404 error if the providers API changes), it will automatically use the next driver in line.

Creating your own drivers

To create your own driver, simply create a class in your application, and extend the abstract Driver:

namespace App\Location\Drivers;

use Illuminate\Support\Fluent;
use Stevebauman\Location\Position;
use Stevebauman\Location\Drivers\Driver;

class MyDriver extends Driver
    public function url($ip)
        return "$ip";
    protected function process($ip)
        return rescue(function () use ($ip) {
            $response = json_decode(file_get_contents($this->url($ip)), true);
            return new Fluent($response);
        }, $rescue = false);

    protected function hydrate(Position $position, Fluent $location)
        $position->countryCode = $location->country_code;

        return $position;

Then, insert your driver class name into the configuration file:

| Driver
| The default driver you would like to use for location retrieval.

'driver' => App\Locations\MyDriver::class,


Location is versioned under the Semantic Versioning guidelines as much as possible.

Releases will be numbered with the following format:


And constructed with the following guidelines:

  • Breaking backward compatibility bumps the major and resets the minor and patch.
  • New additions without breaking backward compatibility bumps the minor and resets the patch.
  • Bug fixes and misc changes bumps the patch.

Minor versions are not maintained individually, and you're encouraged to upgrade through to the next minor version.

Major versions are maintained individually through separate branches.