Update for GeoIP2 web services v2.1

CHANGELOG.md

@@ -1,6 +1,16 @@
 CHANGELOG
 =========
 
+0.7.0 (2014-07-XX)
+------------------
+
+* The web service client API has been updated for the v2.1 release of the web
+  service. In particular, the `cityIspOrg` and `omni` methods on
+  `GeoIP2\WebService\Client` should be considered deprecated. The `city`
+  method now provides all of the data formerly provided by `cityIspOrg`, and
+  the `omni` method has been replaced by the `insights` method.
+
+
 0.6.3 (2014-05-12)
 ------------------
 

README.md

@@ -202,7 +202,7 @@ use GeoIp2\WebService\Client;
 $client = new Client(42, 'abcdef123456');
 
 // Replace "city" with the method corresponding to the web service that
-// you are using, e.g., "country", "cityIspOrg", "omni".
+// you are using, e.g., "country", "insights".
 $record = $client->city('128.101.101.101');
 
 print($record->country->isoCode . "\n"); // 'US'
@@ -232,7 +232,7 @@ Because of these factors, it is possible for any end point to return a record
 where some or all of the attributes are unpopulated.
 
 See the
-[GeoIP2 web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
+[GeoIP2 Precision web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
 for details on what data each end point may return.
 
 The only piece of data which is always returned is the `ipAddress`

src/GeoIp2/Database/Reader.php

@@ -92,37 +92,41 @@ class Reader implements ProviderInterface
     }
 
     /**
-     * This method returns a GeoIP2 City/ISP/Org model.
+     * This method returns a GeoIP2 City model.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string.
      *
-     * @return \GeoIp2\Model\CityIspOrg
+     * @return \GeoIp2\Model\City
      *
      * @throws \GeoIp2\Exception\AddressNotFoundException if the address is
      *         not in the database.
      * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database
      *         is corrupt or invalid
+     *
+     * @deprecated deprecated since version 0.7.0
      */
     public function cityIspOrg($ipAddress)
     {
-        return $this->modelFor('CityIspOrg', $ipAddress);
+        return $this->modelFor('City', $ipAddress);
     }
 
     /**
-     * This method returns a GeoIP2 Omni model.
+     * This method returns a GeoIP2 Insights model.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string.
      *
-     * @return \GeoIp2\Model\Omni
+     * @return \GeoIp2\Model\Insights
      *
      * @throws \GeoIp2\Exception\AddressNotFoundException if the address is
      *         not in the database.
      * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database
      *         is corrupt or invalid
+     *
+     * @deprecated deprecated since version 0.7.0
      */
     public function omni($ipAddress)
     {
-        return $this->modelFor('Omni', $ipAddress);
+        return $this->modelFor('Insights', $ipAddress);
     }
 
     public function connectionType($ipAddress)

src/GeoIp2/Model/City.php

@@ -3,11 +3,10 @@
 namespace GeoIp2\Model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2
+ * Model class for the data returned by GeoIP2 City web service and database.
- * City end point.
  *
- * The only difference between the City, City/ISP/Org, and Omni model
+ * The only difference between the City and Insights model classes is which
- * classes is which fields in each record may be populated. See
+ * fields in each record may be populated. See
  * http://dev.maxmind.com/geoip/geoip2/web-services more details.
  *
  * @property \GeoIp2\Record\City $city City data for the requested IP

src/GeoIp2/Model/CityIspOrg.php

@@ -1,57 +0,0 @@
-<?php
-
-namespace GeoIp2\Model;
-
-/**
- * This class provides a model for the data returned by the GeoIP2
- * City/ISP/Org end point.
- *
- * The only difference between the City, City/ISP/Org, and Omni model
- * classes is which fields in each record may be populated. See
- * http://dev.maxmind.com/geoip/geoip2/web-services more details.
- *
- * @property \GeoIp2\Record\City $city City data for the requested IP
- * address.
- *
- * @property \GeoIp2\Record\Continent $continent Continent data for the
- * requested IP address.
- *
- * @property \GeoIp2\Record\Country $country Country data for the requested
- * IP address. This object represents the country where MaxMind believes the
- * end user is located.
- *
- * @property \GeoIp2\Record\Location $location Location data for the
- * requested IP address.
- *
- * @property \GeoIp2\Record\MaxMind $maxmind Data related to your MaxMind
- * account.
- *
- * @property \GeoIp2\Record\Country $registeredCountry Registered country
- * data for the requested IP address. This record represents the country
- * where the ISP has registered a given IP block and may differ from the
- * user's country.
- *
- * @property \GeoIp2\Record\RepresentedCountry $representedCountry
- * Represented country data for the requested IP address. The represented
- * country is used for things like military bases or embassies. It is only
- * present when the represented country differs from the country.
- *
- * @property array $subdivisions An array of {@link \GeoIp2\Record\Subdivision}
- * objects representing the country subdivisions for the requested IP
- * address. The number and type of subdivisions varies by country, but a
- * subdivision is typically a state, province, county, etc. Subdivisions
- * are ordered from most general (largest) to most specific (smallest).
- * If the response did not contain any subdivisions, this method returns
- * an empty array.
- *
- * @property \GeoIp2\Record\Subdivision $mostSpecificSubdivision An  object
- * representing the most specific subdivision returned. If the response
- * did not contain any subdivisions, this method returns an empty
- * {@link \GeoIp2\Record\Subdivision} object.
- *
- * @property \GeoIp2\Record\Traits $traits Data for the traits of the
- * requested IP address.
- */
-class CityIspOrg extends City
-{
-}

src/GeoIp2/Model/Country.php

@@ -3,10 +3,10 @@
 namespace GeoIp2\Model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 Country.
+ * Model class for the data returned by GeoIP2 Country web service and database.
  *
- * The only difference between the City, City/ISP/Org, and Omni model
+ * The only difference between the City and Insights model classes is which
- * classes is which fields in each record may be populated. See
+ * fields in each record may be populated. See
  * http://dev.maxmind.com/geoip/geoip2/web-services more details.
  *
  * @property \GeoIp2\Record\Continent $continent Continent data for the

src/GeoIp2/Model/Insights.php

@@ -3,11 +3,10 @@
 namespace GeoIp2\Model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2
+ * Model class for the data returned by GeoIP2 Precision: Insights web service.
- * Omni end point.
  *
- * The only difference between the City, City/ISP/Org, and Omni model
+ * The only difference between the City and Insights model classes is which
- * classes is which fields in each record may be populated. See
+ * fields in each record may be populated. See
  * http://dev.maxmind.com/geoip/geoip2/web-services more details.
  *
  * @property \GeoIp2\Record\City $city City data for the requested IP
@@ -52,6 +51,6 @@ namespace GeoIp2\Model;
  * @property \GeoIp2\Record\Traits $traits Data for the traits of the
  * requested IP address.
  */
-class Omni extends CityIspOrg
+class Insights extends City
 {
 }

src/GeoIp2/ProviderInterface.php

@@ -21,14 +21,18 @@ interface ProviderInterface
     /**
      * @param ipAddress
      *            IPv4 or IPv6 address to lookup.
-     * @return \GeoIp2\Model\CityIspOrg A CityIspOrg model for the requested IP address.
+     * @return \GeoIp2\Model\City A City model for the requested IP address.
+     *
+     * @deprecated deprecated since version 0.7.0
      */
     public function cityIspOrg($ipAddress);
 
     /**
      * @param ipAddress
      *            IPv4 or IPv6 address to lookup.
-     * @return \GeoIp2\Model\Omni An Omni model for the requested IP address.
+     * @return \GeoIp2\Model\Insights An Insights model for the requested IP address.
+     *
+     * @deprecated deprecated since version 0.7.0
      */
     public function omni($ipAddress);
 }

