├── .gitignore
├── phpdoc.dist.xml
├── composer.json
├── LICENSE-MIT
├── README.md
└── src
    └── GoogleMapsGeocoder.php


/.gitignore:
--------------------------------------------------------------------------------
1 | composer.lock
2 | vendor/
3 | doc/
4 | phpdoc.xml
5 | 


--------------------------------------------------------------------------------
/phpdoc.dist.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8" ?>
 2 | <phpdoc>
 3 |   <title>GoogleMapsGeocoder</title>
 4 |   <parser>
 5 |     <target>doc</target>
 6 |     <visibility>public</visibility>
 7 |   </parser>
 8 |   <transformer>
 9 |     <target>doc</target>
10 |   </transformer>
11 |   <transformations>
12 |     <template name="responsive" />
13 |   </transformations>
14 |   <files>
15 |     <directory>src</directory>
16 |   </files>
17 | </phpdoc>
18 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "jstayton/google-maps-geocoder",
 3 |     "type": "library",
 4 |     "description": "A PHP wrapper for the Google Maps Geocoding API v3.",
 5 |     "keywords": ["google", "map", "maps", "gmap", "gmaps", "geocode", "geocoder", "geocoding"],
 6 |     "homepage": "https://github.com/jstayton/GoogleMapsGeocoder",
 7 |     "license": "MIT",
 8 |     "authors": [
 9 |         {
10 |             "name": "Justin Stayton",
11 |             "homepage": "http://justinstayton.com",
12 |             "role": "Developer"
13 |         }
14 |     ],
15 |     "autoload": {
16 |         "psr-0": {
17 |             "GoogleMapsGeocoder": "src/"
18 |         }
19 |     },
20 |     "require": {
21 |         "php": ">=5.2.0"
22 |     },
23 |     "require-dev": {
24 |         "phpdocumentor/phpdocumentor": "*"
25 |     }
26 | }
27 | 


--------------------------------------------------------------------------------
/LICENSE-MIT:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2015 Justin Stayton
 2 | 
 3 | Permission is hereby granted, free of charge, to any person
 4 | obtaining a copy of this software and associated documentation
 5 | files (the "Software"), to deal in the Software without
 6 | restriction, including without limitation the rights to use,
 7 | copy, modify, merge, publish, distribute, sublicense, and/or sell
 8 | copies of the Software, and to permit persons to whom the
 9 | Software is furnished to do so, subject to the following
