Merge pull request #2 from Muffinman/feature/geocoding

Adding UK Specific Geocoding APIs

Author: baikho

README.md

@@ -45,7 +45,13 @@ $result = (new \Baikho\Loqate\Address\Retrieve('API Key'))
 
 ### Geocoding API
 
-Currently only [Distance](https://www.loqate.com/resources/support/apis/DistancesAndDirections/Interactive/Distance/1/) and [Directions](https://www.loqate.com/resources/support/apis/DistancesAndDirections/Interactive/Directions/2/) APIs are supported.
+The only APIs currently supported are
+
+- [Distance](https://www.loqate.com/resources/support/apis/DistancesAndDirections/Interactive/Distance/1/)
+- [Directions](https://www.loqate.com/resources/support/apis/DistancesAndDirections/Interactive/Directions/2/)
+- [UK Find](https://www.loqate.com/resources/support/apis/Geocoding/UK/Find/2/)
+- [UK Geocode](https://www.loqate.com/resources/support/apis/Geocoding/UK/Geocode/2.1/)
+- [UK Retrieve](https://www.loqate.com/resources/support/apis/Geocoding/UK/Retrieve/2/)
 
 #### Calculate distance between two points.
 
@@ -67,6 +73,37 @@ $result = $loqate->geocoding()->directions('51.4733514399,-0.00088499646', '51.4
 $result = $loqate->geocoding()->directions('SE10 8XJ', 'SW1A 0AA');
 ```
 
+#### Find a UK Place or Location
+
+This can be a full or partial postcode, a place name or street comma town.
+
+```php
+$result = $loqate->geocoding()->ukFind('London');
+```
+
+#### Geocode a UK Place or Location
+
+This can be a full or partial postcode, a place name or street comma town.
+
+```php
+$result = $loqate->geocoding()->ukGeocode('London');
+```
+
+#### Retrieve a UK Place or Location
+
+This can be a full or partial postcode, a place name or street comma town.
+
+```php
+$result = $loqate->geocoding()->ukRetrieve('XX|XX|XXX|XXXXXXXXXX');
+```
+#### Reverse Geocode a position to Address or Location
+
+Returns the nearest address or location to the given coordinates. A postcode or coordinates (latitude, longitude or easting, nothing) of the centre of the search.
+
+```php
+$result = $loqate->geocoding()->ukReverseGeocode('51.4733514399,-0.00088499646');
+```
+
 ### Email Verification API
 
 #### Validate Email Address:

src/Geocoding/GeocodingHandler.php

@@ -50,4 +50,52 @@ public function distance(string $start, string $finish)
     {
         return (new InteractiveDistance($this->key, $start, $finish))->makeRequest();
     }
+
+    /**
+     * UK Find v2
+     *
+     * @param string $location
+     * @return mixed
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function ukFind(string $location)
+    {
+        return (new UKFind($this->key, $location))->makeRequest();
+    }
+
+    /**
+     * UK Geocode v2.1
+     *
+     * @param string $location
+     * @return mixed
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function ukGeocode(string $location)
+    {
+        return (new UKGeocode($this->key, $location))->makeRequest();
+    }
+
+    /**
+     * UK Retrieve v2
+     *
+     * @param string $id
+     * @return mixed
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function ukRetrieve(string $id)
+    {
+        return (new UKRetrieve($this->key, $id))->makeRequest();
+    }
+
+    /**
+     * UK Reverse Geocode v1.1
+     *
+     * @param string $centrePoint
+     * @return mixed
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function ukReverseGeocode(string $centrePoint)
+    {
+        return (new UKGeocode($this->key, $centrePoint))->makeRequest();
+    }
 }

src/Geocoding/UKFind.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Baikho\Loqate\Geocoding;
+
+use Baikho\Loqate\BaseClient;
+
+/**
+ * Class UK Find v2.
+ *
+ * @package Baikho\Loqate\Geocoding
+ * @see https://www.loqate.com/resources/support/apis/Geocoding/UK/Find/2/
+ */
+class UKFind extends BaseClient
+{
+
+    /**
+     * The location to geocode. This can be a full or partial postcode, a place name or street comma town.
+     *
+     * @var string|null
+     */
+    protected ?string $location;
+
+    /**
+     * Find constructor.
+     *
+     * @param string $key
+     * @param string|null $location
+     */
+    public function __construct(string $key, string $location = null)
+    {
+        parent::__construct($key);
+        $this->location = $location;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getUri(): string
+    {
+        return 'Geocoding/UK/Find/v2/';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setParams(array $parameters): self
+    {
+        $this->location = $parameters['location'] ?? null;
+        return $this;
+    }
+
+    /**
+     * Sets the location.
+     *
+     * @param string $location
+     * @return UKFind
+     */
+    public function setLocation(string $location): UKFind
+    {
+        $this->location = $location;
+        return $this;
+    }
+}

src/Geocoding/UKGeocode.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Baikho\Loqate\Geocoding;
+
+use Baikho\Loqate\BaseClient;
+
+/**
+ * Class UK Geocode v2.1.
+ *
+ * @package Baikho\Loqate\Geocoding
+ * @see https://www.loqate.com/resources/support/apis/Geocoding/UK/Geocode/2.1/
+ */
+class UKGeocode extends BaseClient
+{
+
+    /**
+     * The location to geocode. This can be a full or partial postcode, a place name, street comma town, address (comma separated lines) or an ID from PostcodeAnywhere/Find web services.
+     *
+     * @var string|null
+     */
+    protected ?string $location;
+
+    /**
+     * Find constructor.
+     *
+     * @param string $key
+     * @param string|null $location
+     */
+    public function __construct(string $key, string $location = null)
+    {
+        parent::__construct($key);
+        $this->location = $location;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getUri(): string
+    {
+        return 'Geocoding/UK/Geocode/v2.1/';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setParams(array $parameters): self
+    {
+        $this->location = $parameters['location'] ?? null;
+        return $this;
+    }
+
+    /**
+     * Sets the location.
+     *
+     * @param string $location
+     * @return UKGeocode
+     */
+    public function setLocation(string $location): UKGeocode
+    {
+        $this->location = $location;
+        return $this;
+    }
+}

src/Geocoding/UKRetrieve.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Baikho\Loqate\Geocoding;
+
+use Baikho\Loqate\BaseClient;
+
+/**
+ * Class UK Retrieve v2.
+ *
+ * @package Baikho\Loqate\Geocoding
+ * @see https://www.loqate.com/resources/support/apis/Geocoding/UK/Retrieve/2/
+ */
+class UKRetrieve extends BaseClient
+{
+
+    /**
+     * The location ID to retrieve the coordinates for.
+     *
+     * @var string|null
+     */
+    protected ?string $id;
+
+    /**
+     * Find constructor.
+     *
+     * @param string $key
+     * @param string|null $id
+     */
+    public function __construct(string $key, string $id = null)
+    {
+        parent::__construct($key);
+        $this->id = $id;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getUri(): string
+    {
+        return 'Geocoding/UK/Retrieve/v2/';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setParams(array $parameters): self
+    {
+        $this->id = $parameters['id'] ?? null;
+        return $this;
+    }
+
+    /**
+     * Sets the location ID.
+     *
+     * @param string $id
+     * @return UKRetrieve
+     */
+    public function setId(string $id): UKRetrieve
+    {
+        $this->id = $id;
+        return $this;
+    }
+}

src/Geocoding/UKReverseGeocode.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Baikho\Loqate\Geocoding;
+
+use Baikho\Loqate\BaseClient;
+
+/**
+ * Class UK Reverse Geocode v1.1.
+ *
+ * @package Baikho\Loqate\Geocoding
+ * @see https://www.loqate.com/resources/support/apis/Geocoding/UK/ReverseGeocode/1.1/
+ */
+class UKReverseGeocode extends BaseClient
+{
+
+    /**
+     * A postcode or coordinates (latitude, longitude or easting, nothing) of the centre of the search.
+     *
+     * @var string|null
+     */
+    protected ?string $centrePoint;
+
+    /**
+     * Find constructor.
+     *
+     * @param string $key
+     * @param string|null $centrePoint
+     */
+    public function __construct(string $key, string $centrePoint = null)
+    {
+        parent::__construct($key);
+        $this->centrePoint = $centrePoint;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getUri(): string
+    {
+        return 'Geocoding/UK/ReverseGeocode/v1.1/';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setParams(array $parameters): self
+    {
+        $this->centrePoint = $parameters['centrePoint'] ?? null;
+        return $this;
+    }
+
+    /**
+     * Sets the location.
+     *
+     * @param string $centrePoint
+     * @return UKReverseGeocode
+     */
+    public function setCentrePoint(string $centrePoint): UKReverseGeocode
+    {
+        $this->centrePoint = $centrePoint;
+        return $this;
+    }
+}