use-weather-forecast 0.1.182 → 0.1.184

package/README.md

@@ -24,7 +24,7 @@
 
 [![Coverage](https://codecov.io/gh/OpenSourceAGI/qwksearch-research-agent/graph/badge.svg?component=package-react-weather-forecast)](https://codecov.io/gh/OpenSourceAGI/qwksearch-research-agent)
 
-React weather forecast component using Open-Meteo for current, hourly, and daily forecasts and Cloudflare/ipapi.co for IP geolocation, with a fallback chain behind both.
+React weather forecast component using Open-Meteo for current, hourly, and daily forecasts and Cloudflare/ipwho.is for IP geolocation, with a fallback chain behind both.
 
 ## Features
 
@@ -33,6 +33,8 @@ React weather forecast component using Open-Meteo for current, hourly, and daily
 - Next days forecast.
 - Four weather upstreams tried in order, four IP geolocation upstreams behind that.
 - Every request validated before it is sent, retried with backoff when it can recover.
+- A resolved location cached for 12 hours, so a refreshing widget never spends a
+  lookup it has already made -- the difference between working all day and a `429`.
 - Stale-cache fallback so a total outage still renders a widget.
 - Latitude/longitude override.
 - Split SVG weather icon components.
@@ -110,16 +112,30 @@ exponential backoff from `retryDelay` (400ms, then 800ms, ...). A `429`, a
 called invalid (`400`, `404`) is not, since replaying it only burns the
 upstream's rate limit.
 
+One exception, in the geolocation chain: a provider that answered with a rate
+limit is *not* retried while another provider is still to be tried. A free IP
+lookup's limit is a daily quota, so the retry would be spent asking the one
+operator that has already said no. The last provider in the chain, which has
+nowhere left to move on to, still retries.
+
 ### Fallback APIs
 
 | Order | Weather | IP geolocation |
 | --- | --- | --- |
 | 1 | `open-meteo` -- `api.open-meteo.com/v1/forecast` | `geoEndpoint` (the bundled worker), when given |
-| 2 | `open-meteo-gfs` -- the GFS model endpoint | `ipapi` -- ipapi.co |
-| 3 | `met-no` -- met.no, a different operator and model | `ipwho` -- ipwho.is |
+| 2 | `open-meteo-gfs` -- the GFS model endpoint | `ipwho` -- ipwho.is |
+| 3 | `met-no` -- met.no, a different operator and model | `ipapi` -- ipapi.co |
 | 4 | `wttr` -- wttr.in, no key required | `geojs` -- get.geojs.io |
 | 5 | | `freeipapi` -- freeipapi.com |
 
+ipwho.is leads the geolocation chain: it is free, keyless and CORS-enabled, and
+unlike ipapi.co it does not spend the rest of the day answering `RateLimited` as
+a `200` once the quota is gone. `browser` -- the device's own geolocation -- is
+bundled too but deliberately left out of the default chain, since asking for it
+raises the browser's permission prompt; name it first in `geoProviders` in a
+place where asking is expected and the IP lookups stay behind it for everyone
+who declines.
+
 The fallbacks normalize their own condition codes, units and timestamps into
 the same shape Open-Meteo returns, so a failover is invisible in the rendered
 widget (wttr.in is 3-hourly rather than hourly). If every provider fails, a
@@ -179,20 +195,29 @@ npm run build
 This package no longer uses ipinfo.io. Instead:
 
 - Pass `geoEndpoint` pointing at a deployed instance of the bundled Cloudflare Worker
-  (`worker/geo-worker.ts`) for accurate results. The worker reads Cloudflare's built-in
-  geolocation (`request.cf`) for the visitor's own IP, and falls back to `ipapi.co`
-  when a `?ip=` query param (or the `ip` prop) is supplied for an arbitrary address.
-- If `geoEndpoint` is omitted, the package falls back to calling `ipapi.co` directly
-  from the browser (`https://ipapi.co/json/`, or `https://ipapi.co/<ip>/json/` when an
-  `ip` is supplied). Unlike the previous ip-api.com fallback, this works over HTTPS with
-  no mixed-content issues, though ipapi.co's free tier is rate-limited (1,000
-  requests/day) — deploy the worker and pass `geoEndpoint` for higher-volume or
-  production use.
+  (`worker/geo-worker.ts`) for accurate results, and for production prefer it over any
+  public IP API. The worker reads Cloudflare's built-in geolocation (`request.cf`) for
+  the visitor's own IP: no third-party request, no shared quota, no CORS, and nothing
+  an ad blocker recognises as a tracker. It falls back to the public lookups only for a
+  `?ip=` query param (or the `ip` prop) naming an arbitrary address, or for the rare
+  network Cloudflare has no coordinates for. A successful answer is returned
+  `Cache-Control: private, max-age=43200`, so a reloaded page does not re-ask.
+- If `geoEndpoint` is omitted, the package calls `ipwho.is` directly from the browser
+  (`https://ipwho.is/?rate=1`, or `https://ipwho.is/<ip>?rate=1` when an `ip` is
+  supplied). It is free, needs no key, supports CORS and works over HTTPS with no
+  mixed-content issues; `rate=1` makes it report what is left of the quota alongside
+  the location, which is useful while watching request volume. Its free tier allows
+  1,000 requests/day, **shared by every visitor to your domain** for a browser call --
+  deploy the worker and pass `geoEndpoint` for higher-volume or production use.
+- A resolved location is **cached for 12 hours** (see [Caching](#caching)), so the
+  quota is spent once per visitor per half-day rather than once per render. Turning
+  this off with `cacheLocation={false}` is what re-creates the `429`.
 - A failed lookup is **repeated** before the chain moves on: `getClientLocation`
   tries each provider twice by default, waiting 500ms, then walks the rest of the
-  chain (ipapi.co, ipwho.is, get.geojs.io, freeipapi.com) so a single rate-limited
-  or cold-start response doesn't take the whole forecast down. Tune it with the
-  third argument: `getClientLocation(geoEndpoint, ip, { attempts: 5, retryDelay: 250, providers: ['ipwho'] })`.
+  chain (ipwho.is, ipapi.co, get.geojs.io, freeipapi.com) so a single cold-start
+  response doesn't take the whole forecast down. A rate-limited provider is not
+  retried while another one is left to ask. Tune it with the third argument:
+  `getClientLocation(geoEndpoint, ip, { attempts: 5, retryDelay: 250, providers: ['ipwho'] })`.
 - A response **without usable coordinates counts as a failure** rather than being
   passed on as `NaN`, and `fallbackLocation` covers the case where every provider
   is down.
@@ -212,7 +237,24 @@ This deploys `worker/geo-worker.ts` via Wrangler. Use the resulting `*.workers.d
 
 ## Caching
 
-`getWeatherForecast` caches each response in `localStorage` for 30 minutes, keyed by
+Two things are cached in `localStorage`, on different clocks, because they go
+stale at different rates.
+
+**The resolved location, for 12 hours.** The weather at a place changes through
+the day; the place a visitor is looking from does not. Every free IP lookup
+bills per request against a daily quota, and for a browser call that quota is
+shared by everyone on the domain -- so a widget that re-resolves its location on
+each refresh, each tab and each remount exhausts 1,000 requests without needing
+many users, and then answers `429 Too Many Requests` for the rest of the day.
+Caching the location is the single most effective thing against that, and it is
+on by default. `cacheLocation={false}` forces a fresh lookup every time;
+`locationCacheTtl` changes the window; `clearCachedLocations()` empties it.
+
+Note that the forecast cache below cannot help here: it is keyed by coordinates,
+so it can only be consulted *after* the location is known.
+
+**The forecast itself, for 30 minutes.** `getWeatherForecast` caches each response
+in `localStorage` for 30 minutes, keyed by
 the request itself (location + units + forecast range + timezone), so a fallback
 provider's answer is reused exactly like the primary one's. Repeated calls for the same
 location/options within that window are served from the cache instead of hitting
@@ -225,7 +267,7 @@ or when `localStorage` is unavailable/full.
 ## Notes
 
 - Open-Meteo powers the forecast data, with met.no and wttr.in behind it.
-- Cloudflare's `request.cf`, ipapi.co, ipwho.is, get.geojs.io and freeipapi.com
+- Cloudflare's `request.cf`, ipwho.is, ipapi.co, get.geojs.io and freeipapi.com
   power IP geolocation (see above).
 - HTTP requests go through [`grab-url`](https://www.npmjs.com/package/grab-url), the
   repo-wide client, rather than raw `fetch`. It is the package's only runtime

package/dist/api/geolocation.d.ts

@@ -2,16 +2,30 @@ import type { WeatherLocation } from '../types';
 /** One IP geolocation upstream. */
 export type GeoProvider = {
     id: string;
-    /** Used in the thrown message, e.g. `ipapi.co lookup`. */
+    /** Used in the thrown message, e.g. `ipwho.is lookup`. */
     label: string;
     /** Full URL for the lookup; `ip` is the address to look up, if any. */
-    url: (ip?: string) => string;
+    url?: (ip?: string) => string;
     /** Map the body onto a location, or return `null` if it carries none. */
-    parse: (body: Record<string, any>) => Partial<WeatherLocation> | null;
+    parse?: (body: Record<string, any>) => Partial<WeatherLocation> | null;
+    /**
+     * Answer without an HTTP request at all, for a source that is not a URL --
+     * {@link browserProvider} asks the device. Used instead of `url`/`parse`.
+     */
+    resolve?: (ip: string | undefined, options: {
+        timeout: number;
+    }) => Promise<Partial<WeatherLocation> | null>;
 };
 export type GeolocationOptions = {
     /** default=2 How many times each provider is tried before the next one is used. */
     attempts?: number;
+    /**
+     * default=true Reuse a location resolved in the last 12 hours instead of
+     * spending a lookup. The single most effective thing against a `429`.
+     */
+    cache?: boolean;
+    /** default=43200000 Milliseconds a cached location stays usable. */
+    cacheTtl?: number;
     /** default=500 Milliseconds before a retry; each further wait doubles. */
     retryDelay?: number;
     /** default=8 Seconds before a single lookup is aborted. */
@@ -26,25 +40,66 @@ export type GeolocationOptions = {
         error: Error;
     }) => void;
 };
-export declare const ipapiProvider: GeoProvider;
+/**
+ * Default primary.
+ *
+ * `rate=1` asks ipwho.is to report the quota it has left alongside the
+ * location, which is what makes an approaching limit visible before it is a
+ * `429`. It is a free, no-key, CORS-enabled endpoint, so it works from the
+ * browser without a proxy of any kind.
+ */
 export declare const ipwhoProvider: GeoProvider;
+export declare const ipapiProvider: GeoProvider;
 export declare const geojsProvider: GeoProvider;
 export declare const freeipapiProvider: GeoProvider;
-/** Tried in order; each is a different operator, so a rate limit on one is not a rate limit on all. */
+/**
+ * The device's own geolocation, which costs no quota and is far more precise
+ * than any IP lookup -- but only after the user has granted permission, and
+ * the request is what raises the browser's permission prompt.
+ *
+ * Deliberately **not** in {@link DEFAULT_GEO_PROVIDERS}: a weather widget
+ * should not make the page ask for the user's location the moment it renders.
+ * Put `'browser'` at the front of `geoProviders` in a place where asking is
+ * expected, and the IP lookups stay behind it as the answer for everyone who
+ * declines.
+ */
+export declare const browserProvider: GeoProvider;
+/**
+ * Tried in order; each is a different operator, so a rate limit on one is not
+ * a rate limit on all.
+ *
+ * ipwho.is leads because ipapi.co is the stricter of the two in practice: it
+ * counts a browser request against a quota shared by the whole domain and then
+ * spends the rest of the day answering `RateLimited` as a 200, which is the
+ * failure this chain was built around in the first place.
+ */
 export declare const DEFAULT_GEO_PROVIDERS: GeoProvider[];
 /** The bundled Cloudflare worker, wrapped as a provider so it joins the same chain. */
 export declare function createWorkerGeoProvider(geoEndpoint: string): GeoProvider;
 export declare function resolveGeoProviders(providers?: (string | GeoProvider)[], geoEndpoint?: string): GeoProvider[];
+/**
+ * The key a resolved location is stored under.
+ *
+ * A lookup of an explicit `ip`, a lookup through a worker and a lookup of the
+ * caller's own address are different questions, so each keeps its own answer
+ * rather than serving one for another.
+ */
+export declare function locationCacheKey(geoEndpoint?: string, ip?: string): string;
 /**
  * Resolve the caller's location from a deployed geo worker or from one of the
  * public IP lookups.
  *
- * Each provider is retried with a growing delay, then the chain moves on; only
- * if all of them fail (and no `fallbackLocation` was given) does an error
- * reach the caller, listing what every provider said.
+ * A location resolved in the last 12 hours is reused as-is and costs no
+ * request at all -- see the note at the top of this file for why that is the
+ * difference between a widget that works and one that answers `429` from
+ * mid-afternoon onwards. Pass `cache: false` to force a fresh lookup.
+ *
+ * Otherwise each provider is retried with a growing delay, then the chain
+ * moves on; only if all of them fail (and no `fallbackLocation` was given)
+ * does an error reach the caller, listing what every provider said.
  *
  * @param geoEndpoint URL of a deployed geo worker; it is tried before the public providers.
  * @param ip Look up this IP instead of the caller's own.
- * @param options Retry, timeout, provider chain and fallback settings.
+ * @param options Cache, retry, timeout, provider chain and fallback settings.
  */
 export declare function getClientLocation(geoEndpoint?: string, ip?: string, options?: GeolocationOptions): Promise<WeatherLocation>;

package/dist/api/http.d.ts

@@ -39,14 +39,27 @@ export type GrabJsonOptions = {
      * malformed only wastes the upstream's rate limit.
      */
     retryClientErrors?: boolean;
+    /**
+     * default=true Repeat a request the upstream answered with a rate limit.
+     *
+     * Worth turning off wherever another upstream can answer the same question:
+     * a free IP lookup's limit is a daily quota, so the retry is spent on the
+     * one provider that has already said no, and spends quota to be told so
+     * again. The geolocation chain turns it off for every provider but the last
+     * one, which has nowhere left to move on to.
+     */
+    retryRateLimits?: boolean;
 };
 /** A failed upstream call, carrying the HTTP status when the failure had one. */
 export declare class HttpRequestError extends Error {
     readonly status?: number;
     readonly retryable: boolean;
+    /** The upstream refused because a quota or rate limit is spent, not because it broke. */
+    readonly rateLimited: boolean;
     constructor(message: string, options?: {
         status?: number;
         retryable?: boolean;
+        rateLimited?: boolean;
     });
 }
 /** No status at all means the request never reached the server -- worth a repeat. */

package/dist/index.cjs

@@ -33,9 +33,12 @@ __export(index_exports, {
   DEFAULT_GEO_PROVIDERS: () => DEFAULT_GEO_PROVIDERS,
   DEFAULT_WEATHER_PROVIDERS: () => DEFAULT_WEATHER_PROVIDERS,
   HttpRequestError: () => HttpRequestError,
+  LOCATION_TTL_MS: () => LOCATION_TTL_MS,
   WeatherForecast: () => WeatherForecast,
   WeatherIcon: () => WeatherIcon,
+  browserProvider: () => browserProvider,
   buildForecastRequest: () => buildForecastRequest,
+  clearCachedLocations: () => clearCachedLocations,
   clearWeatherForecastCache: () => clearWeatherForecastCache,
   createOpenMeteoProvider: () => createOpenMeteoProvider,
   createWorkerGeoProvider: () => createWorkerGeoProvider,
@@ -51,15 +54,18 @@ __export(index_exports, {
   isRetryableStatus: () => isRetryableStatus,
   isValidLatitude: () => isValidLatitude,
   isValidLongitude: () => isValidLongitude,
+  locationCacheKey: () => locationCacheKey,
   metNoProvider: () => metNoProvider,
   normalizeCoordinates: () => normalizeCoordinates,
   normalizeTimezone: () => normalizeTimezone,
   openMeteoGfsProvider: () => openMeteoGfsProvider,
   openMeteoProvider: () => openMeteoProvider,
+  readCachedLocation: () => readCachedLocation,
   resolveGeoProviders: () => resolveGeoProviders,
   resolveWeatherProviders: () => resolveWeatherProviders,
   symbolToWmoCode: () => symbolToWmoCode,
   useWeatherForecast: () => useWeatherForecast,
+  writeCachedLocation: () => writeCachedLocation,
   wttrProvider: () => wttrProvider,
   wwoToWmoCode: () => wwoToWmoCode
 });
@@ -84,6 +90,8 @@ function getWeatherIcon(code, isDay = 1) {
 var CACHE_PREFIX = "weather-forecast-cache:";
 var CACHE_TTL_MS = 30 * 60 * 1e3;
 var STALE_TTL_MS = 24 * 60 * 60 * 1e3;
+var LOCATION_PREFIX = "location:";
+var LOCATION_TTL_MS = 12 * 60 * 60 * 1e3;
 function getStorage() {
   if (typeof window === "undefined" || !window.localStorage) return null;
   return window.localStorage;
@@ -116,6 +124,9 @@ function readStaleForecast(key, maxAgeMs = STALE_TTL_MS) {
   return entry.data;
 }
 function writeCachedForecast(key, data) {
+  writeEntry(key, data);
+}
+function writeEntry(key, data) {
   const storage = getStorage();
   if (!storage) return;
   try {
@@ -124,12 +135,31 @@ function writeCachedForecast(key, data) {
   } catch {
   }
 }
+function readCachedLocation(scope, maxAgeMs = LOCATION_TTL_MS) {
+  const key = LOCATION_PREFIX + scope;
+  const entry = readEntry(key);
+  if (!entry) return null;
+  if (maxAgeMs <= 0 || Date.now() - entry.timestamp > maxAgeMs) {
+    getStorage()?.removeItem(CACHE_PREFIX + key);
+    return null;
+  }
+  return entry.data;
+}
+function writeCachedLocation(scope, location) {
+  writeEntry(LOCATION_PREFIX + scope, location);
+}
+function clearCachedLocations() {
+  clearByPrefix(CACHE_PREFIX + LOCATION_PREFIX);
+}
 function clearWeatherForecastCache() {
+  clearByPrefix(CACHE_PREFIX);
+}
+function clearByPrefix(prefix) {
   const storage = getStorage();
   if (!storage) return;
   for (let i = storage.length - 1; i >= 0; i--) {
     const key = storage.key(i);
-    if (key?.startsWith(CACHE_PREFIX)) storage.removeItem(key);
+    if (key?.startsWith(prefix)) storage.removeItem(key);
   }
 }
 
@@ -142,8 +172,10 @@ var HttpRequestError = class extends Error {
     this.name = "HttpRequestError";
     this.status = options.status;
     this.retryable = options.retryable ?? isRetryableStatus(options.status);
+    this.rateLimited = options.rateLimited ?? options.status === 429;
   }
 };
+var RATE_LIMIT_REASON = /rate|limit|quota|too many/i;
 function isRetryableStatus(status) {
   if (status === void 0) return true;
   return RETRYABLE_STATUS.has(status) || status >= 500;
@@ -239,7 +271,8 @@ async function grabJsonOnce(url, label, options) {
   if (data?.error === true) {
     const reason = data.reason ?? "unknown error";
     throw new HttpRequestError(`${label} failed: ${reason}`, {
-      retryable: /rate|limit|busy|timeout|try again/i.test(reason)
+      retryable: /rate|limit|busy|timeout|try again/i.test(reason),
+      rateLimited: RATE_LIMIT_REASON.test(reason)
     });
   }
   if (!data) throw new HttpRequestError(`${label} failed: empty response`);
@@ -260,8 +293,9 @@ async function grabJson(url, label, options = {}) {
       }
     }
     lastError = failure;
+    const spentQuota = failure instanceof HttpRequestError && failure.rateLimited && options.retryRateLimits === false;
     const retryable = !(failure instanceof HttpRequestError) || failure.retryable || options.retryClientErrors === true;
-    if (!retryable || attempt === attempts) break;
+    if (spentQuota || !retryable || attempt === attempts) break;
     if (retryDelay > 0) await wait(retryDelay * 2 ** (attempt - 1));
   }
   throw lastError instanceof Error ? lastError : new HttpRequestError(String(lastError));
@@ -755,23 +789,10 @@ function resolveWeatherProviders(providers) {
 var DEFAULT_ATTEMPTS = 2;
 var DEFAULT_RETRY_DELAY_MS = 500;
 var DEFAULT_TIMEOUT_SECONDS = 8;
-var ipapiProvider = {
-  id: "ipapi",
-  label: "ipapi.co lookup",
-  url: (ip) => `https://ipapi.co/${ip ? `${encodeURIComponent(ip)}/` : ""}json/`,
-  parse: (data) => ({
-    city: data.city,
-    region: data.region,
-    country: data.country_name,
-    timezone: data.timezone,
-    latitude: data.latitude,
-    longitude: data.longitude
-  })
-};
 var ipwhoProvider = {
   id: "ipwho",
   label: "ipwho.is lookup",
-  url: (ip) => `https://ipwho.is/${ip ? encodeURIComponent(ip) : ""}`,
+  url: (ip) => `https://ipwho.is/${ip ? encodeURIComponent(ip) : ""}?rate=1`,
   parse: (data) => {
     if (data.success === false) return null;
     return {
@@ -784,6 +805,19 @@ var ipwhoProvider = {
     };
   }
 };
+var ipapiProvider = {
+  id: "ipapi",
+  label: "ipapi.co lookup",
+  url: (ip) => `https://ipapi.co/${ip ? `${encodeURIComponent(ip)}/` : ""}json/`,
+  parse: (data) => ({
+    city: data.city,
+    region: data.region,
+    country: data.country_name,
+    timezone: data.timezone,
+    latitude: data.latitude,
+    longitude: data.longitude
+  })
+};
 var geojsProvider = {
   id: "geojs",
   label: "geojs.io lookup",
@@ -814,13 +848,36 @@ var freeipapiProvider = {
     longitude: data.longitude
   })
 };
+var browserProvider = {
+  id: "browser",
+  label: "Browser geolocation",
+  resolve: (ip, { timeout }) => new Promise((resolve, reject) => {
+    if (ip) return reject(new Error("Browser geolocation cannot look up another IP"));
+    if (typeof navigator === "undefined" || !navigator.geolocation) {
+      return reject(new Error("Browser geolocation is unavailable"));
+    }
+    navigator.geolocation.getCurrentPosition(
+      (position) => resolve({
+        latitude: position.coords.latitude,
+        longitude: position.coords.longitude,
+        // The device knows where it is, not what that place is called;
+        // the zone it is in is the one the runtime is set to.
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+      }),
+      (error) => reject(new Error(error.message || "Browser geolocation was refused")),
+      { timeout: timeout * 1e3, maximumAge: LOCATION_TTL_MS }
+    );
+  })
+};
 var DEFAULT_GEO_PROVIDERS = [
-  ipapiProvider,
   ipwhoProvider,
+  ipapiProvider,
   geojsProvider,
   freeipapiProvider
 ];
-var BY_ID2 = new Map(DEFAULT_GEO_PROVIDERS.map((provider) => [provider.id, provider]));
+var BY_ID2 = new Map(
+  [...DEFAULT_GEO_PROVIDERS, browserProvider].map((provider) => [provider.id, provider])
+);
 function createWorkerGeoProvider(geoEndpoint) {
   return {
     id: "worker",
@@ -841,8 +898,7 @@ function resolveGeoProviders(providers, geoEndpoint) {
   const chain = configured && configured.length > 0 ? configured : DEFAULT_GEO_PROVIDERS;
   return geoEndpoint ? [createWorkerGeoProvider(geoEndpoint), ...chain] : chain;
 }
-function toLocation(provider, body) {
-  const parsed = provider.parse(body);
+function toLocation(parsed) {
   if (!parsed) return null;
   const coordinates = normalizeCoordinates(parsed.latitude, parsed.longitude);
   if (!coordinates) return null;
@@ -854,19 +910,46 @@ function toLocation(provider, body) {
     ...coordinates
   };
 }
+function locationCacheKey(geoEndpoint, ip) {
+  return `v1|${geoEndpoint ?? "public"}|${ip ?? "self"}`;
+}
+async function resolveOverHttp(provider, ip, transport) {
+  if (!provider.url || !provider.parse) {
+    throw new Error(`${provider.label} failed: provider has no url or resolve`);
+  }
+  const body = await grabJson(provider.url(ip), provider.label, transport);
+  return provider.parse(body);
+}
 async function getClientLocation(geoEndpoint, ip, options = {}) {
+  const cacheKey = locationCacheKey(geoEndpoint, ip);
+  const useCache = options.cache !== false;
+  if (useCache) {
+    const cached = toLocation(readCachedLocation(cacheKey, options.cacheTtl));
+    if (cached) return cached;
+  }
   const providers = resolveGeoProviders(options.providers, geoEndpoint);
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_SECONDS;
   const transport = {
     attempts: Math.max(1, Math.trunc(options.attempts ?? DEFAULT_ATTEMPTS)),
     retryDelay: Math.max(0, options.retryDelay ?? DEFAULT_RETRY_DELAY_MS),
-    timeout: options.timeout ?? DEFAULT_TIMEOUT_SECONDS
+    timeout
   };
   const failures = [];
-  for (const provider of providers) {
+  for (const [index, provider] of providers.entries()) {
+    const isLast = index === providers.length - 1;
     try {
-      const body = await grabJson(provider.url(ip), provider.label, transport);
-      const location = toLocation(provider, body);
-      if (location) return location;
+      const parsed = provider.resolve ? await provider.resolve(ip, { timeout }) : await resolveOverHttp(provider, ip, {
+        ...transport,
+        // A provider that has spent its daily quota will spend the retry
+        // saying so again. Move on to the next operator instead -- unless
+        // this is the last one, which has nowhere to move on to.
+        retryRateLimits: isLast
+      });
+      const location = toLocation(parsed);
+      if (location) {
+        if (useCache) writeCachedLocation(cacheKey, location);
+        return location;
+      }
       throw new Error(`${provider.label} failed: no coordinates in the response`);
     } catch (error) {
       const failure = error instanceof Error ? error : new Error(String(error));
@@ -912,6 +995,12 @@ async function resolveLocation(options) {
     attempts: options.retryAttempts,
     retryDelay: options.retryDelay,
     providers: options.geoProviders,
+    // The forecast cache is keyed by coordinates, so it can only be consulted
+    // once the location is known -- which means a location that is not cached
+    // costs an IP lookup on every refresh, cached forecast or not. This is the
+    // cache that stops that.
+    cache: options.cacheLocation,
+    cacheTtl: options.locationCacheTtl,
     fallbackLocation: options.fallbackLocation,
     onProviderError: options.onProviderError ? ({ provider, error }) => options.onProviderError?.({ provider, error, stage: "geolocation" }) : void 0
   });
@@ -989,6 +1078,8 @@ function requestKey(options) {
     options.retryDelay,
     options.timeout,
     options.allowStaleCache,
+    options.cacheLocation,
+    options.locationCacheTtl,
     options.reloadAttempts,
     options.reloadDelay,
     options.fallbackLocation?.latitude,
@@ -1417,9 +1508,12 @@ function WeatherForecast(props) {
   DEFAULT_GEO_PROVIDERS,
   DEFAULT_WEATHER_PROVIDERS,
   HttpRequestError,
+  LOCATION_TTL_MS,
   WeatherForecast,
   WeatherIcon,
+  browserProvider,
   buildForecastRequest,
+  clearCachedLocations,
   clearWeatherForecastCache,
   createOpenMeteoProvider,
   createWorkerGeoProvider,
@@ -1435,15 +1529,18 @@ function WeatherForecast(props) {
   isRetryableStatus,
   isValidLatitude,
   isValidLongitude,
+  locationCacheKey,
   metNoProvider,
   normalizeCoordinates,
   normalizeTimezone,
   openMeteoGfsProvider,
   openMeteoProvider,
+  readCachedLocation,
   resolveGeoProviders,
   resolveWeatherProviders,
   symbolToWmoCode,
   useWeatherForecast,
+  writeCachedLocation,
   wttrProvider,
   wwoToWmoCode
 });