ipinfo · mtzfederico · Jul 6, 2021 · Jul 6, 2021 · Jul 6, 2021 · Jul 6, 2021
diff --git a/README.md b/README.md
@@ -161,6 +161,14 @@ The IPinfo library can be authenticated with your IPinfo API token, which is pas
 
 In-memory caching of `details` data is provided by default via the [cachetools](https://cachetools.readthedocs.io/en/latest/) library. This uses an LRU (least recently used) cache with a TTL (time to live) by default. This means that values will be cached for the specified duration; if the cache's max size is reached, cache values will be invalidated as necessary, starting with the oldest cached value.
 
+You can access the cached property to see if the response was `cached`.
+
+```python
+>>> details = handler.getDetails(ip_address)
+>>> details.cached
+True
+```
+
 #### Modifying cache options
 
 Cache behavior can be modified by setting the `cache_options` keyword argument. `cache_options` is a dictionary in which the keys are keyword arguments specified in the `cachetools` library. The nesting of keyword arguments is to prevent name collisions between this library and its dependencies.

diff --git a/ipinfo/handler.py b/ipinfo/handler.py
@@ -78,6 +78,7 @@ def getDetails(self, ip_address=None, timeout=None):
         # check cache first.
         try:
             cached_ipaddr = self.cache[cache_key(ip_address)]
+            cached_ipaddr["cached"] = True
             return Details(cached_ipaddr)
         except KeyError:
             pass
@@ -101,7 +102,7 @@ def getDetails(self, ip_address=None, timeout=None):
         # format & cache
         handler_utils.format_details(details, self.countries)
         self.cache[cache_key(ip_address)] = details
-
+        details["cached"] = False
         return Details(details)
 
     def getBatchDetails(
@@ -160,6 +161,7 @@ def getBatchDetails(
 
             try:
                 cached_ipaddr = self.cache[cache_key(ip_address)]
+                cached_ipaddr["cached"] = True
                 result[ip_address] = cached_ipaddr
             except KeyError:
                 lookup_addresses.append(ip_address)
@@ -208,6 +210,7 @@ def getBatchDetails(
             json_response = response.json()
             for ip_address, details in json_response.items():
                 self.cache[cache_key(ip_address)] = details
+                details["cached"] = False
 
             # merge cached results with new lookup
             result.update(json_response)

diff --git a/ipinfo/handler_async.py b/ipinfo/handler_async.py
@@ -103,6 +103,7 @@ async def getDetails(self, ip_address=None, timeout=None):
         # check cache first.
         try:
             cached_ipaddr = self.cache[cache_key(ip_address)]
+            cached_ipaddr["cached"] = True
             return Details(cached_ipaddr)
         except KeyError:
             pass
@@ -125,6 +126,7 @@ async def getDetails(self, ip_address=None, timeout=None):
         handler_utils.format_details(details, self.countries)
         self.cache[cache_key(ip_address)] = details
 
+        details["cached"] = False
         return Details(details)
 
     async def getBatchDetails(
@@ -188,6 +190,7 @@ async def getBatchDetails(
 
             try:
                 cached_ipaddr = self.cache[cache_key(ip_address)]
+                cached_ipaddr["cached"] = True
                 result[ip_address] = cached_ipaddr
             except KeyError:
                 lookup_addresses.append(ip_address)
@@ -276,6 +279,7 @@ async def _do_batch_req(
                 self.cache[cache_key(ip_address)] = details
 
         # merge cached results with new lookup
+        json_resp["cached"] = False
         result.update(json_resp)
 
     def _ensure_aiohttp_ready(self):