Document how to use the GeoLite2 web service

Author: oschwald

README.rst

@@ -45,11 +45,14 @@ should not be used to identify a particular address or household.
 Web Service Usage
 -----------------
 
-To use this API, you first create either a web service object with your
-MaxMind ``account_id`` and ``license_key`` or a database reader object with the
-path to your database file. After doing this, you may call the method
-corresponding to request type (e.g., ``city`` or ``country``), passing it the
-IP address you want to look up.
+To use this API, you first construct either a ``geoip2.webservice.Client`` or
+``geoip2.webservice.AsyncClient``, passing your MaxMind ``account_id`` and
+``license_key`` to the constructor. To use the GeoLite2 web service instead of
+GeoIP2 Precision, set the optional ``host`` keyword argument to
+``geolite.info``.
+
+After doing this, you may call the method corresponding to request type
+(e.g., ``city`` or ``country``), passing it the IP address you want to look up.
 
 If the request succeeds, the method call will return a model class for the
 end point you called. This model in turn contains multiple record classes,
@@ -66,12 +69,14 @@ Sync Web Service Example
     >>>
     >>> # This creates a Client object that can be reused across requests.
     >>> # Replace "42" with your account ID and "license_key" with your license
-    >>> # key.
+    >>> # key. Set the "host" keyword argument to "geolite.info" to use the
+    >>> # GeoLite2 web service instead of GeoIP2 Precision.
     >>> with geoip2.webservice.Client(42, 'license_key') as client:
     >>>
-    >>>     # Replace "insights" with the method corresponding to the web service
-    >>>     # that you are using, e.g., "country", "city".
-    >>>     response = client.insights('203.0.113.0')
+    >>>     # Replace "city" with the method corresponding to the web service
+    >>>     # that you are using, i.e., "country", "city", or "insights". Please
+    >>>     # note that Insights is not supported by the GeoLite2 web service.
+    >>>     response = client.city('203.0.113.0')
     >>>
     >>>     response.country.iso_code
     'US'
@@ -114,12 +119,14 @@ Async Web Service Example
     >>>     # loops, you must ensure the object is not used on another loop.
     >>>     #
     >>>     # Replace "42" with your account ID and "license_key" with your license
-    >>>     # key.
+    >>>     # key. Set the "host" keyword argument to "geolite.info" to use the
+    >>>     # GeoLite2 web service instead of GeoIP2 Precision.
     >>>     async with geoip2.webservice.AsyncClient(42, 'license_key') as client:
     >>>
-    >>>         # Replace "insights" with the method corresponding to the web service
-    >>>         # that you are using, e.g., "country", "city".
-    >>>         response = await client.insights('203.0.113.0')
+    >>>         # Replace "city" with the method corresponding to the web service
+    >>>         # that you are using, i.e., "country", "city", or "insights". Please
+    >>>         # note that Insights is not supported by the GeoLite2 web service.
+    >>>         response = await client.city('203.0.113.0')
     >>>
     >>>         response.country.iso_code
     'US'

geoip2/webservice.py

@@ -21,7 +21,7 @@
 SSL
 ---
 
-Requests to the GeoIP2 Precision web service are always made with SSL.
+Requests to the web service are always made with SSL.
 
 """
 
@@ -219,8 +219,8 @@ class AsyncClient(BaseClient):
     The following keyword arguments are also accepted:
 
     :param host: The hostname to make a request against. This defaults to
-      "geoip.maxmind.com". In most cases, you should not need to set this
-      explicitly.
+      "geoip.maxmind.com". To use the GeoLite2 web service instead of GeoIP2
+      Precision, set this to "geolite.info".
     :param locales: This is list of locale codes. This argument will be
       passed on to record classes to use when their name properties are
       called. The default value is ['en'].
@@ -276,7 +276,7 @@ def __init__(  # pylint: disable=too-many-arguments
         self._proxy = proxy
 
     async def city(self, ip_address: IPAddress = "me") -> City:
-        """Call GeoIP2 Precision City endpoint with the specified IP.
+        """Call City endpoint with the specified IP.
 
         :param ip_address: IPv4 or IPv6 address as a string. If no
            address is provided, the address that the web service is
@@ -305,7 +305,10 @@ async def country(self, ip_address: IPAddress = "me") -> Country:
         )
 
     async def insights(self, ip_address: IPAddress = "me") -> Insights:
-        """Call the GeoIP2 Precision: Insights endpoint with the specified IP.
+        """Call the Insights endpoint with the specified IP.
+
+        Insights is only supported by GeoIP2 Precision. The GeoLite2 web
+        service does not support it.
 
         :param ip_address: IPv4 or IPv6 address as a string. If no address
           is provided, the address that the web service is called from will
@@ -375,8 +378,8 @@ class Client(BaseClient):
     The following keyword arguments are also accepted:
 
     :param host: The hostname to make a request against. This defaults to
-      "geoip.maxmind.com". In most cases, you should not need to set this
-      explicitly.
+      "geoip.maxmind.com". To use the GeoLite2 web service instead of GeoIP2
+      Precision, set this to "geolite.info".
     :param locales: This is list of locale codes. This argument will be
       passed on to record classes to use when their name properties are
       called. The default value is ['en'].
@@ -434,7 +437,7 @@ def __init__(  # pylint: disable=too-many-arguments
             self._proxies = {"https": proxy}
 
     def city(self, ip_address: IPAddress = "me") -> City:
-        """Call GeoIP2 Precision City endpoint with the specified IP.
+        """Call City endpoint with the specified IP.
 
         :param ip_address: IPv4 or IPv6 address as a string. If no
            address is provided, the address that the web service is
@@ -460,7 +463,10 @@ def country(self, ip_address: IPAddress = "me") -> Country:
         )
 
     def insights(self, ip_address: IPAddress = "me") -> Insights:
-        """Call the GeoIP2 Precision: Insights endpoint with the specified IP.
+        """Call the Insights endpoint with the specified IP.
+
+        Insights is only supported by GeoIP2 Precision. The GeoLite2 web
+        service does not support it.
 
         :param ip_address: IPv4 or IPv6 address as a string. If no address
           is provided, the address that the web service is called from will