PHPackages kulykovoleksii/laravel-geocoding - 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. kulykovoleksii/laravel-geocoding ActiveLibrary[Utility & Helpers](/categories/utility) kulykovoleksii/laravel-geocoding ================================ Universal geocoding and postal code lookup for PHP with support for multiple countries. Framework-agnostic core with first-class Laravel integration. v1.0.0(2mo ago)03MITPHPPHP ^8.1|^8.2|^8.3 Since Mar 7Pushed 2mo agoCompare [ Source](https://github.com/kulykovoleksii/laravel-geocoding)[ Packagist](https://packagist.org/packages/kulykovoleksii/laravel-geocoding)[ RSS](/packages/kulykovoleksii-laravel-geocoding/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (6)Versions (2)Used By (0) Laravel Geocoding ================= [](#laravel-geocoding) Universal geocoding and postal code lookup package for Laravel with support for multiple countries worldwide. Features -------- [](#features) - Multi-country support (UK, USA, Ukraine, Canada, and more) - Multiple geocoding providers with automatic fallback - Free UK postcode lookup via Postcodes.io API - Google Maps Geocoding API integration for worldwide coverage - Database caching to minimize API calls - Reverse geocoding from coordinates to addresses - Hierarchical region management - Comprehensive test suite Requirements ------------ [](#requirements) - PHP 8.1 or higher - Laravel 10.0 or 11.0 - MySQL/PostgreSQL database Installation ------------ [](#installation) Install the package via Composer: ``` composer require kulykovoleksii/laravel-geocoding ``` Publish the configuration file: ``` php artisan vendor:publish --tag=geocoding-config ``` Publish and run migrations: ``` php artisan vendor:publish --tag=geocoding-migrations php artisan migrate ``` Configuration ------------- [](#configuration) Add your Google Maps API key to `.env` (optional but recommended for worldwide coverage): ``` GOOGLE_MAPS_API_KEY=your_api_key_here ``` Get your API key at: **Pricing:** $200/month free credit (approximately 40,000 requests/month free) Usage ----- [](#usage) ### Basic Usage [](#basic-usage) ``` use Kulykovoleksii\Geocoding\Services\Geocoding\GeocodingService; $geocoding = app(GeocodingService::class); // Lookup UK postcode (uses free Postcodes.io) $result = $geocoding->lookupPostalCode('SW1A 1AA'); echo $result->getFullAddress(); // Westminster, London, SW1A 1AA echo $result->latitude; // 51.5033 echo $result->longitude; // -0.1276 ``` ### Lookup Different Countries [](#lookup-different-countries) ``` // USA ZIP code $result = $geocoding->lookupPostalCode('90210'); echo $result->city; // Beverly Hills echo $result->state; // California // Ukraine postal code $result = $geocoding->lookupPostalCode('01001'); echo $result->city; // Kyiv ``` ### Geocode Full Address [](#geocode-full-address) ``` $result = $geocoding->geocode('10 Downing Street, London, UK'); echo $result->latitude; // 51.5033 echo $result->longitude; // -0.1276 echo $result->postalCode; // SW1A 2AA ``` ### Reverse Geocoding [](#reverse-geocoding) ``` $result = $geocoding->reverseGeocode(51.5033, -0.1276); echo $result->getFullAddress(); // Output: 10 Downing Street, Westminster, London, SW1A 2AA ``` ### Using Facade [](#using-facade) ``` use Kulykovoleksii\Geocoding\Facades\Geocoding; $result = Geocoding::lookupPostalCode('SW1A 1AA'); ``` ### Working with Regions [](#working-with-regions) ``` use Kulykovoleksii\Geocoding\Models\Region; use Kulykovoleksii\Geocoding\Models\PostalCode; // Create region hierarchy $uk = Region::create([ 'name' => 'United Kingdom', 'slug' => 'uk', 'country_code' => 'GB', 'type' => 'country', ]); $london = Region::create([ 'name' => 'London', 'slug' => 'london', 'country_code' => 'GB', 'type' => 'city', 'parent_id' => $uk->id, ]); // Query regions $ukRegions = Region::byCountry('GB')->get(); $cities = Region::byType('city')->get(); $countries = Region::roots()->get(); ``` Supported Postal Code Formats ----------------------------- [](#supported-postal-code-formats) CountryCodeFormat ExampleProviderUnited KingdomGBSW1A 1AA, M1 1AAPostcodes.ioUnited StatesUS90210, 10001-1234Google MapsUkraineUA01001, 79000Google MapsCanadaCAK1A 0B1Google MapsOthers\*VariousGoogle MapsGeocoding Providers ------------------- [](#geocoding-providers) ### Postcodes.io (UK only, free) [](#postcodesio-uk-only-free) Automatically used for UK postcodes. No configuration required. ### Google Maps Geocoding API (Universal) [](#google-maps-geocoding-api-universal) Used for non-UK addresses or when Postcodes.io doesn't have data. Requires API key in configuration. Caching Strategy ---------------- [](#caching-strategy) All geocoding results are automatically cached in the database: 1. First lookup checks the database cache 2. If not found, queries the appropriate geocoding provider 3. Results are stored in the `postal_codes` table 4. Subsequent lookups use cached data 5. Reverse geocoding uses proximity search for nearby cached coordinates This minimizes API calls and costs, especially for paid services like Google Maps. Testing ------- [](#testing) Run the test suite: ``` composer test ``` Or using PHPUnit directly: ``` vendor/bin/phpunit ``` Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. Security -------- [](#security) If you discover any security-related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Oleksii Kulykov](https://github.com/kulykovoleksii) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 38 — LowBetter than 85% of packages Maintenance87 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 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 Unknown Total 1 Last Release 66d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f5fa8805dfcea5c6d17484e99542a2be34cfbc0275514a8c0e5995b94cb6b06f?d=identicon)[kulykovoleksii](/maintainers/kulykovoleksii) --- Top Contributors [![kulykovoleksii](https://avatars.githubusercontent.com/u/958994?v=4)](https://github.com/kulykovoleksii "kulykovoleksii (2 commits)") --- Tags phplaravelgeocodingaddressgeolocationgoogle mapspostcodepostal-codeuk-postcodes ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/kulykovoleksii-laravel-geocoding/health.svg) ``` [![Health](https://phpackages.com/badges/kulykovoleksii-laravel-geocoding/health.svg)](https://phpackages.com/packages/kulykovoleksii-laravel-geocoding) ``` ### Alternatives [stevebauman/location Retrieve a user's location by their IP Address 1.3k7.6M65](/packages/stevebauman-location)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[adrianorosa/laravel-geolocation Laravel Geo Location package to get details for a given IP Address 6593.3k1](/packages/adrianorosa-laravel-geolocation)[tehwave/laravel-achievements Simple, elegant Achievements the Laravel way 7012.8k](/packages/tehwave-laravel-achievements) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)