Document how to use the GeoLite2 web service

Author: oschwald

README.md

@@ -26,7 +26,7 @@ You should now have the file `composer.phar` in your project directory.
 
 Run in your project root:
 
-```
+```sh
 php composer.phar require geoip2/geoip2:~2.0
 ```
 
@@ -265,13 +265,33 @@ print($record->network . "\n"); // '128.101.101.101/32'
 ### Usage ###
 
 To use this API, you must create a new `\GeoIp2\WebService\Client`
-object with your `$accountId` and `$licenseKey`, then you call the method
-corresponding to a specific end point, passing it the IP address you want to
-look up.
+object with your `$accountId` and `$licenseKey`:
+
+```php
+$client = new Client(42, 'abcdef123456');
+```
+
+You may also call the constructor with additional arguments. The third argument
+specifies the language preferences when using the `->name` method on the model
+classes that this client creates. The fourth argument is additional options
+such as `host` and `timeout`.
+
+For instance, to call the GeoLite2 web service instead of GeoIP2 Precision:
+
+```php
+$client = new Client(42, 'abcdef123456', ['en'], ['host' => 'geolite.info']);
+```
+
+After creating the client, you may now call the method corresponding to a
+specific endpoint with the IP address to look up, e.g.:
+
+```php
+$record = $client->city('128.101.101.101');
+```
 
-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, each of
-which represents part of the data returned by the web service.
+If the request succeeds, the method call will return a model class for the
+endpoint you called. This model in turn contains multiple record classes, each
+of which represents part of the data returned by the web service.
 
 If there is an error, a structured exception is thrown.
 
@@ -286,7 +306,8 @@ use GeoIp2\WebService\Client;
 
 // 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" to "geolite.info" in the fourth argument options
+// array to use the GeoLite2 web service instead of GeoIP2 Precision.
 $client = new Client(42, 'abcdef123456');
 
 // Replace "city" with the method corresponding to the web service that

src/WebService/Client.php

@@ -59,7 +59,9 @@ class Client implements ProviderInterface
      * @param array  $locales    list of locale codes to use in name property
      *                           from most preferred to least preferred
      * @param array  $options    array of options. Valid options include:
-     *                           * `host` - The host to use when querying the web service.
+     *                           * `host` - The host to use when querying the web service. To
+     *                           query the GeoLite2 web service instead of GeoIP2 Precision,
+     *                           set the host to `geolite.info`.
      *                           * `timeout` - Timeout in seconds.
      *                           * `connectTimeout` - Initial connection timeout in seconds.
      *                           * `proxy` - The HTTP proxy to use. May include a schema, port,
@@ -95,7 +97,7 @@ private function userAgent(): string
     }
 
     /**
-     * This method calls the GeoIP2 Precision: City service.
+     * This method calls the City service.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      *                          address is provided, the address that the web service is called
@@ -124,7 +126,7 @@ public function city(string $ipAddress = 'me'): \GeoIp2\Model\City
     }
 
     /**
-     * This method calls the GeoIP2 Precision: Country service.
+     * This method calls the Country service.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      *                          address is provided, the address that the web service is called
@@ -153,7 +155,8 @@ public function country(string $ipAddress = 'me'): \GeoIp2\Model\Country
     }
 
     /**
-     * This method calls the GeoIP2 Precision: Insights service.
+     * This method calls the Insights service. Insights is only supported by GeoIP2
+     * Precision. The GeoLite2 web service does not support it.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      *                          address is provided, the address that the web service is called