Providers

Each HTTP provider talks to its API through Laravel’s own HTTP client — no vendor SDKs — with the shared timeout, its own retry settings and its own rate-limit budget. Add the credentials you have to .env:

# IPinfo — the token is optional; the anonymous tier works without one
IPINFO_TOKEN=your-ipinfo-token

# IP2Location.io
IP2LOCATION_API_KEY=your-ip2location-key

# Google — the key needs the Geocoding API and the Routes API enabled
GOOGLE_MAPS_API_KEY=your-google-maps-key

# Static location returned by the "default" provider
GEOLOCATION_DEFAULT_HUMAN_READABLE="Springfield, US"
GEOLOCATION_DEFAULT_STREET="Main Street 1"
GEOLOCATION_DEFAULT_CITY=Springfield
GEOLOCATION_DEFAULT_COUNTRY_ISO_CODE=US
GEOLOCATION_DEFAULT_LATITUDE=39.7817
GEOLOCATION_DEFAULT_LONGITUDE=-89.6501

What each provider returns

IPinfo

Looks up /{ip}/json on ipinfo.io. The token is optional: the anonymous tier works without one, and the bearer header is only sent when a token is set. Invalid IPs and non-IP queries return null without a request.

IP2Location.io

Calls the ip2location.io API with your key and the IP; without IP2LOCATION_API_KEY the request goes out unauthenticated. A response carrying an error, a non-2xx status or an invalid IP resolves to null, and so does the all-empty reply it gives for a private or reserved IP.

Google

The only bundled provider that handles coordinates and addresses: reverse geocoding for coordinate queries, forward geocoding for address queries, both via the Geocoding API. It is also the only bundled DistanceProvider: distances and matrices come from the Routes API’s computeRouteMatrix, driving (traffic-unaware) or walking. IP queries return null, so Google sits happily behind the IP providers.

Enable both the Geocoding API and the Routes API on the key in GOOGLE_MAPS_API_KEY. Geocoding receives it as the key query parameter, the Routes API in the X-Goog-Api-Key header; services.google.url and services.google.routes_url set the two endpoints. When Google refuses a request as a whole — a key without the API enabled (REQUEST_DENIED, PERMISSION_DENIED), an exhausted quota, an invalid request — the provider throws a redacted ProviderUnavailableException naming the status instead of answering null, so the pipeline moves on and the failure event says why.

Default

Returns the static location from default.* with type Default — but only once you configure it; while every default.* value is empty or zero (as shipped), it answers null. Set it when your app should always have something to work with — for example your head office or the country you mostly serve. The fallback is never cached.

The two MaxMind providers have their own section — see MaxMind.