src/GeoIp2/Record/City.php

@@ -9,7 +9,7 @@ namespace GeoIp2\Record;
  *
  * @property int $confidence A value from 0-100 indicating MaxMind's
  * confidence that the city is correct. This attribute is only available
- * from the Omni end point.
+ * from the Insights end point.
  *
  * @property int $geonameId The GeoName ID for the city. This attribute
  * is returned by all end points.

src/GeoIp2/Record/Location.php

@@ -9,7 +9,7 @@ namespace GeoIp2\Record;
  *
  * @property int $accuracyRadius The radius in kilometers around the
  * specified location where the IP address is likely to be. This attribute
- * is only available from the Omni end point.
+ * is only available from the Insights end point.
  *
  * @property float $latitude The latitude of the location as a floating
  * point number. This attribute is returned by all end points except the

src/GeoIp2/Record/Postal.php

@@ -14,7 +14,7 @@ namespace GeoIp2\Record;
  *
  * @property int $confidence A value from 0-100 indicating MaxMind's
  * confidence that the postal code is correct. This attribute is only
- * available from the Omni end point.
+ * available from the Insights end point.
  */
 class Postal extends AbstractRecord
 {

src/GeoIp2/Record/RepresentedCountry.php

@@ -13,7 +13,7 @@ namespace GeoIp2\Record;
  *
  * @property int $confidence A value from 0-100 indicating MaxMind's
  * confidence that the country is correct. This attribute is only available
- * from the Omni end point.
+ * from the Insights end point.
  *
  * @property int $geonameId The GeoName ID for the country. This attribute is
  * returned by all end points.

src/GeoIp2/Record/Subdivision.php

@@ -10,7 +10,7 @@ namespace GeoIp2\Record;
  *
  * @property int $confidence This is a value from 0-100 indicating MaxMind's
  * confidence that the subdivision is correct. This attribute is only
- * available from the Omni end point.
+ * available from the Insights end point.
  *
  * @property int $geonameId This is a GeoName ID for the subdivision. This
  * attribute is returned by all end points except Country.

src/GeoIp2/Record/Traits.php

@@ -11,18 +11,18 @@ namespace GeoIp2\Record;
  * @property int $autonomousSystemNumber The {@link
  * http://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous
  * system number} associated with the IP address. This attribute is only
- * available from the City/ISP/Org and Omni end points.
+ * available from the City and Insights web service end points.
  *
  * @property string $autonomousSystemOrganization The organization
  * associated with the registered {@link
  * http://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous
  * system number} for the IP address. This attribute is only available from
- * the City/ISP/Org and Omni end points.
+ * the City and Insights web service end points.
  *
  * @property string $domain The second level domain associated with the
  * IP address. This will be something like "example.com" or "example.co.uk",
  * not "foo.example.com". This attribute is only available from the
- * City/ISP/Org and Omni end points.
+ * City and Insights web service end points.
  *
  * @property string $ipAddress The IP address that the data in the model
  * is for. If you performed a "me" lookup against the web service, this
@@ -40,12 +40,12 @@ namespace GeoIp2\Record;
  * end points.
  *
  * @property string $isp The name of the ISP associated with the IP address.
- * This attribute is only available from the City/ISP/Org and Omni end
+ * This attribute is only available from the City and Insights web service end
  * points.
  *
  * @property string $organization The name of the organization associated
- * with the IP address. This attribute is only available from the City/ISP/Org
+ * with the IP address. This attribute is only available from the City and
- * and Omni end points.
+ * Insights web service end points.
  *
  * @property string $userType <p>The user type associated with the IP
  *  address. This can be one of the following values:</p>
@@ -66,7 +66,10 @@ namespace GeoIp2\Record;
  *    <li>search_engine_spider
  *    <li>traveler
  * </ul>
- * <p>This attribute is only available from the Omni end point.</p>
+ * <p>
+ *   This attribute is only available from the Insight web service end
+ *   point.
+ * </p>
  */
 class Traits extends AbstractRecord
 {

src/GeoIp2/WebService/Client.php

@@ -15,10 +15,10 @@ use Guzzle\Http\Exception\ClientErrorResponseException;
 use Guzzle\Http\Exception\ServerErrorResponseException;
 
 /**
- * This class provides a client API for all the GeoIP2 web service's
+ * This class provides a client API for all the GeoIP2 Precision web service
- * end points. The end points are Country, City, City/ISP/Org, and Omni. Each
+ * end points. The end points are Country, City, and Insights. Each end point
- * end point returns a different set of data about an IP address, with Country
+ * returns a different set of data about an IP address, with Country returning
- * returning the least data and Omni the most.
+ * the least data and Insights the most.
  *
  * Each web service end point is represented by a different model class, and
  * these model classes in turn contain multiple Record classes. The record
@@ -80,7 +80,7 @@ class Client implements ProviderInterface
     }
 
     /**
-     * This method calls the GeoIP2 City endpoint.
+     * This method calls the GeoIP2 Precision: City endpoint.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      * address is provided, the address that the web service is called
@@ -112,7 +112,41 @@ class Client implements ProviderInterface
     }
 
     /**
-     * This method calls the GeoIP2 Country endpoint.
+     * This method calls the GeoIP2 Precision: City endpoint.
+     *
+     * @param string $ipAddress IPv4 or IPv6 address as a string. If no
+     * address is provided, the address that the web service is called
+     * from will be used.
+     *
+     * @return \GeoIp2\Model\City
+     *
+     * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
+     *   provided is not in our database (e.g., a private address).
+     * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
+     *   with the user ID or license key that you provided.
+     * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
+     *   of queries.
+     * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
+     *   received by the web service but is invalid for some other reason.
+     *   This may indicate an issue with this API. Please report the error to
+     *   MaxMind.
+     * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
+     *   code or message was returned. This could indicate a problem with the
+     *   connection between your server and the web service or that the web
+     *   service returned an invalid document or 500 error code.
+     * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
+     *   class to the above exceptions. It will be thrown directly if a 200
+     *   status code is returned but the body is invalid.
+     *
+     * @deprecated deprecated since version 0.7.0
+     */
+    public function cityIspOrg($ipAddress = 'me')
+    {
+        return $this->city($ipAddress);
+    }
+
+    /**
+     * This method calls the GeoIP2 Precision: Country endpoint.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      * address is provided, the address that the web service is called
@@ -144,13 +178,13 @@ class Client implements ProviderInterface
     }
 
     /**
-     * This method calls the GeoIP2 City/ISP/Org endpoint.
+     * This method calls the GeoIP2 Precision: Insights endpoint.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      * address is provided, the address that the web service is called
      * from will be used.
      *
-     * @return \GeoIp2\Model\CityIspOrg
+     * @return \GeoIp2\Model\Insights
      *
      * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
      *   provided is not in our database (e.g., a private address).
@@ -169,20 +203,22 @@ class Client implements ProviderInterface
      * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
      *   class to the above exceptions. It will be thrown directly if a 200
      *   status code is returned but the body is invalid.
+     *
+     * @deprecated deprecated since version 0.7.0
      */
-    public function cityIspOrg($ipAddress = 'me')
+    public function insights($ipAddress = 'me')
     {
-        return $this->responseFor('city_isp_org', 'CityIspOrg', $ipAddress);
+        return $this->responseFor('insights', 'Insights', $ipAddress);
     }
 
     /**
-     * This method calls the GeoIP2 Omni endpoint.
+     * This method calls the GeoIP2 Precision: Insights (prev. Omni) endpoint.
      *
      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
      * address is provided, the address that the web service is called
      * from will be used.
      *
-     * @return \GeoIp2\Model\Omni
+     * @return \GeoIp2\Model\Insights
      *
      * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
      *   provided is not in our database (e.g., a private address).
@@ -201,10 +237,12 @@ class Client implements ProviderInterface
      * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
      *   class to the above exceptions. It will be thrown directly if a 200
      *   status code is returned but the body is invalid.
+     *
+     * @deprecated deprecated since version 0.7.0
      */
     public function omni($ipAddress = 'me')
     {
-        return $this->responseFor('omni', 'Omni', $ipAddress);
+        return $this->insights($ipAddress);
     }
 
     private function responseFor($endpoint, $class, $ipAddress)
@@ -354,6 +392,6 @@ class Client implements ProviderInterface
 
     private function baseUri()
     {
-        return 'https://' . $this->host . '/geoip/v2.0';
+        return 'https://' . $this->host . '/geoip/v2.1';
     }
 }

tests/GeoIp2/Test/Model/InsightsTest.php

@@ -2,9 +2,9 @@
 
 namespace GeoIp2\Test\Model;
 
-use GeoIp2\Model\Omni;
+use GeoIp2\Model\Insights;
 
-class OmniTest extends \PHPUnit_Framework_TestCase
+class InsightsTest extends \PHPUnit_Framework_TestCase
 {
 
     public function testFull()
@@ -69,12 +69,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase
             ),
         );
 
