README.md

Roomies Geolocatable

Determine the geographical location, currency and network information of website users based on their IP addresses.

Geolocatable is an abstraction over multiple IP geolocation services including Cloudflare, Ip2Location, ipapi.co ipapi.com, ip-api.com, ipdata, Maxmind GeoIP database and web services.

It's based off of laravel-geoip, but there are some key differences that may affect your decision:

• it allows you to use multiple providers with different configurations,
• it doesn't implement caching behaviour,
• it doesn't implement a fallback/default location.

Installation

You can install the package via Composer:

composer require roomies/geolocatable

You can publish the config file with:

php artisan vendor:publish --tag="geolocatable-config"

Read through the config file to understand the supported services and provide the correct configuration for your preferred services.

Getting started

You can perform an IP address geolcaton using the Facade.

use Roomies\Geolocatable\Facades\Geolocation;

// Returns an instance of \Roomies\Geolocatable\Result\Geolocation
$result = Geolocate::ip('129.168.0.1');

echo "Looks like you are in {$result->country}, roughly around {$result->latitude}, {$result->longitude}.";

Depending on the provider you choose different combinations of information will be available. It will also depend specifically on the IP address itself and what data the provider has. However, Geolocatable returns a typed readonly class that provides access to structured attributes as well as the raw result if you require it.

• IP address
• location: Roomies\Geolocatable\Result\Location
  • continent name
  • country name and country ISO
  • state name and state ISO
  • city name
  • postal code
  • latitude
  • longitude
  • timezone
• network: Roomies\Geolocatable\Result\Network
  • organization
  • ISP
  • domain
  • is a proxy network
  • is a mobile network
  • is a hosting network
  • is an anonymous network
• currency: Roomies\Geolocatable\Result\Currency
  • name
  • code
  • symbol
• raw: the raw result from the geolocation provider

You can also change the provider you use on the fly.

Geolocate::using('maxmind_database')->ip('192.168.0.1');

Cloudflare

If you have Cloudflare in front of your website you can add visitor location headers to your app using a managed transform. It doesn't have as much information as other providers and it can only be used for the IP address that makes the request, but it is a great free option if you don't need greater detail.

Ip2Location

Ip2Location is a freemium service that starts at 30,000 lookups/month for free.

Check the config file or provide your IP2LOCATION_KEY in the environment.

ipapi.co

ipapi is a freemium service.

ipapi.com

Proivide your IPAPI_KEY API key to use this API.

ip-api.com

ip-api is a freemium service.

ipdata

Provide your IPDATA_KEY API key to use this API.

Maxmind Database

Provide your Maxmind account_id and license_key to download the Maxmind database.

Once configured you need to install the geoip2 dependency and then download the database.

composer require geoip2/geoip2
php artisan geolocatable:download

You can choose to update the database on your own schedule.

Maxmind Web Services

Provide your Maxmind account_id and license_key to use Maxmind Web Services.

By default it will use the city level for IP address details but you can control this.

Testing

Geolocatable includes a fake which makes it easy for you to test how your app handles different results. It allows you to stub the res

$result = new Roomies\Geolocatable\Result\Geolocation(
    source: 'fake',
    ipAddress: '192.168.0.1',
    raw: []
);

Geolocate::fake($result);

License

The MIT License (MIT). Please see License File for more information.