PHPackages abdullmng/laravel-distance - 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. [Utility & Helpers](/categories/utility) 4. / 5. abdullmng/laravel-distance ActiveLibrary[Utility & Helpers](/categories/utility) abdullmng/laravel-distance ========================== Calculate straight-line and route-based distances between addresses or coordinates with built-in geocoding and routing 1.2.1(5mo ago)218↓100%MITPHPPHP ^8.2|^8.3|^8.4 Since Nov 19Pushed 5mo agoCompare [ Source](https://github.com/abdullmng/laravel-distance)[ Packagist](https://packagist.org/packages/abdullmng/laravel-distance)[ RSS](/packages/abdullmng-laravel-distance/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (5)Versions (5)Used By (0) Laravel Distance Calculator =========================== [](#laravel-distance-calculator) A comprehensive Laravel package for calculating distances between locations with built-in geocoding support. Perfect for logistics, ride-sharing, delivery, and location-based applications. Features -------- [](#features) - 🌍 **Multiple Geocoding Providers**: Nominatim (OpenStreetMap), Google Maps, Mapbox, and OpenCage - 📏 **Accurate Distance Calculations**: Haversine and Vincenty formulas for straight-line distances - 🛣️ **Route-Based Distances**: Calculate actual driving/walking/cycling distances using road networks - ⏱️ **Travel Time Estimates**: Get estimated duration for routes - 🔄 **Flexible Input**: Accept addresses, coordinates, or coordinate strings - 📦 **Multiple Units**: Kilometers, miles, meters, and feet - 💾 **Built-in Caching**: Reduce API calls and improve performance - 🎯 **Bearing & Direction**: Calculate bearing and compass direction between locations - 🔌 **Easy Integration**: Laravel service provider and facade support Requirements ------------ [](#requirements) - PHP 8.2, 8.3, or 8.4 - Laravel 10.x, 11.x, or 12.x Installation ------------ [](#installation) Install the package via Composer: ``` composer require abdullmng/laravel-distance ``` Publish the configuration file: ``` php artisan vendor:publish --tag=distance-config ``` Configuration ------------- [](#configuration) Configure your preferred geocoding and routing providers in `.env`: ``` # Geocoding Provider (nominatim, google, mapbox, opencage) GEOCODING_PROVIDER=nominatim # Routing Provider (osrm, mapbox, google) ROUTING_PROVIDER=osrm # Google Maps API Key (if using Google) GOOGLE_MAPS_API_KEY=your-api-key # Mapbox API Key (if using Mapbox) MAPBOX_API_KEY=your-api-key # OpenCage API Key (if using OpenCage) OPENCAGE_API_KEY=your-api-key # Nominatim settings (if using Nominatim) NOMINATIM_URL=https://nominatim.openstreetmap.org NOMINATIM_USER_AGENT=YourAppName/1.0 # Default distance unit (kilometers, miles, meters, feet) DISTANCE_UNIT=kilometers # Default routing mode (driving, walking, cycling) ROUTING_MODE=driving # Cache settings GEOCODING_CACHE_ENABLED=true GEOCODING_CACHE_DURATION=1440 ``` Usage ----- [](#usage) ### Straight-Line Distance Calculation [](#straight-line-distance-calculation) ``` use Abdullmng\Distance\Facades\Distance; // Calculate straight-line distance between two addresses $result = Distance::between( 'New York, NY', 'Los Angeles, CA' ); echo $result->distance; // Distance in default unit (km) echo $result->inMiles(); // Convert to miles echo $result->inMeters(); // Convert to meters ``` ### Route-Based Distance Calculation [](#route-based-distance-calculation) ``` // Calculate actual driving distance using road networks $route = Distance::route( 'Lagos, Nigeria', 'Abuja, Nigeria' ); echo $route->distance; // Distance in default unit (km) echo $route->duration; // Duration in seconds echo $route->formattedDuration(); // e.g., "6h 30m" echo $route->inMiles(); // Convert to miles ``` ### Comparing Straight-Line vs Route Distance [](#comparing-straight-line-vs-route-distance) ``` // Straight-line (as the crow flies) $straightLine = Distance::between('Lagos', 'Abuja'); echo "Straight-line: {$straightLine->inKilometers()} km\n"; // Route-based (actual driving distance) $route = Distance::route('Lagos', 'Abuja'); echo "Route: {$route->inKilometers()} km\n"; echo "Duration: {$route->formattedDuration()}\n"; ``` ### Different Travel Modes [](#different-travel-modes) ``` // Driving (default) $driving = Distance::route($from, $to, ['mode' => 'driving']); // Walking $walking = Distance::route($from, $to, ['mode' => 'walking']); // Cycling $cycling = Distance::route($from, $to, ['mode' => 'cycling']); ``` ### Using Coordinates [](#using-coordinates) ``` use Abdullmng\Distance\DTOs\Coordinate; // Using Coordinate objects $from = new Coordinate(40.7128, -74.0060); // New York $to = new Coordinate(34.0522, -118.2437); // Los Angeles // Straight-line distance $result = Distance::between($from, $to); // Route distance $route = Distance::route($from, $to); ``` ### Using Coordinate Strings [](#using-coordinate-strings) ``` // Using coordinate strings $result = Distance::between( '40.7128,-74.0060', '34.0522,-118.2437' ); ``` ### Specify Unit [](#specify-unit) ``` // Calculate in miles $result = Distance::between('New York, NY', 'Los Angeles, CA', 'miles'); // Or use the unit() method $result = Distance::unit('miles')->between('New York, NY', 'Los Angeles, CA'); ``` ### Geocoding [](#geocoding) ``` // Simple geocoding $coordinate = Distance::geocode('1600 Amphitheatre Parkway, Mountain View, CA'); echo $coordinate->latitude; echo $coordinate->longitude; echo $coordinate->formattedAddress; echo $coordinate->accuracy; // Quality score (0-1) echo $coordinate->source; // Which provider was used // Reverse geocode $address = Distance::reverse(37.4224764, -122.0842499); echo $address; // "1600 Amphitheatre Parkway, Mountain View, CA..." ``` ### Structured Geocoding (Improved Accuracy) [](#structured-geocoding-improved-accuracy) For better accuracy, especially in developing countries, use structured geocoding: ``` use Abdullmng\Distance\DTOs\StructuredAddress; $address = new StructuredAddress( houseNumber: '24', street: 'Obi Okosi Street', neighbourhood: 'Hill-Side Estate', suburb: 'Gwarimpa', city: 'Abuja', country: 'Nigeria' ); $coordinate = Distance::geocodeStructured($address); if ($coordinate->isHighAccuracy()) { echo "High quality result!\n"; echo "Coordinates: {$coordinate->latitude}, {$coordinate->longitude}\n"; } ``` ### Geocoding Quality Scores [](#geocoding-quality-scores) All geocoding results include accuracy scores to help you make informed decisions: ``` $coordinate = Distance::geocode('Gwarimpa, Abuja, Nigeria'); if ($coordinate->isHighAccuracy()) { // accuracy >= 0.8 - Safe to use echo "High quality result\n"; } elseif ($coordinate->isLowAccuracy()) { // accuracy < 0.5 - May be inaccurate echo "Low quality - consider structured geocoding\n"; } else { // 0.5 distance; // Distance in configured unit echo $result->unit; // Unit used echo $result->from->latitude; // Starting coordinate echo $result->to->longitude; // Ending coordinate // Convert to different units echo $result->inKilometers(); echo $result->inMiles(); echo $result->inMeters(); echo $result->inFeet(); // Get as array $array = $result->toArray(); ``` Advanced Geocoding Features --------------------------- [](#advanced-geocoding-features) ### Fallback Chain [](#fallback-chain) Automatically try multiple geocoding providers until you get a high-quality result: ``` GEOCODING_USE_FALLBACK=true GEOCODING_MIN_ACCURACY=0.7 ``` ``` // config/distance.php 'use_fallback_chain' => true, 'fallback_providers' => [ 'nominatim', // Try free provider first 'opencage', // Then OpenCage 'mapbox', // Then Mapbox 'google', // Last resort (most expensive) ], 'minimum_accuracy' => 0.7, ``` ### Local Coordinate Cache [](#local-coordinate-cache) Cache frequently used addresses for instant, 100% accurate results: ``` // config/distance.php 'local_coordinates' => [ 'Main Warehouse Lagos' => [ 'lat' => 6.5244, 'lon' => 3.3792, 'formatted' => 'Main Warehouse, Apapa, Lagos, Nigeria' ], 'Office Abuja' => [ 'lat' => 9.0765, 'lon' => 7.3986, 'formatted' => 'Head Office, Abuja, Nigeria' ], ], ``` ``` // Checks local cache first (instant, no API calls) $coordinate = Distance::geocode('Main Warehouse Lagos'); echo $coordinate->source; // 'local_cache' echo $coordinate->accuracy; // 1.0 (100%) ``` For more details, see [GEOCODING\_ACCURACY.md](GEOCODING_ACCURACY.md). Geocoding Providers ------------------- [](#geocoding-providers) ### Nominatim (OpenStreetMap) - Free [](#nominatim-openstreetmap---free) No API key required. Great for development and low-volume applications. ``` GEOCODING_PROVIDER=nominatim NOMINATIM_USER_AGENT=YourAppName/1.0 ``` ### Google Maps - Paid [](#google-maps---paid) Highly accurate with extensive coverage. ``` GEOCODING_PROVIDER=google GOOGLE_MAPS_API_KEY=your-api-key ``` ### Mapbox - Freemium [](#mapbox---freemium) Good balance of accuracy and pricing. ``` GEOCODING_PROVIDER=mapbox MAPBOX_API_KEY=your-api-key ``` ### OpenCage - Freemium [](#opencage---freemium) Aggregates multiple data sources. ``` GEOCODING_PROVIDER=opencage OPENCAGE_API_KEY=your-api-key ``` Use Cases --------- [](#use-cases) ### Logistics & Delivery Apps [](#logistics--delivery-apps) ``` // Calculate delivery distance $warehouse = new Coordinate(40.7128, -74.0060); $customer = '123 Main St, Brooklyn, NY'; $result = Distance::between($warehouse, $customer, 'kilometers'); if ($result->distance > 50) { // Out of delivery range } ``` ### Ride-Sharing Apps [](#ride-sharing-apps) ``` // Find distance between driver and passenger $driver = '40.7580,-73.9855'; $passenger = '40.7489,-73.9680'; $result = Distance::between($driver, $passenger, 'miles'); $eta = $result->distance / 30; // Assuming 30 mph average speed ``` ### Store Locator [](#store-locator) ``` $userLocation = Distance::geocode($userAddress); $stores = Store::all(); foreach ($stores as $store) { $storeCoord = new Coordinate($store->latitude, $store->longitude); $distance = Distance::between($userLocation, $storeCoord, 'miles'); $store->distance = $distance->distance; } $nearestStores = $stores->sortBy('distance')->take(5); ``` Documentation ------------- [](#documentation) - [Routing Guide](ROUTING.md) - Comprehensive guide for route-based distance calculations - [Mapbox Geocoding Guide](MAPBOX_GEOCODING.md) - Mapbox geocoding setup and troubleshooting - [Quick Start Guide](QUICKSTART.md) - Get started quickly with examples - [Contributing Guide](CONTRIBUTING.md) - How to contribute to this package Testing ------- [](#testing) ``` composer test ``` License ------- [](#license) MIT License. See [LICENSE](LICENSE) for more information. Credits ------- [](#credits) - [Muhammad Abdullahi](https://github.com/abdullmng) Support ------- [](#support) For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/abdullmng/laravel-distance). ### Health Score 38 — LowBetter than 85% of packages Maintenance70 Regular maintenance activity Popularity10 Limited adoption so far Community6 Small or concentrated contributor base Maturity55 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 Every ~1 days Total 4 Last Release 171d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/59dfc613133e955181aff1cfb6ceeb74e68782fe5b60b153de6a6dada4de3e4c?d=identicon)[abdullmng](/maintainers/abdullmng) --- Top Contributors [![abdullmng](https://avatars.githubusercontent.com/u/42342425?v=4)](https://github.com/abdullmng "abdullmng (6 commits)") --- Tags laravelgeocodinggeolocationroutingaddressesdistancedeliverylogisticsride-sharing ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/abdullmng-laravel-distance/health.svg) ``` [![Health](https://phpackages.com/badges/abdullmng-laravel-distance/health.svg)](https://phpackages.com/packages/abdullmng-laravel-distance) ``` ### Alternatives [stevebauman/location Retrieve a user's location by their IP Address 1.3k7.6M65](/packages/stevebauman-location)[watson/active Laravel helper for recognising the current route, controller and action 3253.6M14](/packages/watson-active)[adrianorosa/laravel-geolocation Laravel Geo Location package to get details for a given IP Address 6593.3k1](/packages/adrianorosa-laravel-geolocation)[nativephp/mobile NativePHP for Mobile 82724.0k43](/packages/nativephp-mobile)[bensampo/laravel-embed Painless responsive embeds for videos, slideshows and more. 142146.8k](/packages/bensampo-laravel-embed)[glhd/conveyor-belt 14797.0k](/packages/glhd-conveyor-belt) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)