geocoder-php · willdurand · Feb 13, 2015 · Jan 12, 2015 · Jan 16, 2015 · Jan 19, 2015
diff --git a/README.md b/README.md
@@ -106,12 +106,8 @@ objects (`AddressCollection`), each providing the following API:
 * `getLocality()` will return the `locality` or `city`;
 * `getPostalCode()` will return the `postalCode` or `zipcode`;
 * `getSubLocality()` will return the `city district`, or `sublocality`;
-* `getCounty()` will return a `County` object (with `name` and `code`
-  properties);
-* `getCountyCode()` will return the `county` code (county short name);
-* `getRegion()` will return a `Region` object (with `name` and `code`
-  properties);
-* `getRegionCode()` will return the `region` code (region short name);
+* `getAdminLevels()` will return an ordered collection (`AdminLevelCollection`)
+  of `AdminLevel` object (with `level`, `name` and `code` properties);
 * `getCountry()` will return a `Country` object (with `name` and `code`
   properties);
 * `getCountryCode()` will return the ISO `country` code;
@@ -478,13 +474,9 @@ Here is the mapping:
 
 * Zipcode: `%z`
 
-* County: `%P`
-
-* County Code: `%p`
-
-* Region: `%R`
+* Admin Level Name: `%A1`, `%A2`, `%A3`, `%A4`, `%A5`
 
-* Region Code: `%r`
+* Admin Level Code: `%a1`, `%a2`, `%a3`, `%a4`, `%a5`
 
 * Country: `%C`
 

diff --git a/src/Geocoder/Dumper/Gpx.php b/src/Geocoder/Dumper/Gpx.php
@@ -69,20 +69,22 @@ public function dump(Address $address)
      */
     protected function formatName(Address $address)
     {
-        $name  = '';
+        $name  = [];
         $array = $address->toArray();
-        $attrs = array('streetNumber', 'streetName', 'postalCode', 'locality', 'county', 'region', 'country');
+        $attrs = [
+            ['streetNumber'],
+            ['streetName'],
+            ['postalCode'],
+            ['locality'],
+            ['adminLevels', 2, 'name'],
+            ['adminLevels', 1, 'name'],
+            ['country'],
+        ];
 
         foreach ($attrs as $attr) {
-            if (isset($array[$attr]) && !empty($array[$attr])) {
-                $name .= sprintf('%s, ', $array[$attr]);
-            }
+            $name[] = \igorw\get_in($array, $attr);
         }
 
-        if (strlen($name) > 1) {
-            $name = substr($name, 0, strlen($name) - 2);
-        }
-
-        return $name;
+        return implode(', ', array_filter($name));
     }
 }
diff --git a/src/Geocoder/Exception/UnexpectedValue.php b/src/Geocoder/Exception/UnexpectedValue.php
@@ -0,0 +1,18 @@
+<?php
+
+/**
+ * This file is part of the Geocoder package.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @license    MIT License
+ */
+
+namespace Geocoder\Exception;
+
+/**
+ * @author Giorgio Premi <giosh94mhz@gmail.com>
+ */
+class UnexpectedValue extends \UnexpectedValueException implements Exception
+{
+}
diff --git a/src/Geocoder/Formatter/StringFormatter.php b/src/Geocoder/Formatter/StringFormatter.php
@@ -11,35 +11,33 @@
 namespace Geocoder\Formatter;
 
 use Geocoder\Model\Address;
+use Geocoder\Model\AdminLevel;
+use Geocoder\Model\AdminLevelCollection;
 
 /**
  * @author William Durand <william.durand1@gmail.com>
  */
 class StringFormatter
 {
-    const STREET_NUMBER = '%n';
+    const STREET_NUMBER    = '%n';
 
-    const STREET_NAME   = '%S';
+    const STREET_NAME      = '%S';
 
-    const LOCALITY      = '%L';
+    const LOCALITY         = '%L';
 
-    const POSTAL_CODE   = '%z';
+    const POSTAL_CODE      = '%z';
 
-    const SUB_LOCALITY  = '%D';
+    const SUB_LOCALITY     = '%D';
 
-    const COUNTY        = '%P';
+    const ADMIN_LEVEL      = '%A';
 
-    const COUNTY_CODE   = '%p';
+    const ADMIN_LEVEL_CODE = '%a';
 
-    const REGION        = '%R';
+    const COUNTRY          = '%C';
 
-    const REGION_CODE   = '%r';
+    const COUNTRY_CODE     = '%c';
 
-    const COUNTRY       = '%C';
-
-    const COUNTRY_CODE  = '%c';
-
-    const TIMEZONE      = '%T';
+    const TIMEZONE         = '%T';
 
     /**
      * Transform an `Address` instance into a string representation.
@@ -51,19 +49,27 @@ class StringFormatter
      */
     public function format(Address $address, $format)
     {
-        return strtr($format, array(
+        $replace = [
             self::STREET_NUMBER => $address->getStreetNumber(),
             self::STREET_NAME   => $address->getStreetName(),
             self::LOCALITY      => $address->getLocality(),
             self::POSTAL_CODE   => $address->getPostalCode(),
             self::SUB_LOCALITY  => $address->getSubLocality(),
-            self::COUNTY        => $address->getCounty()->getName(),
-            self::COUNTY_CODE   => $address->getCounty()->getCode(),
-            self::REGION        => $address->getRegion()->getName(),
-            self::REGION_CODE   => $address->getRegion()->getCode(),
             self::COUNTRY       => $address->getCountry()->getName(),
             self::COUNTRY_CODE  => $address->getCountry()->getCode(),
             self::TIMEZONE      => $address->getTimezone(),
-        ));
+        ];
+
+        for ($level = 1; $level <= AdminLevelCollection::MAX_LEVEL_DEPTH; $level ++) {
+            $replace[self::ADMIN_LEVEL . $level] = null;
+            $replace[self::ADMIN_LEVEL_CODE . $level] = null;
+        }
+
+        foreach ($address->getAdminLevels() as $level => $adminLevel) {
+            $replace[self::ADMIN_LEVEL . $level] = $adminLevel->getName();
+            $replace[self::ADMIN_LEVEL_CODE . $level] = $adminLevel->getCode();
+        }
+
+        return strtr($format, $replace);
     }
 }
