[ArcGISOnline] Updated Readme to clarify token creation/use. (#1105)

Readme.md

@@ -11,32 +11,46 @@
 This is the ArcGIS provider from the PHP Geocoder. This is a **READ ONLY** repository. See the
 [main repo](https://github.com/geocoder-php/Geocoder) for information and documentation.
 
+ArcGIS provides 2 APIs for geocoding addresses:
+* [`geocodeAddresses`](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-geocode-addresses.htm)
+* [`findAddressCandidates`](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm)
+    * This API states:
+    > Applications are contractually prohibited from storing the results of
+    geocoding transactions unless they make the request by passing the
+    `forStorage` parameter with a value of `true` and the `token` parameter with
+    a valid ArcGIS Online token.
+
+Since a token is required for the `geocodeAddresses` API, the
+`geocodeQuery` method checks the `token` property:
+* If `token` is `NULL`, it uses the `findAddressCandidates` API.
+* If `token` is not `NULL`, it uses the `geocodeAddresses` API.
+    * If the `token` value is invalid or has expired, you will get an error.
+    * Tokens have a maximum lifetime of 14 days.
+    * [Instructions for generating an ArcGIS token](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-authenticate-a-request.htm#GUID-F2BECC7B-5042-4D89-87FC-4CE31012E66D)
+
 ## Usage
 
+### Without a token
+
 ```php
 $httpClient = new \Http\Adapter\Guzzle6\Client();
 
 $provider = new \Geocoder\Provider\ArcGISList\ArcGISList($httpClient);
 
+// Uses the `findAddressCandidates` operation. Result storage is prohibited.
 $result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
 ```
 
-### Storing results
-
-ArcGIS prohibits storing the results of geocoding transactions without providing
-a valid ArcGIS Online token, which requires
-[ArcGIS Online credentials](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-authenticate-a-request.htm).
-
-You can use the static `token` method on the provider to create a client which
-uses your valid ArcGIS Online token:
+### With a token
 
 ```php
 
 $httpClient = new \Http\Adapter\Guzzle6\Client();
 
-// Client ID is required. Private key is optional.
+// Your token is required.
 $provider = \Geocoder\Provider\ArcGISList\ArcGISList::token($httpClient, 'your-token');
 
+// Uses the `geocodeAddresses` operation. Result storage is permitted.
 $result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
 ```
 
@@ -48,7 +62,7 @@ composer require geocoder-php/arcgis-online-provider
 
 ### Note
 
-It is possible to specify a `sourceCountry` to restrict result to this specific
+It is possible to specify a `sourceCountry` to restrict results to this specific
 country thus reducing request time (note that this doesn't work on reverse
 geocoding).