diff --git a/EXAMPLES.md b/EXAMPLES.md index 3b33b28..9ad6a3b 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -456,8 +456,10 @@ def monitor_prices(): elif price.value < limits['low']: send_alert(commodity, price.value, limits['low'], 'BELOW') - # Example caller-selected interval; honor API limit and freshness metadata. - time.sleep(300) + # Example caller-selected interval. Derive production polling from the + # account's current limit/reset response and the source timestamps. + # See https://docs.oilpriceapi.com/guides/rate-limiting#how-often-to-poll + time.sleep(1800) if __name__ == '__main__': print("Starting price monitor...") diff --git a/docs/PERFORMANCE_GUIDE.md b/docs/PERFORMANCE_GUIDE.md index 421446e..6f7f7c7 100644 --- a/docs/PERFORMANCE_GUIDE.md +++ b/docs/PERFORMANCE_GUIDE.md @@ -235,15 +235,27 @@ while True: **Solution:** ```python -# Choose an interval from API limits and the application's freshness need +# Match the interval to the account limit and how fast the data moves. import time while True: price = client.prices.get("WTI_USD") print(f"WTI: ${price.value}") - time.sleep(300) # Example client-selected interval + # Example interval; derive this from current limit/reset metadata. + time.sleep(1800) ``` +Choose the interval from the current account response and the source timestamps +returned with the data. Polling faster than the source changes cannot return new +information, while a hard-coded schedule can exceed an account's current +allowance when product limits change. + +⚠️ **`get_multiple()` currently issues one HTTP request per code**, so it +consumes quota per commodity rather than per call. Until that is batched +(api#7240), a loop over `get()` and a call to `get_multiple()` cost the same. +See the rate-limiting guide for the current REST batching contract if you are +close to your quota. + **Better Solution (for streamed updates):** ```python # Use WebSocket streaming when the account is entitled to it.