- What are the requirements to install toin0u/geocoder-laravel?
- You need PHP 8.2 or higher and Laravel 11 or newer. Install it with composer require toin0u/geocoder-laravel; the service provider is auto-discovered on modern Laravel, so you only register it manually on older setups. Then publish the config file and add a provider API key such as a Google Maps key to your environment.
- How do I choose which geocoding provider is used?
- Providers are configured in the published config file as a provider chain. The default setup uses Google Maps for address and reverse geocoding and GeoPlugin for IP-based lookups. You can reorder or replace providers, but chain order matters because lookups fall through to the next provider when one fails or returns no result.
- How does caching work and should I change the default cache duration?
- The package wraps the geocoder in a cache decorator that stores results using locale-partitioned cache keys, so the same query in different languages does not collide. The default cache duration is effectively forever (9999999 seconds), which is technically convenient but may conflict with provider terms such as Google's Maps Platform caching limits. Shorten the TTL and get vendor or legal sign-off before using it in production.
- How can I test geocoding in Laravel without calling real APIs?
- Because the package uses Laravel's HTTP client by default, you can use Http::fake() in your tests to return canned provider responses. That lets you assert the facade output and error paths without network calls. A quick spike proving one provider plus one faked test is usually a day's work.
- Can I batch geocode many addresses with this package?
- No. It is a thin service provider over the Geocoder PHP library and is designed for request-scoped, single-record lookups such as normalizing an address at form entry or reverse geocoding a stored coordinate. It has no batching, queue-aware rate limiting, or backoff orchestration. For bulk jobs, use a dedicated batch service or call the provider directly behind your own queue workers.
- Why did the package version jump from 5.0.0 to 13.0.0?
- Starting with 13.0.0, the major version tracks the highest supported Laravel version rather than the upstream Geocoder PHP version. So 13.x supports Laravel 11, 12, and 13, and the next major will follow Laravel 14. Read the upgrading notes before installing, especially the change to the default HTTP adapter, and pin the version in automated dependency tooling.
- Does it support per-tenant API keys or locale settings?
- Not out of the box. Configuration is application-global, so every tenant shares the same provider, API key, and locale policy. In multi-tenant apps you need to set config dynamically at runtime or build per-tenant provider instances behind an app-owned interface. It also should not be treated as a system of record for address data.
- What happens when all geocoding providers fail?
- Chain providers fall through on failure, so a failed lookup and a genuine no-result can look similar to the caller. Without explicit handling you may receive an empty collection instead of an alertable error. Decide up front whether the workflow should block or degrade, and add your own error handling and logging around the facade calls.
- How do I reverse geocode coordinates or look up a user's location by IP?
- Use the Geocoder facade to reverse geocode a stored latitude and longitude for display, and rely on the default GeoPlugin provider for IP-to-region lookups used for locale or currency defaults. Note that IP geolocation may count as personal data in some jurisdictions, so check whether the third-party call needs a data processing agreement. Accuracy for IP-derived location is coarse and should not drive anything high-stakes.
- What are the alternatives if I need high volume or production-grade geocoding?
- This package is best treated as an implementation detail behind an app-owned interface for low-volume, request-scoped lookups. For high QPS or bulk geocoding, consider a dedicated geocoding service or direct provider SDKs with queue-aware rate limiting and backoff. Also note the modest adoption signal (around 750 GitHub stars, few indexed dependents), so expect to own more edge cases than with a heavily used dependency.