--- title: "Geolocation for Laravel — docs | Roundly" description: "Developer docs for Geolocation for Laravel: IP, address and coordinate lookups, a native MaxMind reader, distances, geofencing, rate limits and testing." url: https://roundly-consulting.com/open-source/docs/geolocation-for-laravel language: en --- [All packages](https://roundly-consulting.com/open-source.md) Open source # Geolocation for Laravel Install `composer require roundly-consulting/geolocation-for-laravel` Requires: PHP ^8.4 · Laravel ^12.0|^13.0 [GitHub](https://github.com/roundly-consulting/geolocation-for-laravel) [Packagist](https://packagist.org/packages/roundly-consulting/geolocation-for-laravel) [Donate (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Patreon](https://www.patreon.com/cw/roundly) ## Overview 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’s Routes API, 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](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/installation.md) Install via Composer, optionally publish the config, and resolve your first location in one line — no migrations to run. #### [Configuration](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/configuration.md) Every config key, default and env variable — pipeline, providers, timeout, cache, events, the fallback location and each provider’s service block. #### [The Geolocation facade](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/facade.md) Every Geolocation facade method in one place — locate, batch, distance and matrix, scoping and overrides, database refresh and cache control. #### [DI and actions](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/without-facade.md) Skip the facade: inject GeolocationManager for the same API, or run the MaxMind refresh as UpdateDatabaseAction from your own jobs. #### [How it works](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/how-it-works.md) 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](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/providers.md) Set up IPinfo, IP2Location, Google and the default fallback — credentials, what each provider resolves and which Location fields it fills. #### [MaxMind](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/maxmind.md) Offline IP lookups from a local .mmdb file with the native reader, database downloads via Artisan, and the GeoIP2 Precision web service. #### [Locating](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/locating.md) 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](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/coordinates.md) The validated Coordinates value object, Haversine distance, the GeolocationQuery and DistanceQuery named constructors, and both enums. #### [Distance & matrix](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/distance.md) Driving or walking distance and travel time between two points, and a full origin × destination grid in a single call. #### [Geofencing](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/geofencing.md) Radius checks, point-in-polygon zones, bearings, midpoints and bounding boxes on Coordinates — pure PHP, no API calls. #### [Eloquent models](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/eloquent-models.md) Store a Coordinates value object on any model with the HasLocation trait or CoordinatesCast, and query nearby rows with withinRadius(). #### [Validation & requests](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/validation.md) Validate latitude/longitude input with Rule::coordinates() and resolve the visitor’s location with the $request->location() macro. #### [Per-call options](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/per-call-options.md) 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](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/custom-providers.md) 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](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/rate-limiting.md) Pace every HTTP provider under its own budget with adaptive Retry-After backoff, or fail fast with a typed exception past a ceiling. #### [Caching](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/caching.md) Cache successful locate() and distance() results on any cache store to cut API costs and latency — failures are never cached. #### [Events](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/events.md) Listen for LocationResolved, DistanceResolved, LocationResolutionFailed and DistanceResolutionFailed to log, audit or react to lookups. #### [Artisan commands](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/commands.md) Resolve a location from the terminal to smoke-test credentials, and download or refresh the MaxMind database. #### [Exceptions](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/exceptions.md) Every typed exception the package throws and when, how unreachable providers are skipped, and how to catch everything in one place. #### [Testing](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/testing.md) Geolocation::fake() records lookups, distances, refreshes and cache calls with seeded results — or fake the HTTP layer and the rate limiter. #### [Requirements](https://roundly-consulting.com/open-source/docs/geolocation-for-laravel/requirements.md) 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 crypto](https://roundly-consulting.com/support-us.md) By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md). [Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly) ## 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. [Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source.md)