Geolocation Bundle Laravel Package

Product Decisions This Supports

• French-market roadmap bets. This package only does one thing: forward-geocode a French postal address into latitude/longitude via api.adresse.gouv.fr (the Base Adresse Nationale / BAN API). It's a signal that French address handling is in scope — relevant if you're deciding whether to localize checkout, delivery, or store-locator features for France.
• Build vs. buy for address geocoding. The underlying capability is a free, keyless, government-operated HTTP API. This package is a thin wrapper (the name says "bundle," which suggests Symfony conventions, not Laravel). The realistic decision is not "adopt this vs. build our own geocoder" — it's "call the BAN API directly from an Http::get() vs. add a 0-star dependency." For a Laravel codebase, a small internal service class behind an interface is usually the better call.
• Feature scope for address capture. Supports decisions around address autocomplete, validating that a customer-entered address actually resolves to a real French location, and normalizing addresses before they hit your database — all of which reduce failed deliveries and support tickets.
• Geo-dependent features. Store locator, delivery zone / catchment polygons, distance-to-nearest-fulfilment-centre, territory analytics, and map pins for admin dashboards — all consume lat/lng, and all are viable on top of BAN output without paying a commercial geocoder.
• Buy-vs-integrate for international expansion. If the answer to "which countries?" is anything other than France, this package doesn't help. That should push you toward a vendor abstraction (Nominatim, Mapbox, Google) rather than a France-only dependency baked into domain code.

When to Consider This Package

Consider it if:

• Your address surface area is exclusively French postal addresses, and forward geocoding (address → coordinates) is the only operation you need.
• You're prototyping an MVP or internal tool and want the fastest possible path to "address in, lat/lng out."
• You want zero API cost and zero key management — BAN is free and unauthenticated, which removes procurement and secrets rotation from the critical path.
• You're already on Symfony-adjacent conventions, or you're comfortable reading the source and copying the ~30–50 lines into your own Laravel service.

Look elsewhere if:

• You need international addresses, reverse geocoding (lat/lng → address), batch/bulk geocoding, or autocomplete-as-you-type. BAN does some of this, but this wrapper almost certainly doesn't expose it.
• You need maintenance assurance. Zero stars, zero dependents, a single release (2024-07-24), and no consumers means no community vetting, no downstream bug discovery, and no realistic expectation of a security patch. A zero-dependency wrapper is low-risk to adopt because it's small, not because it's safe.
• You need SLA, rate-limit handling, retries, caching, or circuit breaking. A government API will rate-limit and will occasionally be slow; assume you're building that layer yourself.
• You need a Laravel-native integration — service provider, auto-discovery, publishable config, facade, fakes for testing. "Bundle" in the package name is a red flag for framework fit. Verify before committing.
• You need testability. A wrapper that calls out at invocation time makes your test suite hit the network; you'll want an adapter you can fake.
• You're on a long-lived product where dependency provenance is reviewed. A 0-star, single-maintainer package will fail most dependency-review gates — and it would be the correct outcome.

How to Pitch It (Stakeholders)

For executives (one paragraph): France publishes its official address database as a free, keyless public API (adresse.gouv.fr). This package is a small open-source wrapper around that API that turns a French postal address into map coordinates. The cost is zero and the license is permissive (MIT), so the financial downside is minimal — but it is an unmaintained, zero-adoption library, so we should treat it as a reference implementation rather than a foundation. Recommendation: adopt the underlying government API, not this specific package; write our own thin client in roughly a day and own it.

For engineering (the actual ask): This is a 1-function wrapper over api.adresse.gouv.fr. There is no meaningful logic being purchased here — no caching, no retry, no rate-limit handling, no abstraction over providers, and likely no Laravel service provider. Proposed approach: implement a Geocoder interface with a BanGeocoder implementation using Laravel's Http client, wrapped in Cache::remember keyed on the normalized address, plus an AddressData DTO. That gives us fakes in tests, swap-ability if we expand beyond France, and no supply-chain exposure. If we do pull the package in, pin it, vendor-review the source (it's small), and wrap it behind our own interface so removal is a one-line change.

Risk summary to carry into the decision: 0 stars / 0 dependents / single release = no evidence of production use and no maintenance signal; French-only scope limits reuse; the underlying service is free but unsupported, so error handling is on us. Upside: trivial to replace, no cost, no vendor lock-in, high-quality official data. Net: low-risk to borrow from, moderate-risk to depend on.