diff --git a/src/Geocoder/Geocoder.php b/src/Geocoder/Geocoder.php
@@ -10,7 +10,7 @@
 
 namespace Geocoder;
 
-use Geocoder\Model\Address;
+use Geocoder\Model\AddressCollection;
 
 /**
  * @author William Durand <william.durand1@gmail.com>
@@ -27,17 +27,17 @@ interface Geocoder
      *
      * @param string $value
      *
-     * @return Address[]
+     * @return AddressCollection
      */
     public function geocode($value);
 
     /**
      * Reverses geocode given latitude and longitude values.
      *
-     * @param double $latitude.
+     * @param double $latitude
      * @param double $longitude
      *
-     * @return Address[]
+     * @return AddressCollection
      */
     public function reverse($latitude, $longitude);
 

diff --git a/src/Geocoder/Model/Address.php b/src/Geocoder/Model/Address.php
@@ -51,14 +51,9 @@ final class Address
     private $postalCode;
 
     /**
-     * @var County
+     * @var AdminLevelCollection
      */
-    private $county;
-
-    /**
-     * @var Region
-     */
-    private $region;
+    private $adminLevels;
 
     /**
      * @var Country
@@ -78,17 +73,16 @@ final class Address
      * @param string $subLocality
      */
     public function __construct(
-        Coordinates $coordinates = null,
-        Bounds $bounds           = null,
-        $streetNumber            = null,
-        $streetName              = null,
-        $postalCode              = null,
-        $locality                = null,
-        $subLocality             = null,
-        County $county           = null,
-        Region $region           = null,
-        Country $country         = null,
-        $timezone                = null
+        Coordinates $coordinates          = null,
+        Bounds $bounds                    = null,
+        $streetNumber                     = null,
+        $streetName                       = null,
+        $postalCode                       = null,
+        $locality                         = null,
+        $subLocality                      = null,
+        AdminLevelCollection $adminLevels = null,
+        Country $country                  = null,
+        $timezone                         = null
     ) {
         $this->coordinates  = $coordinates;
         $this->bounds       = $bounds;
@@ -97,8 +91,7 @@ public function __construct(
         $this->postalCode   = $postalCode;
         $this->locality     = $locality;
         $this->subLocality  = $subLocality;
-        $this->county       = $county;
-        $this->region       = $region;
+        $this->adminLevels  = $adminLevels ?: new AdminLevelCollection();
         $this->country      = $country;
         $this->timezone     = $timezone;
     }
@@ -203,43 +196,13 @@ public function getSubLocality()
     }
 
     /**
-     * Returns the county value.
+     * Returns the administrative levels.
      *
-     * @return County
+     * @return AdminLevelCollection
      */
-    public function getCounty()
+    public function getAdminLevels()
     {
-        return $this->county;
-    }
-
-    /**
-     * Returns the county short name.
-     *
-     * @return string
-     */
-    public function getCountyCode()
-    {
-        return $this->county->getCode();
-    }
-
-    /**
-     * Returns the region value.
-     *
-     * @return Region
-     */
-    public function getRegion()
-    {
-        return $this->region;
-    }
-
-    /**
-     * Returns the region short name.
-     *
-     * @return string
-     */
-    public function getRegionCode()
-    {
-        return $this->region->getCode();
+        return $this->adminLevels;
     }
 
     /**
@@ -279,6 +242,14 @@ public function getTimezone()
      */
     public function toArray()
     {
+        $adminLevels = [];
+        foreach ($this->adminLevels as $adminLevel) {
+            $adminLevels[$adminLevel->getLevel()] = [
+                'name'  => $adminLevel->getName(),
+                'code'  => $adminLevel->getCode()
+            ];
+        }
+
         return array(
             'latitude'     => $this->getLatitude(),
             'longitude'    => $this->getLongitude(),
@@ -288,10 +259,7 @@ public function toArray()
             'postalCode'   => $this->postalCode,
             'locality'     => $this->locality,
             'subLocality'  => $this->subLocality,
-            'county'       => $this->county->getName(),
-            'countyCode'   => $this->county->getCode(),
-            'region'       => $this->region->getName(),
-            'regionCode'   => $this->region->getCode(),
+            'adminLevels'  => $adminLevels,
             'country'      => $this->country->getName(),
             'countryCode'  => $this->country->getCode(),
             'timezone'     => $this->timezone,

diff --git a/src/Geocoder/Model/AddressCollection.php b/src/Geocoder/Model/AddressCollection.php
@@ -9,6 +9,9 @@ final class AddressCollection implements \IteratorAggregate, \Countable
      */
     private $addresses;
 
+    /**
+     * @param Address[] $addresses
+     */
     public function __construct(array $addresses = [])
     {
         $this->addresses = array_values($addresses);
@@ -31,7 +34,7 @@ public function count()
     }
 
     /**
-     * @return Address
+     * @return Address|null
      */
     public function first()
     {
@@ -50,8 +53,17 @@ public function slice($offset, $length = null)
         return array_slice($this->addresses, $offset, $length);
     }
 
+    /**
+     * @return bool
+     */
+    public function has($index)
+    {
+        return isset($this->addresses[$index]);
+    }
+
     /**
      * @return Address
+     * @throws \OutOfBoundsException
      */
     public function get($index)
     {