Open source
Geolocation for Laravel
composer require roundly-consulting/geolocation-for-laravelOverview
A native geolocation layer for Laravel. Resolve a location from an IP address, a street address or a pair of coordinates — and the travel distance between two points — through an ordered pipeline of providers: MaxMind, IP2Location, IPinfo, Google and a configurable fallback. It ships a native .mmdb reader for fully offline IP lookups, geofencing helpers, an Eloquent coordinates cast, a validation rule, caching, events and a test fake. MIT-licensed and built on Laravel’s own HTTP client — no vendor SDKs, just three small Roundly packages as dependencies.
What you get
Provider pipeline
MaxMind, IP2Location, IPinfo, Google and a static fallback, tried in order — the first real answer wins, an unreachable API is skipped. Reorder in config or pin one per call.
Native MaxMind reader
Offline IP lookups from a local .mmdb file with a built-in binary reader, plus a command that downloads and refreshes the database.
Distance & matrices
Driving or walking distance and duration via Google, whole origin × destination grids in one call, and Haversine distance offline.
Geofencing & Eloquent
Radius checks, point-in-polygon, bearings, midpoints and bounding boxes, plus a Coordinates cast and a withinRadius() query scope.
Paced, cached, observable
Per-provider rate limits with adaptive Retry-After backoff, optional lookup caching and resolution events you can listen to.
Facade, DI & a recording fake
Call the Geolocation facade or inject GeolocationManager; Geolocation::fake() records lookups, distances, refreshes and cache calls.
Validation & tooling
A coordinates validation rule, a $request->location() macro and two Artisan commands — locate from the terminal, refresh MaxMind.
Documentation
Installation
Install via Composer, optionally publish the config, and resolve your first location in one line — no migrations to run.
Configuration
Every config key, default and env variable — pipeline, providers, timeout, cache, events, the fallback location and each provider’s service block.
The Geolocation facade
Every Geolocation facade method in one place — locate, batch, distance and matrix, scoping and overrides, database refresh and cache control.
DI and actions
Skip the facade: inject GeolocationManager for the same API, or run the MaxMind refresh as UpdateDatabaseAction from your own jobs.
How it works
An ordered pipeline of named providers — the first real answer wins, unreachable APIs are skipped and an optional static default is the last resort.
Providers
Set up IPinfo, IP2Location, Google and the default fallback — credentials, what each provider resolves and which Location fields it fills.
MaxMind
Offline IP lookups from a local .mmdb file with the native reader, database downloads via Artisan, and the GeoIP2 Precision web service.
Locating
Resolve a Location from an IP, the current request, an address or coordinates — plus the Location object, JSON output and batch lookups.
Coordinates, queries & enums
The validated Coordinates value object, Haversine distance, the GeolocationQuery and DistanceQuery named constructors, and both enums.
Distance & matrix
Driving or walking distance and travel time between two points, and a full origin × destination grid in a single call.
Geofencing
Radius checks, point-in-polygon zones, bearings, midpoints and bounding boxes on Coordinates — pure PHP, no API calls.
Eloquent models
Store a Coordinates value object on any model with the HasLocation trait or CoordinatesCast, and query nearby rows with withinRadius().
Validation & requests
Validate latitude/longitude input with Rule::coordinates() and resolve the visitor’s location with the $request->location() macro.
Per-call options
Pin a call to specific providers, override one provider’s credential or the timeout for a single call chain, and add your own manager methods as macros.
Custom providers
Plug your own location or distance source into the pipeline with extend() or the providers map, with call-time overrides and rate limits.
Rate limiting
Pace every HTTP provider under its own budget with adaptive Retry-After backoff, or fail fast with a typed exception past a ceiling.
Caching
Cache successful locate() and distance() results on any cache store to cut API costs and latency — failures are never cached.
Events
Listen for LocationResolved, DistanceResolved and LocationResolutionFailed to log, audit or react to lookups.
Artisan commands
Resolve a location from the terminal to smoke-test credentials, and download or refresh the MaxMind database.
Exceptions
Every typed exception the package throws and when, how unreachable providers are skipped, and how to catch everything in one place.
Testing
Geolocation::fake() records lookups, distances, refreshes and cache calls with seeded results — or fake the HTTP layer and the rate limiter.
Requirements
PHP 8.4+, Laravel 12 or 13, ext-zlib and ext-phar, plus credentials only for the HTTP providers you enable.
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 cryptoBy donating, you agree to our donation terms.
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.