-        $model = new Omni($raw, array('en'));
+        $model = new Insights($raw, array('en'));
 
         $this->assertInstanceOf(
-            'GeoIp2\Model\Omni',
+            'GeoIp2\Model\Insights',
             $model,
-            'GeoIp2\Model\Omni object'
+            'GeoIp2\Model\Insights object'
         );
 
         $this->assertInstanceOf(
@@ -147,12 +147,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase
     {
         $raw = array('traits' => array('ip_address' => '5.6.7.8'));
 
-        $model = new Omni($raw, array('en'));
+        $model = new Insights($raw, array('en'));
 
         $this->assertInstanceOf(
-            'GeoIp2\Model\Omni',
+            'GeoIp2\Model\Insights',
             $model,
-            'GeoIp2\Model\Omni object with no data except traits.ipAddress'
+            'GeoIp2\Model\Insights object with no data except traits.ipAddress'
         );
 
         $this->assertInstanceOf(
@@ -231,12 +231,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase
         );
 
         // checking whether there are exceptions with unknown keys
-        $model = new Omni($raw, array('en'));
+        $model = new Insights($raw, array('en'));
 
         $this->assertInstanceOf(
-            'GeoIp2\Model\Omni',
+            'GeoIp2\Model\Insights',
             $model,
-            'no exception when Omni model gets raw data with unknown keys'
+            'no exception when Insights model gets raw data with unknown keys'
         );
 
         $this->assertEquals(

tests/GeoIp2/Test/WebService/ClientTest.php

@@ -198,18 +198,22 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
 
-    public function testOmni()
+    public function testInsights()
     {
-        $omni = $this->client($this->getResponse('1.2.3.4'))
-            ->omni('1.2.3.4');
 
-        $this->assertInstanceOf('GeoIp2\Model\Omni', $omni);
+        $methods = array('omni', 'insights');
+        foreach ($methods as $method) {
+            $record = $this->client($this->getResponse('1.2.3.4'))
+                ->$method('1.2.3.4');
 
-        $this->assertEquals(
+            $this->assertInstanceOf('GeoIp2\Model\Insights', $record);
-            42,
+
-            $omni->continent->geonameId,
+            $this->assertEquals(
-            'continent geoname_id is 42'
+                42,
-        );
+                $record->continent->geonameId,
+                'continent geoname_id is 42'
+            );
+        }
     }
 
     public function testCity()
@@ -225,7 +229,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
         $client = $this->client($this->getResponse('me'));
 
         $this->assertInstanceOf(
-            'GeoIp2\Model\CityIspOrg',
+            'GeoIp2\Model\City',
             $client->cityIspOrg('me'),
             'can set ip parameter to me'
         );
@@ -233,7 +237,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
 
     /**
      * @expectedException GeoIp2\Exception\GeoIp2Exception
-     * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.0/country/1.2.3.5 but did not receive a HTTP body.
+     * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.1/country/1.2.3.5 but did not receive a HTTP body.
      */
     public function testNoBodyException()
     {
@@ -244,7 +248,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
 
     /**
      * @expectedException GeoIp2\Exception\GeoIp2Exception
-     * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.0/country/2.2.3.5 but could not decode the response as JSON:
+     * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.1/country/2.2.3.5 but could not decode the response as JSON:
      */
     public function testBadBodyException()
     {
@@ -332,7 +336,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     /**
      * @expectedException GeoIp2\Exception\HttpException
      * @expectedExceptionCode 406
-     * @expectedExceptionMessage Received a 406 error for https://geoip.maxmind.com/geoip/v2.0/country/1.2.3.12 with the following body: Cannot satisfy your Accept-Charset requirements
+     * @expectedExceptionMessage Received a 406 error for https://geoip.maxmind.com/geoip/v2.1/country/1.2.3.12 with the following body: Cannot satisfy your Accept-Charset requirements
      */
     public function test406Exception()
     {
@@ -426,7 +430,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
         $request = $all_requests[0];
 
         $this->assertEquals(
-            'https://geoip.maxmind.com/geoip/v2.0/country/1.2.3.4',
+            'https://geoip.maxmind.com/geoip/v2.1/country/1.2.3.4',
             $request->getUrl(),
             'got expected URI for Country request'
         );