Weave Code
Geocoder Laravel Package
spatie/geocoder
Convert any address into GPS coordinates using Google's geocoding service. Returns latitude, longitude, accuracy, formatted address, and viewport bounds as a simple array. Requires a Google Maps API key.
spatie/geocoder converts any street address into GPS coordinates using Google's geocoding service. A single call to Geocoder::getCoordinatesForAddress() returns everything you need for mapping, distance calculations, or validation.
Geocoder::getCoordinatesForAddress('Samberstraat 69, Antwerpen, Belgium');
- One-line address-to-coordinates lookups
- Returns lat, lng, accuracy and formatted_address
- Ships the viewport northeast/southwest bounds
- Powered by the Google Maps Geocoding API
- Framework-agnostic, MIT licensed, with Laravel-friendly usage
Frequently asked questions about Geocoder
- How do I install spatie/geocoder in a Laravel application?
- Install it with Composer using composer require spatie/geocoder. Laravel auto-discovers the service provider and facade, so you can start calling Geocoder after configuration. Add your Google Geocoding API key through your environment or package config, then cache and queue settings as needed.
- What data does Geocoder::getCoordinatesForAddress return?
- It returns an array with lat and lng for the address. The response also includes accuracy, formatted_address, and viewport bounds with northeast and southwest coordinates. You can use these fields for mapping, validation, and display.
- Can spatie/geocoder reverse geocode coordinates into an address?
- Yes, the package supports reverse geocoding through its provider integration, converting coordinates back into an address. Reverse geocoding is generally less reliable than forward geocoding, so validate results and handle missing or ambiguous matches. Use caching and fallbacks because reverse lookups can also increase API costs.
- How do I cache geocoding results to reduce Google API costs?
- Use Geocoder::setCache() with a Laravel cache store such as Redis or Memcached. Cache frequent address lookups with a sensible TTL and reuse coordinates for repeated requests. For bulk operations, combine caching with queued jobs to avoid blocking requests and exceeding quotas.
- How can I test geocoding without calling the real Google API?
- Mock the Geocoder facade or bind a fake geocoder implementation in the Laravel container. The package supports custom adapters and test-friendly mocking, such as Geocoder::fake(), so tests do not hit live APIs. Cover edge cases like invalid addresses, international formats, and failed responses.
- What are the cost and rate-limit risks of using Google Geocoding API?
- Google Geocoding API usage can incur charges once you exceed the free tier, which is commonly capped around $200 per month. Rate limits or quota exhaustion can break synchronous workflows if errors are not handled. Mitigate with caching, retries, queued batch jobs, and monitoring or alerts for quota usage.
- Does spatie/geocoder integrate with Laravel Eloquent models?
- Yes, it can be used with Eloquent models through a Geocodable-style trait that geocodes an address attribute into latitude and longitude. It also works with plain arrays or custom objects, so you are not forced into a specific schema. Bind the geocoder in the service container and mock it for model tests.
- Which geocoding providers does spatie/geocoder support?
- The core example uses Google's Geocoding API for address-to-coordinate conversion. The package is extensible via adapters, allowing other providers such as OpenStreetMap or Mapbox for cost optimization, redundancy, or regional coverage. Provider choice affects accuracy, pricing, and rate limits.
- How should I handle failed geocoding or invalid addresses in production?
- Sanitize and validate addresses before calling the API, and check the returned accuracy field before trusting coordinates. Define fallback behavior such as retrying, using a default location, or asking the user to correct the address. Log GeocodeFailed events and monitor rate limits so failures do not silently break workflows.
- Is spatie/geocoder actively maintained and which Laravel versions are supported?
- Spatie maintains the package as part of its open-source collection, with releases and tests published on GitHub. Exact Laravel and PHP version constraints are defined in composer.json, so check Packagist or the repository before upgrading. For long-term projects, review the changelog and test provider API changes during upgrades.
Weaver
How can I help you explore Laravel packages today?