PHPackages topukhan/geokit - 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. [API Development](/categories/api) 4. / 5. topukhan/geokit ActiveLibrary[API Development](/categories/api) topukhan/geokit =============== A clean and extensible geocoding toolkit for Laravel v2.0.0(6mo ago)04MITPHPPHP ^8.2 Since Jun 12Pushed 6mo agoCompare [ Source](https://github.com/topukhan/geokit)[ Packagist](https://packagist.org/packages/topukhan/geokit)[ RSS](/packages/topukhan-geokit/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (6)Versions (4)Used By (0) Geokit - Laravel Geocoding Toolkit ================================== [](#geokit---laravel-geocoding-toolkit) A clean and extensible geocoding toolkit for Laravel that supports multiple providers with automatic fallback handling. Features -------- [](#features) - 🌍 **Multiple Providers**: Geoapify (premium) and Nominatim (free) support - 🔄 **Smart Fallback**: Automatically falls back to next provider if one fails - 🛡️ **Quota Protection**: Detects API quota issues and handles them gracefully - 🎯 **Consistent Results**: Unified response format across all providers - ⚡ **Laravel Integration**: Facade and Service injection support - 🔧 **Configurable**: Easy configuration and extensible architecture Installation ------------ [](#installation) Install the package via Composer: ``` composer require topukhan/geokit ``` Publish the configuration file: ``` php artisan vendor:publish --tag=geokit-config ``` Configuration ------------- [](#configuration) ### Environment Variables [](#environment-variables) Add these variables to your `.env` file: ``` # Optional: Your Geoapify API key (if you have one) GEOKIT_GEOAPIFY_KEY=your_geoapify_api_key_here # Optional: Request timeout in seconds (default: 30) GEOKIT_TIMEOUT=30 # Optional: Maximum results per search (default: 10) GEOKIT_MAX_RESULTS=10 # Optional: User agent for API requests GEOKIT_USER_AGENT="Your App Name/1.0" ``` ### Config File [](#config-file) The `config/geokit.php` file allows you to customize: - Provider order and selection - API keys - Request timeouts - Result limits Usage ----- [](#usage) ### Using the Facade [](#using-the-facade) ``` use Topukhan\Geokit\Facades\Geokit; $response = Geokit::search('Tongi, Dhaka'); // Check if we got results if ($response->hasResults()) { echo "Found {$response->count()} results\n"; // Get the first result $first = $response->first(); echo "Best match: {$first->formatted}\n"; echo "Coordinates: {$first->lat}, {$first->lng}\n"; echo "Provider: {$first->provider}\n"; // Access address components if (isset($first->components['city'])) { echo "City: {$first->components['city']}\n"; } } // Check if fallback was used if ($response->usedFallback) { echo "Used fallback providers\n"; } // See which providers failed if (!empty($response->failedProviders)) { echo "Failed providers: " . implode(', ', $response->failedProviders) . "\n"; } ``` ### Using Service Injection [](#using-service-injection) ``` use Topukhan\Geokit\Services\AddressResolverService; class LocationController extends Controller { public function search(Request $request, AddressResolverService $geokit) { $response = $geokit->search($request->input('query')); return response()->json($response->toArray()); } } ``` Response Format --------------- [](#response-format) All searches return a `GeocodeResponse` object with this structure: ``` GeocodeResponse { +query: string // Original search query +results: array // Array of GeocodeResult objects +usedFallback: bool // Whether fallback providers were used +failedProviders: array // Names of providers that failed } ``` Each result in the `results` array is a `GeocodeResult` object: ``` GeocodeResult { +provider: string // Provider name (e.g., 'geoapify', 'nominatim') +formatted: string // Full formatted address +lat: float // Latitude +lng: float // Longitude +components: array // Address components (city, state, country, etc.) } ``` ### Example Response [](#example-response) ``` { "query": "Tongi, Dhaka", "results": [ { "provider": "geoapify", "formatted": "Tongi, Gazipur District, Dhaka Division, Bangladesh", "lat": 23.8896, "lng": 90.3961, "components": { "city": "Tongi", "district": "Gazipur District", "state": "Dhaka Division", "country": "Bangladesh", "country_code": "BD" } } ], "usedFallback": false, "failedProviders": [] } ``` Provider Details ---------------- [](#provider-details) ### Geoapify [](#geoapify) - **Type**: Premium (requires API key) - **Quota**: Varies by plan - **Accuracy**: High - **Coverage**: Global ### Nominatim [](#nominatim) - **Type**: Free (no API key required) - **Quota**: Rate limited - **Accuracy**: Good - **Coverage**: Global (OpenStreetMap data) Error Handling -------------- [](#error-handling) The package handles various error scenarios automatically: - **Invalid API Keys**: Automatically falls back to next provider - **Quota Exceeded**: Detects quota issues and skips provider - **Network Timeouts**: Respects configured timeout limits - **Rate Limits**: Handles rate limiting gracefully Extending with New Providers ---------------------------- [](#extending-with-new-providers) To add a new geocoding provider: 1. Create a new class implementing `GeocodingDriverInterface` 2. Add it to the service provider's provider mapping 3. Update the configuration file Example: ``` use Topukhan\Geokit\Contracts\GeocodingDriverInterface; class GoogleGeocoder implements GeocodingDriverInterface { public function getName(): string { return 'google'; } // Implement other interface methods... } ``` Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 10.0+ License ------- [](#license) This package is open-sourced software licensed under the MIT license. ### Health Score 34 — LowBetter than 77% of packages Maintenance68 Regular maintenance activity Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity51 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 ~74 days Total 3 Last Release 184d ago Major Versions v1.0.1 → v2.0.02025-11-07 PHP version history (2 changes)v1.0.0PHP ^8.1 v2.0.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/f613a571f6930b83256d8f9e6b2a468e995a08737ab3f393644c9a0dcf3b8e0d?d=identicon)[topukhan](/maintainers/topukhan) --- Top Contributors [![topukhan](https://avatars.githubusercontent.com/u/98571259?v=4)](https://github.com/topukhan "topukhan (7 commits)") --- Tags laravelgeocodinglocationnominatimaddress searchgeoapify ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/topukhan-geokit/health.svg) ``` [![Health](https://phpackages.com/badges/topukhan-geokit/health.svg)](https://phpackages.com/packages/topukhan-geokit) ``` ### Alternatives [andreaselia/laravel-api-to-postman Generate a Postman collection automatically from your Laravel API 1.0k586.2k3](/packages/andreaselia-laravel-api-to-postman)[essa/api-tool-kit set of tools to build an api with laravel 52680.5k](/packages/essa-api-tool-kit)[resend/resend-laravel Resend for Laravel 1191.4M6](/packages/resend-resend-laravel)[joggapp/laravel-aws-sns Laravel package for the SNS events by AWS 3171.8k](/packages/joggapp-laravel-aws-sns)[dragon-code/laravel-json-response Automatically always return a response in JSON format 1118.6k1](/packages/dragon-code-laravel-json-response)[surface/laravel-webfinger A Laravel package to create an ActivityPub webfinger. 113.8k](/packages/surface-laravel-webfinger) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)