10 | conditions:
11 | 
12 | The above copyright notice and this permission notice shall be
13 | included in all copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
17 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 | OTHER DEALINGS IN THE SOFTWARE.
23 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | **NOTICE:** _This project is deprecated and no longer maintained. If you'd like
  2 | to continue supporting a forked version, please reach out on Twitter
  3 | ([@kidjustino](https://twitter.com/kidjustino)) to have it listed here._
  4 | 
  5 | GoogleMapsGeocoder
  6 | ==================
  7 | 
  8 | [![Latest Stable Version](https://poser.pugx.org/jstayton/google-maps-geocoder/v/stable.png)](https://packagist.org/packages/jstayton/google-maps-geocoder)
  9 | [![Total Downloads](https://poser.pugx.org/jstayton/google-maps-geocoder/downloads.png)](https://packagist.org/packages/jstayton/google-maps-geocoder)
 10 | 
 11 | A PHP wrapper for the Google Maps Geocoding API v3.
 12 | 
 13 | Developed by [Justin Stayton](http://justinstayton.com) while at
 14 | [Monk Development](http://monkdev.com).
 15 | 
 16 | *   [Documentation](http://jstayton.github.io/GoogleMapsGeocoder/classes/GoogleMapsGeocoder.html)
 17 | *   [Release Notes](https://github.com/jstayton/GoogleMapsGeocoder/wiki/Release-Notes)
 18 | 
 19 | Requirements
 20 | ------------
 21 | 
 22 | *   PHP >= 5.2.0
 23 | 
 24 | Installation
 25 | ------------
 26 | 
 27 | ### Composer
 28 | 
 29 | The recommended installation method is through
 30 | [Composer](http://getcomposer.org/), a dependency manager for PHP. Just add
 31 | `jstayton/google-maps-geocoder` to your project's `composer.json` file:
 32 | 
 33 | ```json
 34 | {
 35 |     "require": {
 36 |         "jstayton/google-maps-geocoder": "*"
 37 |     }
 38 | }
 39 | ```
 40 | 
 41 | [More details](http://packagist.org/packages/jstayton/google-maps-geocoder) can
 42 | be found over at [Packagist](http://packagist.org).
 43 | 
 44 | ### Manually
 45 | 
 46 | 1.  Copy `src/GoogleMapsGeocoder.php` to your codebase, perhaps to the `vendor`
 47 |     directory.
 48 | 2.  Add the `GoogleMapsGeocoder` class to your autoloader or `require` the file
 49 |     directly.
 50 | 
 51 | Getting Started
 52 | ---------------
 53 | 
 54 | We'll use the address of [Monk Development](http://monkdev.com) for this
 55 | example:
 56 | 
 57 | ```php
 58 | $address = "2707 Congress St., San Diego, CA 92110";
 59 | ```
 60 | 
 61 | There are two ways to set the address of a `GoogleMapsGeocoder` object. Either
 62 | the address can be passed to the constructor:
 63 | 
 64 | ```php
 65 | $Geocoder = new GoogleMapsGeocoder($address);
 66 | ```
 67 | 
 68 | Or the address can be set after the object is created:
 69 | 
 70 | ```php
 71 | $Geocoder = new GoogleMapsGeocoder();
 72 | $Geocoder->setAddress($address);
 73 | ```
 74 | 
 75 | By default, the `format` is set to `json` and the `sensor` is set to `false`.
 76 | These values can be changed either through the constructor or after the object
 77 | is created. See the
 78 | [documentation](http://jstayton.github.io/GoogleMapsGeocoder/classes/GoogleMapsGeocoder.html)
 79 | for the complete list of API parameters that can be changed.
 80 | 
 81 | Once all parameters are set, the final step is to send the request to the
 82 | Google Maps Geocoding API:
 83 | 
 84 | ```php
 85 | $response = $Geocoder->geocode();
 86 | ```
 87 | 
 88 | The `geocode` method converts the response into a JSON associative array
 89 | (default) or `SimpleXMLElement` object depending on the specified `format`. See
 90 | the `geocode`
 91 | [documentation](http://jstayton.github.io/GoogleMapsGeocoder/classes/GoogleMapsGeocoder.html#method_geocode)
 92 | for making the request over HTTPS or preventing conversion (instead returning
 93 | the raw plain text response).
 94 | 
 95 | Feedback
 96 | --------
 97 | 
 98 | Please open an issue to request a feature or submit a bug report. Or even if
 99 | you just want to provide some feedback, I'd love to hear. I'm also available on
100 | Twitter as [@kidjustino](https://twitter.com/kidjustino).
101 | 
102 | Contributing
103 | ------------
104 | 
105 | 1.  Fork it.
106 | 2.  Create your feature branch (`git checkout -b my-new-feature`).
107 | 3.  Commit your changes (`git commit -am 'Added some feature'`).
108 | 4.  Push to the branch (`git push origin my-new-feature`).
109 | 5.  Create a new Pull Request.
110 | 


--------------------------------------------------------------------------------
/src/GoogleMapsGeocoder.php:
--------------------------------------------------------------------------------
   1 | <?php
   2 | 
   3 |   /**
   4 |    * A PHP wrapper for the Google Maps Geocoding API v3.
   5 |    *
   6 |    * @author    Justin Stayton
   7 |    * @copyright Copyright 2015 by Justin Stayton
   8 |    * @license   https://github.com/jstayton/Miner/blob/master/LICENSE-MIT MIT
   9 |    * @link      https://developers.google.com/maps/documentation/geocoding/intro
  10 |    * @package   GoogleMapsGeocoder
  11 |    * @version   2.4.0
  12 |    */
  13 |   class GoogleMapsGeocoder {
  14 | 
  15 |     /**
  16 |      * Domain portion of the Google Geocoding API URL.
  17 |      */
  18 |     const URL_DOMAIN = "maps.googleapis.com";
  19 | 
  20 |     /**
  21 |      * Path portion of the Google Geocoding API URL.
  22 |      */
  23 |     const URL_PATH = "/maps/api/geocode/";
  24 | 
  25 |     /**
  26 |      * HTTP URL of the Google Geocoding API.
  27 |      */
  28 |     const URL_HTTP = "http://maps.googleapis.com/maps/api/geocode/";
  29 | 
  30 |     /**
  31 |      * HTTPS URL of the Google Geocoding API.
  32 |      */
  33 |     const URL_HTTPS = "https://maps.googleapis.com/maps/api/geocode/";
  34 | 
  35 |     /**
  36 |      * JSON response format.
  37 |      */
  38 |     const FORMAT_JSON = "json";
  39 | 
  40 |     /**
  41 |      * XML response format.
  42 |      */
  43 |     const FORMAT_XML = "xml";
  44 | 
  45 |     /**
  46 |      * No errors occurred, the address was successfully parsed and at least one
  47 |      * geocode was returned.
  48 |      */
  49 |     const STATUS_SUCCESS = "OK";
  50 | 
  51 |     /**
  52 |      * Geocode was successful, but returned no results.
  53 |      */
  54 |     const STATUS_NO_RESULTS = "ZERO_RESULTS";
  55 | 
  56 |     /**
  57 |      * Over limit of 2,500 (100,000 if premier) requests per day.
  58 |      */
  59 |     const STATUS_OVER_LIMIT = "OVER_QUERY_LIMIT";
  60 | 
  61 |     /**
  62 |      * Request denied, usually because of missing sensor parameter.
  63 |      */
  64 |     const STATUS_REQUEST_DENIED = "REQUEST_DENIED";
  65 | 
  66 |     /**
  67 |      * Invalid request, usually because of missing parameter that's required.
  68 |      */
  69 |     const STATUS_INVALID_REQUEST = "INVALID_REQUEST";
  70 | 
  71 |     /**
  72 |      * Unnown server error. May succeed if tried again.
  73 |      */
  74 |     const STATUS_UNKNOWN_ERROR = "UNKNOWN_ERROR";
  75 | 
  76 |     /**
  77 |      * Returned result is a precise street address.
  78 |      */
  79 |     const LOCATION_TYPE_ROOFTOP = "ROOFTOP";
  80 | 
  81 |     /**
  82 |      * Returned result is between two precise points (usually on a road).
  83 |      */
  84 |     const LOCATION_TYPE_RANGE = "RANGE_INTERPOLATED";
  85 | 
  86 |     /**
  87 |      * Returned result is the geometric center of a polyline (i.e., a street)
  88 |      * or polygon (i.e., a region).
  89 |      */
  90 |     const LOCATION_TYPE_CENTER = "GEOMETRIC_CENTER";
  91 | 
  92 |     /**
  93 |      * Returned result is approximate.
  94 |      */
  95 |     const LOCATION_TYPE_APPROXIMATE = "APPROXIMATE";
  96 | 
  97 |     /**
  98 |      * A precise street address.
  99 |      */
 100 |     const TYPE_STREET_ADDRESS = "street_address";
 101 | 
 102 |     /**
 103 |      * A named route (such as "US 101").
 104 |      */
 105 |     const TYPE_ROUTE = "route";
 106 | 
 107 |     /**
 108 |      * A major intersection, usually of two major roads.
 109 |      */
 110 |     const TYPE_INTERSECTION = "intersection";
 111 | 
 112 |     /**
 113 |      * A political entity, usually of some civil administration.
 114 |      */
 115 |     const TYPE_POLITICAL = "political";
 116 | 
 117 |     /**
 118 |      * A national political entity (country). The highest order type returned.
 119 |      */
 120 |     const TYPE_COUNTRY = "country";
 121 | 
 122 |     /**
 123 |      * A first-order civil entity below country (states within the US).
 124 |      */
 125 |     const TYPE_ADMIN_AREA_1 = "administrative_area_level_1";
 126 | 
 127 |     /**
 128 |      * A second-order civil entity below country (counties within the US).
 129 |      */
 130 |     const TYPE_ADMIN_AREA_2 = "administrative_area_level_2";
 131 | 
 132 |     /**
 133 |      * A third-order civil entity below country.
 134 |      */
 135 |     const TYPE_ADMIN_AREA_3 = "administrative_area_level_3";
 136 | 
 137 |     /**
 138 |      * A fourth-order civil entity below country.
 139 |      */
 140 |     const TYPE_ADMIN_AREA_4 = "administrative_area_level_4";
 141 | 
 142 |     /**
 143 |      * A fifth-order civil entity below country.
 144 |      */
 145 |     const TYPE_ADMIN_AREA_5 = "administrative_area_level_5";
 146 | 
 147 |     /**
 148 |      * A commonly-used alternative name for the entity.
 149 |      */
 150 |     const TYPE_COLLOQUIAL_AREA = "colloquial_area";
 151 | 
 152 |     /**
 153 |      * An incorporated city or town.
 154 |      */
 155 |     const TYPE_LOCALITY = "locality";
 156 | 
 157 |     /**
 158 |      * A specific type of Japanese locality.
 159 |      */
 160 |     const TYPE_WARD = "ward";
 161 | 
 162 |     /**
 163 |      * A first-order civil entity below a locality.
 164 |      */
 165 |     const TYPE_SUB_LOCALITY = "sublocality";
 166 | 
 167 |     /**
 168 |      * A named neighborhood.
 169 |      */
 170 |     const TYPE_NEIGHBORHOOD = "neighborhood";
 171 | 
 172 |     /**
 173 |      * A named location, usually a building or collection of buildings.
 174 |      */
 175 |     const TYPE_PREMISE = "premise";
 176 | 
 177 |     /**
 178 |      * A first-order entity below a named location, usually a single building
 179 |      * within a collection of building with a common name.
 180 |      */
 181 |     const TYPE_SUB_PREMISE = "subpremise";
 182 | 
 183 |     /**
 184 |      * A postal code as used to address mail within the country.
 185 |      */
 186 |     const TYPE_POSTAL_CODE = "postal_code";
 187 | 
 188 |     /**
 189 |      * A prominent natural feature.
 190 |      */
 191 |     const TYPE_NATURAL_FEATURE = "natural_feature";
 192 | 
 193 |     /**
 194 |      * An airport.
 195 |      */
 196 |     const TYPE_AIRPORT = "airport";
 197 | 
 198 |     /**
 199 |      * A named park.
 200 |      */
 201 |     const TYPE_PARK = "park";
 202 | 
 203 |     /**
 204 |      * A named point of interest that doesn't fit within another category.
 205 |      */
 206 |     const TYPE_POINT_OF_INTEREST = "point_of_interest";
 207 | 
 208 |     /**
 209 |      * A floor of a building address.
 210 |      */
 211 |     const TYPE_FLOOR = "floor";
 212 | 
 213 |     /**
 214 |      * A place that has not yet been categorized.
 215 |      */
 216 |     const TYPE_ESTABLISHMENT = "establishment";
 217 | 
 218 |     /**
 219 |      * A parking lot or parking structure.
 220 |      */
 221 |     const TYPE_PARKING = "parking";
 222 | 
 223 |     /**
 224 |      * A specific postal box.
 225 |      */
 226 |     const TYPE_POST_BOX = "post_box";
 227 | 
 228 |     /**
 229 |      * A grouping of geographic areas used for mailing addresses in some
 230 |      * countries.
 231 |      */
 232 |     const TYPE_POSTAL_TOWN = "postal_town";
 233 | 
 234 |     /**
 235 |      * A room of a building address.
 236 |      */
 237 |     const TYPE_ROOM = "room";
 238 | 
 239 |     /**
 240 |      * A precise street number.
 241 |      */
 242 |     const TYPE_STREET_NUMBER = "street_number";
 243 | 
 244 |     /**
 245 |      * A bus stop.
 246 |      */
 247 |     const TYPE_BUS_STATION = "bus_station";
 248 | 
 249 |     /**
 250 |      * A train stop.
 251 |      */
 252 |     const TYPE_TRAIN_STATION = "train_station";
 253 | 
 254 |     /**
 255 |      * A public transit stop.
 256 |      */
 257 |     const TYPE_TRANSIT_STATION = "transit_station";
 258 | 
 259 |     /**
 260 |      * Helps calculate a more realistic bounding box by taking into account the
 261 |      * curvature of the earth's surface.
 262 |      */
 263 |     const EQUATOR_LAT_DEGREE_IN_MILES = 69.172;
 264 | 
 265 |     /**
 266 |      * Response format.
 267 |      *
 268 |      * @var string
 269 |      */
 270 |     private $format;
 271 | 
 272 |     /**
 273 |      * Address to geocode.
 274 |      *
 275 |      * @var string
 276 |      */
 277 |     private $address;
 278 | 
 279 |     /**
 280 |      * Latitude to reverse geocode to the closest address.
 281 |      *
 282 |      * @var float|string
 283 |      */
 284 |     private $latitude;
 285 | 
 286 |     /**
 287 |      * Longitude to reverse geocode to the closest address.
 288 |      *
 289 |      * @var float|string
 290 |      */
 291 |     private $longitude;
 292 | 
 293 |     /**
 294 |      * Southwest latitude of the bounding box within which to bias geocode
 295 |      * results.
 296 |      *
 297 |      * @var float|string
 298 |      */
 299 |     private $boundsSouthwestLatitude;
 300 | 
 301 |     /**
 302 |      * Southwest longitude of the bounding box within which to bias geocode
 303 |      * results.
 304 |      *
 305 |      * @var float|string
 306 |      */
 307 |     private $boundsSouthwestLongitude;
 308 | 
 309 |     /**
 310 |      * Northeast latitude of the bounding box within which to bias geocode
 311 |      * results.
 312 |      *
 313 |      * @var float|string
 314 |      */
 315 |     private $boundsNortheastLatitude;
 316 | 
 317 |     /**
 318 |      * Northeast longitude of the bounding box within which to bias geocode
 319 |      * results.
 320 |      *
 321 |      * @var float|string
 322 |      */
 323 |     private $boundsNortheastLongitude;
 324 | 
 325 |     /**
 326 |      * Two-character, top-level domain (ccTLD) within which to bias geocode
 327 |      * results.
 328 |      *
 329 |      * @var string
 330 |      */
 331 |     private $region;
 332 | 
 333 |     /**
 334 |      * Language code in which to return results.
 335 |      *
 336 |      * @var string
 337 |      */
 338 |     private $language;
 339 | 
 340 |     /**
 341 |      * Address type(s) to restrict results to.
 342 |      *
 343 |      * @var array
 344 |      */
 345 |     private $resultType = array();
 346 | 
 347 |     /**
 348 |      * Location type(s) to restrict results to.
 349 |      *
 350 |      * @var array
 351 |      */
 352 |     private $locationType = array();
 353 | 
 354 |     /**
 355 |      * Whether the request is from a device with a location sensor.
 356 |      *
 357 |      * @deprecated 2.3.0 no longer required by the Google Maps API
 358 |      * @var        string
 359 |      */
 360 |     private $sensor;
 361 | 
 362 |     /**
 363 |      * API key to authenticate with.
 364 |      *
 365 |      * @var string
 366 |      */
 367 |     private $apiKey;
 368 | 
 369 |     /**
 370 |      * Client ID for Business clients.
 371 |      *
 372 |      * @var string
 373 |      */
 374 |     private $clientId;
 375 | 
 376 |     /**
 377 |      * Cryptographic signing key for Business clients.
 378 |      *
 379 |      * @var string
 380 |      */
 381 |     private $signingKey;
 382 | 
 383 |     /**
 384 |      * Constructor. The request is not executed until `geocode()` is called.
 385 |      *
 386 |      * @param  string $address optional address to geocode
 387 |      * @param  string $format optional response format (JSON default)
 388 |      * @param  bool|string $sensor deprecated as of v2.3.0
 389 |      * @return GoogleMapsGeocoder
 390 |      */
 391 |     public function __construct($address = null, $format = self::FORMAT_JSON, $sensor = false) {
 392 |       $this->setAddress($address)
 393 |            ->setFormat($format)
 394 |            ->setSensor($sensor);
 395 |     }
 396 | 
 397 |     /**
 398 |      * Set the response format.
 399 |      *
 400 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#GeocodingResponses
 401 |      * @param  string $format response format
 402 |      * @return GoogleMapsGeocoder
 403 |      */
 404 |     public function setFormat($format) {
 405 |       $this->format = $format;
 406 | 
 407 |       return $this;
 408 |     }
 409 | 
 410 |     /**
 411 |      * Get the response format.
 412 |      *
 413 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#GeocodingResponses
 414 |      * @return string response format
 415 |      */
 416 |     public function getFormat() {
 417 |       return $this->format;
 418 |     }
 419 | 
 420 |     /**
 421 |      * Whether the response format is JSON.
 422 |      *
 423 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#JSON
 424 |      * @return bool whether JSON
 425 |      */
 426 |     public function isFormatJson() {
 427 |       return $this->getFormat() == self::FORMAT_JSON;
 428 |     }
 429 | 
 430 |     /**
 431 |      * Whether the response format is XML.
 432 |      *
 433 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#XML
 434 |      * @return bool whether XML
 435 |      */
 436 |     public function isFormatXml() {
 437 |       return $this->getFormat() == self::FORMAT_XML;
 438 |     }
 439 | 
 440 |     /**
 441 |      * Set the address to geocode.
 442 |      *
 443 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#geocoding
 444 |      * @param  string $address address to geocode
 445 |      * @return GoogleMapsGeocoder
 446 |      */
 447 |     public function setAddress($address) {
 448 |       $this->address = $address;
 449 | 
 450 |       return $this;
 451 |     }
 452 | 
 453 |     /**
 454 |      * Get the address to geocode.
 455 |      *
 456 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#geocoding
 457 |      * @return string
 458 |      */
 459 |     public function getAddress() {
 460 |       return $this->address;
 461 |     }
 462 | 
 463 |     /**
 464 |      * Set the latitude/longitude to reverse geocode to the closest address.
 465 |      *
 466 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#ReverseGeocoding
 467 |      * @param  float|string $latitude latitude to reverse geocode
 468 |      * @param  float|string $longitude longitude to reverse geocode
 469 |      * @return GoogleMapsGeocoder
 470 |      */
 471 |     public function setLatitudeLongitude($latitude, $longitude) {
 472 |       $this->setLatitude($latitude)
 473 |            ->setLongitude($longitude);
 474 | 
 475 |       return $this;
 476 |     }
 477 | 
 478 |     /**
 479 |      * Get the latitude/longitude to reverse geocode to the closest address
 480 |      * in comma-separated format.
 481 |      *
 482 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#ReverseGeocoding
 483 |      * @return string|false comma-separated coordinates, or false if not set
 484 |      */
 485 |     public function getLatitudeLongitude() {
 486 |       $latitude = $this->getLatitude();
 487 |       $longitude = $this->getLongitude();
 488 | 
 489 |       if ($latitude && $longitude) {
 490 |         return $latitude . "," . $longitude;
 491 |       }
 492 |       else {
 493 |         return false;
 494 |       }
 495 |     }
 496 | 
 497 |     /**
 498 |      * Set the latitude to reverse geocode to the closest address.
 499 |      *
 500 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#ReverseGeocoding
 501 |      * @param  float|string $latitude latitude to reverse geocode
 502 |      * @return GoogleMapsGeocoder
 503 |      */
 504 |     public function setLatitude($latitude) {
 505 |       $this->latitude = $latitude;
 506 | 
 507 |       return $this;
 508 |     }
 509 | 
 510 |     /**
 511 |      * Get the latitude to reverse geocode to the closest address.
 512 |      *
 513 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#ReverseGeocoding
 514 |      * @return float|string latitude to reverse geocode
 515 |      */
 516 |     public function getLatitude() {
 517 |       return $this->latitude;
 518 |     }
 519 | 
 520 |     /**
 521 |      * Set the longitude to reverse geocode to the closest address.
 522 |      *
 523 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#ReverseGeocoding
 524 |      * @param  float|string $longitude longitude to reverse geocode
 525 |      * @return GoogleMapsGeocoder
 526 |      */
 527 |     public function setLongitude($longitude) {
 528 |       $this->longitude = $longitude;
 529 | 
 530 |       return $this;
 531 |     }
 532 | 
 533 |     /**
 534 |      * Get the longitude to reverse geocode to the closest address.
 535 |      *
 536 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#ReverseGeocoding
 537 |      * @return float|string longitude to reverse geocode
 538 |      */
 539 |     public function getLongitude() {
 540 |       return $this->longitude;
 541 |     }
 542 | 
 543 |     /**
 544 |      * Set the bounding box coordinates within which to bias geocode results.
 545 |      *
 546 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 547 |      * @param  float|string $southwestLatitude southwest latitude boundary
 548 |      * @param  float|string $southwestLongitude southwest longitude boundary
 549 |      * @param  float|string $northeastLatitude northeast latitude boundary
 550 |      * @param  float|string $northeastLongitude northeast longitude boundary
 551 |      * @return GoogleMapsGeocoder
 552 |      */
 553 |     public function setBounds($southwestLatitude, $southwestLongitude, $northeastLatitude, $northeastLongitude) {
 554 |       $this->setBoundsSouthwest($southwestLatitude, $southwestLongitude)
 555 |            ->setBoundsNortheast($northeastLatitude, $northeastLongitude);
 556 | 
 557 |       return $this;
 558 |     }
 559 | 
 560 |     /**
 561 |      * Get the bounding box coordinates within which to bias geocode results
 562 |      * in comma-separated, pipe-delimited format.
 563 |      *
 564 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 565 |      * @return string|false comma-separated, pipe-delimited coordinates, or
 566 |      *                      false if not set
 567 |      */
 568 |     public function getBounds() {
 569 |       $southwest = $this->getBoundsSouthwest();
 570 |       $northeast = $this->getBoundsNortheast();
 571 | 
 572 |       if ($southwest && $northeast) {
 573 |         return $southwest . "|" . $northeast;
 574 |       }
 575 |       else {
 576 |         return false;
 577 |       }
 578 |     }
 579 | 
 580 |     /**
 581 |      * Set the southwest coordinates of the bounding box within which to bias
 582 |      * geocode results.
 583 |      *
 584 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 585 |      * @param  float|string $latitude southwest latitude boundary
 586 |      * @param  float|string $longitude southwest longitude boundary
 587 |      * @return GoogleMapsGeocoder
 588 |      */
 589 |     public function setBoundsSouthwest($latitude, $longitude) {
 590 |       $this->boundsSouthwestLatitude = $latitude;
 591 |       $this->boundsSouthwestLongitude = $longitude;
 592 | 
 593 |       return $this;
 594 |     }
 595 | 
 596 |     /**
 597 |      * Get the southwest coordinates of the bounding box within which to bias
 598 |      * geocode results in comma-separated format.
 599 |      *
 600 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 601 |      * @return string|false comma-separated coordinates, or false if not set
 602 |      */
 603 |     public function getBoundsSouthwest() {
 604 |       $latitude = $this->getBoundsSouthwestLatitude();
 605 |       $longitude = $this->getBoundsSouthwestLongitude();
 606 | 
 607 |       if ($latitude && $longitude) {
 608 |         return $latitude . "," . $longitude;
 609 |       }
 610 |       else {
 611 |         return false;
 612 |       }
 613 |     }
 614 | 
 615 |     /**
 616 |      * Get the southwest latitude of the bounding box within which to bias
 617 |      * geocode results.
 618 |      *
 619 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 620 |      * @return float|string southwest latitude boundary
 621 |      */
 622 |     public function getBoundsSouthwestLatitude() {
 623 |       return $this->boundsSouthwestLatitude;
 624 |     }
 625 | 
 626 |     /**
 627 |      * Get the southwest longitude of the bounding box within which to bias
 628 |      * geocode results.
 629 |      *
 630 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 631 |      * @return float|string southwest longitude boundary
 632 |      */
 633 |     public function getBoundsSouthwestLongitude() {
 634 |       return $this->boundsSouthwestLongitude;
 635 |     }
 636 | 
 637 |     /**
 638 |      * Set the northeast coordinates of the bounding box within which to bias
 639 |      * geocode results.
 640 |      *
 641 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 642 |      * @param  float|string $latitude northeast latitude boundary
 643 |      * @param  float|string $longitude northeast longitude boundary
 644 |      * @return GoogleMapsGeocoder
 645 |      */
 646 |     public function setBoundsNortheast($latitude, $longitude) {
 647 |       $this->boundsNortheastLatitude = $latitude;
 648 |       $this->boundsNortheastLongitude = $longitude;
 649 | 
 650 |       return $this;
 651 |     }
 652 | 
 653 |     /**
 654 |      * Get the northeast coordinates of the bounding box within which to bias
 655 |      * geocode results in comma-separated format.
 656 |      *
 657 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 658 |      * @return string|false comma-separated coordinates, or false if not set
 659 |      */
 660 |     public function getBoundsNortheast() {
 661 |       $latitude = $this->getBoundsNortheastLatitude();
 662 |       $longitude = $this->getBoundsNortheastLongitude();
 663 | 
 664 |       if ($latitude && $longitude) {
 665 |         return $latitude . "," . $longitude;
 666 |       }
 667 |       else {
 668 |         return false;
 669 |       }
 670 |     }
 671 | 
 672 |     /**
 673 |      * Get the northeast latitude of the bounding box within which to bias
 674 |      * geocode results.
 675 |      *
 676 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 677 |      * @return float|string northeast latitude boundary
 678 |      */
 679 |     public function getBoundsNortheastLatitude() {
 680 |       return $this->boundsNortheastLatitude;
 681 |     }
 682 | 
 683 |     /**
 684 |      * Get the northeast longitude of the bounding box within which to bias
 685 |      * geocode results.
 686 |      *
 687 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#Viewports
 688 |      * @return float|string northeast longitude boundary
 689 |      */
 690 |     public function getBoundsNortheastLongitude() {
 691 |       return $this->boundsNortheastLongitude;
 692 |     }
 693 | 
 694 |     /**
 695 |      * Set the two-character, top-level domain (ccTLD) within which to bias
 696 |      * geocode results.
 697 |      *
 698 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#RegionCodes
 699 |      * @param  string $region two-character, top-level domain (ccTLD)
 700 |      * @return GoogleMapsGeocoder
 701 |      */
 702 |     public function setRegion($region) {
 703 |       $this->region = $region;
 704 | 
 705 |       return $this;
 706 |     }
 707 | 
 708 |     /**
 709 |      * Get the two-character, top-level domain (ccTLD) within which to bias
 710 |      * geocode results.
 711 |      *
 712 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#RegionCodes
 713 |      * @return string two-character, top-level domain (ccTLD)
 714 |      */
 715 |     public function getRegion() {
 716 |       return $this->region;
 717 |     }
 718 | 
 719 |     /**
 720 |      * Set the language code in which to return results.
 721 |      *
 722 |      * @link   https://developers.google.com/maps/faq#languagesupport
 723 |      * @param  string $language language code
 724 |      * @return GoogleMapsGeocoder
 725 |      */
 726 |     public function setLanguage($language) {
 727 |       $this->language = $language;
 728 | 
 729 |       return $this;
 730 |     }
 731 | 
 732 |     /**
 733 |      * Get the language code in which to return results.
 734 |      *
 735 |      * @link   https://developers.google.com/maps/faq#languagesupport
 736 |      * @return string language code
 737 |      */
 738 |     public function getLanguage() {
 739 |       return $this->language;
 740 |     }
 741 | 
 742 |     /**
 743 |      * Set the address type(s) to restrict results to.
 744 |      *
 745 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#reverse-restricted
 746 |      * @param  string|array $resultType address type(s)
 747 |      * @return GoogleMapsGeocoder
 748 |      */
 749 |     public function setResultType($resultType) {
 750 |       $this->resultType = is_array($resultType) ? $resultType : array($resultType);
 751 | 
 752 |       return $this;
 753 |     }
 754 | 
 755 |     /**
 756 |      * Get the address type(s) to restrict results to.
 757 |      *
 758 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#reverse-restricted
 759 |      * @return array address type(s)
 760 |      */
 761 |     public function getResultType() {
 762 |       return $this->resultType;
 763 |     }
 764 | 
 765 |     /**
 766 |      * Get the address type(s) to restrict results to separated by a pipe (|).
 767 |      *
 768 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#reverse-restricted
 769 |      * @return string address type(s) separated by a pipe (|)
 770 |      */
 771 |     public function getResultTypeFormatted() {
 772 |       return implode('|', $this->getResultType());
 773 |     }
 774 | 
 775 |     /**
 776 |      * Set the location type(s) to restrict results to.
 777 |      *
 778 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#reverse-restricted
 779 |      * @param  string|array $locationType location type(s)
 780 |      * @return GoogleMapsGeocoder
 781 |      */
 782 |     public function setLocationType($locationType) {
 783 |       $this->locationType = is_array($locationType) ? $locationType : array($locationType);
 784 | 
 785 |       return $this;
 786 |     }
 787 | 
 788 |     /**
 789 |      * Get the location type(s) to restrict results to.
 790 |      *
 791 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#reverse-restricted
 792 |      * @return array location type(s)
 793 |      */
 794 |     public function getLocationType() {
 795 |       return $this->locationType;
 796 |     }
 797 | 
 798 |     /**
 799 |      * Get the location type(s) to restrict results to separated by a pipe (|).
 800 |      *
 801 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#reverse-restricted
 802 |      * @return string location type(s) separated by a pipe (|)
 803 |      */
 804 |     public function getLocationTypeFormatted() {
 805 |       return implode('|', $this->getLocationType());
 806 |     }
 807 | 
 808 |     /**
 809 |      * Set whether the request is from a device with a location sensor.
 810 |      *
 811 |      * @deprecated 2.3.0 no longer required by the Google Maps API
 812 |      * @link       https://developers.google.com/maps/documentation/geocoding/intro#Sensor
 813 |      * @param      bool|string $sensor boolean or 'true'/'false' string
 814 |      * @return     GoogleMapsGeocoder
 815 |      */
 816 |     public function setSensor($sensor) {
 817 |       if ($sensor == 'true' || $sensor == 'false') {
 818 |         $this->sensor = $sensor;
 819 |       }
 820 |       elseif ($sensor) {
 821 |         $this->sensor = "true";
 822 |       }
 823 |       else {
 824 |         $this->sensor = "false";
 825 |       }
 826 | 
 827 |       return $this;
 828 |     }
 829 | 
 830 |     /**
 831 |      * Get whether the request is from a device with a location sensor.
 832 |      *
 833 |      * @deprecated 2.3.0 no longer required by the Google Maps API
 834 |      * @link       https://developers.google.com/maps/documentation/geocoding/intro#Sensor
 835 |      * @return     string 'true' or 'false'
 836 |      */
 837 |     public function getSensor() {
 838 |       return $this->sensor;
 839 |     }
 840 | 
 841 |     /**
 842 |      * Set the API key to authenticate with.
 843 |      *
 844 |      * @link   https://developers.google.com/console/help/new/#UsingKeys
 845 |      * @param  string $apiKey API key
 846 |      * @return GoogleMapsGeocoder
 847 |      */
 848 |     public function setApiKey($apiKey) {
 849 |       $this->apiKey = $apiKey;
 850 | 
 851 |       return $this;
 852 |     }
 853 | 
 854 |     /**
 855 |      * Get the API key to authenticate with.
 856 |      *
 857 |      * @link   https://developers.google.com/console/help/new/#UsingKeys
 858 |      * @return string API key
 859 |      */
 860 |     public function getApiKey() {
 861 |       return $this->apiKey;
 862 |     }
 863 |     /**
 864 |      * Set the client ID for Business clients.
 865 |      *
 866 |      * @link   https://developers.google.com/maps/documentation/business/webservices/#client_id
 867 |      * @param  string $clientId client ID
 868 |      * @return GoogleMapsGeocoder
 869 |      */
 870 |     public function setClientId($clientId) {
 871 |       $this->clientId = $clientId;
 872 | 
 873 |       return $this;
 874 |     }
 875 | 
 876 |     /**
 877 |      * Get the client ID for Business clients.
 878 |      *
 879 |      * @link   https://developers.google.com/maps/documentation/business/webservices/#client_id
 880 |      * @return string client ID
 881 |      */
 882 |     public function getClientId() {
 883 |       return $this->clientId;
 884 |     }
 885 | 
 886 |     /**
 887 |      * Set the cryptographic signing key for Business clients.
 888 |      *
 889 |      * @link   https://developers.google.com/maps/documentation/business/webservices/#cryptographic_signing_key
 890 |      * @param  string $signingKey cryptographic signing key
 891 |      * @return GoogleMapsGeocoder
 892 |      */
 893 |     public function setSigningKey($signingKey) {
 894 |       $this->signingKey = $signingKey;
 895 | 
 896 |       return $this;
 897 |     }
 898 | 
 899 |     /**
 900 |      * Get the cryptographic signing key for Business clients.
 901 |      *
 902 |      * @link   https://developers.google.com/maps/documentation/business/webservices/#cryptographic_signing_key
 903 |      * @return string cryptographic signing key
 904 |      */
 905 |     public function getSigningKey() {
 906 |       return $this->signingKey;
 907 |     }
 908 | 
 909 |     /**
 910 |      * Whether the request is for a Business client.
 911 |      *
 912 |      * @return bool whether the request is for a Business client
 913 |      */
 914 |     public function isBusinessClient() {
 915 |       return $this->getClientId() && $this->getSigningKey();
 916 |     }
 917 | 
 918 |     /**
 919 |      * Generate the signature for a Business client geocode request.
 920 |      *
 921 |      * @link   https://developers.google.com/maps/documentation/business/webservices/auth#digital_signatures
 922 |      * @param  string $pathQueryString path and query string of the request
 923 |      * @return string Base64 encoded signature that's URL safe
 924 |      */
 925 |     private function generateSignature($pathQueryString) {
 926 |       $decodedSigningKey = self::base64DecodeUrlSafe($this->getSigningKey());
 927 | 
 928 |       $signature = hash_hmac('sha1', $pathQueryString, $decodedSigningKey, true);
 929 |       $signature = self::base64EncodeUrlSafe($signature);
 930 | 
 931 |       return $signature;
 932 |     }
 933 | 
 934 |     /**
 935 |      * Build the query string with all set parameters of the geocode request.
 936 |      *
 937 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#GeocodingRequests
 938 |      * @return string encoded query string of the geocode request
 939 |      */
 940 |     private function geocodeQueryString() {
 941 |       $queryString = array();
 942 | 
 943 |       // One of the following is required.
 944 |       $address = $this->getAddress();
 945 |       $latitudeLongitude = $this->getLatitudeLongitude();
 946 | 
 947 |       // If both are set for some reason, favor address to geocode.
 948 |       if ($address) {
 949 |         $queryString['address'] = $address;
 950 |       }
 951 |       elseif ($latitudeLongitude) {
 952 |         $queryString['latlng'] = $latitudeLongitude;
 953 |       }
 954 | 
 955 |       // Optional parameters.
 956 |       $queryString['bounds'] = $this->getBounds();
 957 |       $queryString['region'] = $this->getRegion();
 958 |       $queryString['language'] = $this->getLanguage();
 959 |       $queryString['result_type'] = $this->getResultTypeFormatted();
 960 |       $queryString['location_type'] = $this->getLocationTypeFormatted();
 961 | 
 962 |       // Required.
 963 |       $queryString['sensor'] = $this->getSensor();
 964 | 
 965 |       // Remove any unset parameters.
 966 |       $queryString = array_filter($queryString);
 967 | 
 968 |       // The signature is added later using the path + query string.
 969 |       if ($this->isBusinessClient()) {
 970 |         $queryString['client'] = $this->getClientId();
 971 |       }
 972 |       elseif ($this->getApiKey()) {
 973 |         $queryString['key'] = $this->getApiKey();
 974 |       }
 975 | 
 976 |       // Convert array to proper query string.
 977 |       return http_build_query($queryString);
 978 |     }
 979 | 
 980 |     /**
 981 |      * Build the URL (with query string) of the geocode request.
 982 |      *
 983 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#GeocodingRequests
 984 |      * @param  bool $https whether to make the request over HTTPS
 985 |      * @return string URL of the geocode request
 986 |      */
 987 |     private function geocodeUrl($https = false) {
 988 |       // HTTPS is required if an API key is set.
 989 |       if ($https || $this->getApiKey()) {
 990 |         $scheme = "https";
 991 |       }
 992 |       else {
 993 |         $scheme = "http";
 994 |       }
 995 | 
 996 |       $pathQueryString = self::URL_PATH . $this->getFormat() . "?" . $this->geocodeQueryString();
 997 | 
 998 |       if ($this->isBusinessClient()) {
 999 |         $pathQueryString .= "&signature=" . $this->generateSignature($pathQueryString);
1000 |       }
1001 | 
1002 |       return $scheme . "://" . self::URL_DOMAIN . $pathQueryString;
1003 |     }
1004 | 
1005 |     /**
1006 |      * Execute the geocoding request. The return type is based on the requested
1007 |      * format: associative array if JSON, SimpleXMLElement object if XML.
1008 |      *
1009 |      * @link   https://developers.google.com/maps/documentation/geocoding/intro#GeocodingResponses
1010 |      * @param  bool $https whether to make the request over HTTPS
1011 |      * @param  bool $raw whether to return the raw (string) response
1012 |      * @param  resource $context stream context from `stream_context_create()`
1013 |      * @return string|array|SimpleXMLElement response in requested format
1014 |      */
1015 |     public function geocode($https = false, $raw = false, $context = null) {
1016 |       $response = file_get_contents($this->geocodeUrl($https), false, $context);
1017 | 
1018 |       if ($raw) {
1019 |         return $response;
1020 |       }
1021 |       elseif ($this->isFormatJson()) {
1022 |         return json_decode($response, true);
1023 |       }
1024 |       elseif ($this->isFormatXml()) {
1025 |         return new SimpleXMLElement($response);
1026 |       }
1027 |       else {
1028 |         return $response;
1029 |       }
1030 |     }
1031 | 
1032 |     /**
1033 |      * Computes a four point bounding box around the specified location. This
1034 |      * can then be used to find all locations within an X-mile range of a central
1035 |      * location. A bounding box is much easier and faster to compute than a
1036 |      * bounding radius.
1037 |      *
1038 |      * The returned array contains two keys: 'lat' and 'lon'. Each of these
1039 |      * contains another array with two keys: 'max' and 'min'. Four points are
1040 |      * returned in total.
1041 |      *
1042 |      * @param  float|string $latitude to draw the bounding box around
1043 |      * @param  float|string $longitude to draw the bounding box around
1044 |      * @param  int|float|string $mileRange mile range around point
1045 |      * @return array 'lat' and 'lon' 'min' and 'max' points
1046 |      */
1047 |     public static function boundingBox($latitude, $longitude, $mileRange) {
1048 |       $maxLatitude = $latitude + $mileRange / self::EQUATOR_LAT_DEGREE_IN_MILES;
1049 |       $minLatitude = $latitude - ($maxLatitude - $latitude);
1050 | 
1051 |       $maxLongitude = $longitude + $mileRange / (cos($minLatitude * M_PI / 180) * self::EQUATOR_LAT_DEGREE_IN_MILES);
1052 |       $minLongitude = $longitude - ($maxLongitude - $longitude);
1053 | 
1054 |       return array('lat' => array('max' => $maxLatitude,
1055 |                                   'min' => $minLatitude),
1056 |                    'lon' => array('max' => $maxLongitude,
1057 |                                   'min' => $minLongitude));
1058 |     }
1059 | 
1060 |     /**
1061 |      * Encode a string with Base64 using only URL safe characters.
1062 |      *
1063 |      * @param  string $value value to encode
1064 |      * @return string encoded value
1065 |      */
1066 |     private static function base64EncodeUrlSafe($value) {
1067 |       return strtr(base64_encode($value), '+/', '-_');
1068 |     }
1069 | 
1070 |     /**
1071 |      * Decode a Base64 string that uses only URL safe characters.
1072 |      *
1073 |      * @param  string $value value to decode
1074 |      * @return string decoded value
1075 |      */
1076 |     private static function base64DecodeUrlSafe($value) {
1077 |       return base64_decode(strtr($value, '-_', '+/'));
1078 |     }
1079 | 
1080 |   }
1081 | 
1082 | ?>
1083 | 


--------------------------------------------------------------------------------