Merge pull request #58 from smartystreets/eric/enrichment-address-search

Added Address Search Feature for the US Address Enrichment API
smartystreets · Sep 10, 2024 · 042815d · 042815d
2 parents d936041 + 52e2721
commit 042815d
Show file tree

Hide file tree

Showing 7 changed files with 334 additions and 39 deletions.
diff --git a/examples/USEnrichmentExample.php b/examples/USEnrichmentExample.php
@@ -3,10 +3,12 @@
 require_once(dirname(dirname(__FILE__)) . '/src/StaticCredentials.php');
 require_once(dirname(dirname(__FILE__)) . '/src/ClientBuilder.php');
 require_once(dirname(dirname(__FILE__)) . '/src/US_Enrichment/Client.php');
+require_once(dirname(dirname(__FILE__)) . '/src/US_Enrichment/Lookup.php');
 
 use SmartyStreets\PhpSdk\StaticCredentials;
 use SmartyStreets\PhpSdk\ClientBuilder;
 use SmartyStreets\PhpSdk\US_Enrichment\Result;
+use SmartyStreets\PhpSdk\US_Enrichment\Lookup;
 
 $lookupExample = new USEnrichmentExample();
 $lookupExample->run();
@@ -31,10 +33,25 @@ public function run()
         $client = (new ClientBuilder($staticCredentials)) ->withLicenses(["us-property-data-principal-cloud"])
             ->buildUsEnrichmentApiClient();
 
-        $smartyKey = "1682393594";
+        $smartyKey = "325023201";
+
+        $lookup = new Lookup();
+
+        $lookup->setStreet("56 Union Ave");
+        $lookup->setCity("Somerville");
+        $lookup->setState("NJ");
+        $lookup->setZipcode("08876");
+
+        // You can also send an address in freeform by uncommenting the line below
+        // $lookup->setFreeform("56 Union Ave Somerville NJ 08876");
 
         try {
+            // Call the API with only a smarty key using the line below
             $result = $client->sendPropertyPrincipalLookup($smartyKey);
+
+            // Or call the API with an address using the lookup object with the commented line below
+            // $result = $client->sendPropertyPrincipalLookup($lookup);
+
             if ($result != null) {
                 $this->displayResult($result[0]);
             }

diff --git a/src/US_Enrichment/Client.php b/src/US_Enrichment/Client.php
@@ -21,40 +21,106 @@ public function __construct(Sender $sender, Serializer $serializer = null) {
         $this->serializer = $serializer;
     }
 
-    public function sendPropertyFinancialLookup($smartyKey){
-        $lookup = new Lookup($smartyKey, "property", "financial");
-        $this->sendLookup($lookup);
-        return $lookup->getResponse();
+    public function sendPropertyFinancialLookup($financialLookup){
+        if (is_string($financialLookup)) {
+            $lookup = new Lookup($financialLookup, "property", "financial");
+            $this->sendLookup($lookup);
+            return $lookup->getResponse();
+        } 
+        else if (is_object($financialLookup)) {
+            $financialLookup->setDataSetName("property");
+            $financialLookup->setDataSubSetName("financial");
+            $this->sendLookup($financialLookup);
+            return $financialLookup->getResponse();
+        }
+        else {
+            return null;
+        }
     }
 
-    public function sendPropertyPrincipalLookup($smartyKey){
-        $lookup = new Lookup($smartyKey, "property", "principal");
-        $this->sendLookup($lookup);
-        return $lookup->getResponse();
+    public function sendPropertyPrincipalLookup($principalLookup){
+        if (is_string($principalLookup)) {
+            $lookup = new Lookup($principalLookup, "property", "principal");
+            $this->sendLookup($lookup);
+            return $lookup->getResponse();
+        }
+        else if (is_object($principalLookup)) {
+            $principalLookup->setDataSetName("property");
+            $principalLookup->setDataSubSetName("principal");
+            $this->sendLookup($principalLookup);
+            return $principalLookup->getResponse();
+        }
+        else {
+            return null;
+        }
     }
 
-    public function sendGeoReferenceLookup($smartyKey){
-        $lookup = new Lookup($smartyKey, "geo-reference", null);
-        $this->sendLookup($lookup);
-        return $lookup->getResponse();
+    public function sendGeoReferenceLookup($geoReferenceLookup){
+        if (is_string($geoReferenceLookup)) {
+            $lookup = new Lookup($geoReferenceLookup, "geo-reference");
+            $this->sendLookup($lookup);
+            return $lookup->getResponse();
+        }
+        else if (is_object($geoReferenceLookup)) {
+            $geoReferenceLookup->setDataSetName("geo-reference");
+            $geoReferenceLookup->setDataSubSetName(null);
+            $this->sendLookup($geoReferenceLookup);
+            return $geoReferenceLookup->getResponse();
+        }
+        else {
+            return null;
+        }
     }
 
-    public function sendSecondaryLookup($smartyKey){
-        $lookup = new Lookup($smartyKey, "secondary", null);
-        $this->sendLookup($lookup);
-        return $lookup->getResponse();
+    public function sendSecondaryLookup($secondaryLookup){
+        if (is_string($secondaryLookup)) {
+            $lookup = new Lookup($secondaryLookup, "secondary");
+            $this->sendLookup($lookup);
+            return $lookup->getResponse();
+        }
+        else if (is_object($secondaryLookup)) {
+            $secondaryLookup->setDataSetName("secondary");
+            $secondaryLookup->setDataSubSetName(null);
+            $this->sendLookup($secondaryLookup);
+            return $secondaryLookup->getResponse();
+        }
+        else {
+            return null;
+        }
     }
 
-    public function sendSecondaryCountLookup($smartyKey){
-        $lookup = new Lookup($smartyKey, "secondary", "count");
-        $this->sendLookup($lookup);
-        return $lookup->getResponse();
+    public function sendSecondaryCountLookup($secondaryCountLookup){
+        if (is_string($secondaryCountLookup)) {
+            $lookup = new Lookup($secondaryCountLookup, "secondary", "count");
+            $this->sendLookup($lookup);
+            return $lookup->getResponse();
+        }
+        else if (is_object($secondaryCountLookup)) {
+            $secondaryCountLookup->setDataSetName("secondary");
+            $secondaryCountLookup->setDataSubSetName("count");
+            $this->sendLookup($secondaryCountLookup);
+            return $secondaryCountLookup->getResponse();
+        }
+        else {
+            return null;
+        }
     }
 
-    public function sendGenericLookup($smartyKey, $dataSetName, $dataSubsetName){
-        $lookup = new Lookup($smartyKey, $dataSetName, $dataSubsetName);
-        $this->sendLookup($lookup);
-        return $lookup->getResponse();
+    public function sendGenericLookup($genericLookup, $dataSetName, $dataSubsetName){
+        if (is_string($genericLookup)) {
+            $lookup = new Lookup($genericLookup, $dataSetName, $dataSubsetName);
+            $this->sendLookup($lookup);
+            return $lookup->getResponse();
+        }
+        else if (is_object($genericLookup)) {
+            $genericLookup->setDataSetName($dataSetName);
+            $genericLookup->setDataSubSetName($dataSubsetName);
+            $this->sendLookup($genericLookup);
+            return $genericLookup->getResponse();
+        }
+        else {
+            return null;
+        }
     }
 
     private function sendLookup(Lookup $lookup) {
@@ -83,13 +149,28 @@ private function buildRequest(Lookup $lookup) {
 
         $request->setUrlComponents($this->getUrlPrefix($lookup));
 
+        if ($lookup->getSmartyKey() == null) {
+            $request->setParameter("freeform", $lookup->getFreeform());
+            $request->setParameter("street", $lookup->getStreet());
+            $request->setParameter("city", $lookup->getCity());
+            $request->setParameter("state", $lookup->getState());
+            $request->setParameter("zipcode", $lookup->getZipcode());
+        }
         return $request;
     }
 
     private function getUrlPrefix($lookup){
-        if ($lookup->getDataSubsetName() == null) {
-            return $lookup->getSmartyKey() . "/" . $lookup->getDataSetName();
+        if ($lookup->getSmartyKey() == null) {
+            if ($lookup->getDataSubsetName() == null) {
+                return "search/" . $lookup->getDataSetName();
+            }
+            return "search/" . $lookup->getDataSetName() . "/" . $lookup->getDataSubsetName();
+        }
+        else {
+            if ($lookup->getDataSubsetName() == null) {
+                return $lookup->getSmartyKey() . "/" . $lookup->getDataSetName();
+            }
+            return $lookup->getSmartyKey() . "/" . $lookup->getDataSetName() . "/" . $lookup->getDataSubsetName();
         }
-        return $lookup->getSmartyKey() . "/" . $lookup->getDataSetName() . "/" . $lookup->getDataSubsetName();
     }
 }
diff --git a/src/US_Enrichment/Lookup.php b/src/US_Enrichment/Lookup.php
@@ -7,24 +7,54 @@ class Lookup {
     //region [ Fields ]
 
     private $smartyKey,
+        $freeform,
+        $street,
+        $city,
+        $state,
+        $zipcode,
         $dataSetName,
         $dataSubsetName,
         $response;
 
     //endregion
 
-    public function __construct($smartyKey, $dataSetName, $dataSubsetName) {
+    public function __construct($smartyKey = null, $dataSetName = null, $dataSubsetName = null, $freeform = null, $street = null, $city = null, $state = null,
+    $zipcode = null) {
         $this->smartyKey = $smartyKey;
         $this->dataSetName = $dataSetName;
         $this->dataSubsetName = $dataSubsetName;
+        $this->freeform = $freeform;
+        $this->street = $street;
+        $this->city = $city;
+        $this->state = $state;
+        $this->zipcode = $zipcode;
         $this->response = null;
-
     }
 
     public function getSmartyKey(){
         return $this->smartyKey;
     }
 
+    public function getFreeform(){
+        return $this->freeform;
+    }
+
+    public function getStreet(){
+        return $this->street;
+    }
+
+    public function getCity(){
+        return $this->city;
+    }
+
+    public function getState(){
+        return $this->state;
+    }
+
+    public function getZipcode(){
+        return $this->zipcode;
+    }
+
     public function getDataSetName(){
         return $this->dataSetName;
     }
@@ -37,6 +67,38 @@ public function getResponse() {
         return $this->response;
     }
 
+    public function setSmartyKey($smartyKey) {
+        $this->smartyKey = $smartyKey;
+    }
+
+    public function setDataSetName($dataSetName) {
+        $this->dataSetName = $dataSetName;
+    }
+
+    public function setDataSubsetName($dataSubsetName) {
+        $this->dataSubsetName = $dataSubsetName;
+    }
+
+    public function setFreeform($freeform) {
+        $this->freeform = $freeform;
+    }
+
+    public function setStreet($street){
+        $this->street = $street;
+    }
+
+    public function setCity($city){
+        $this->city = $city;
+    }
+
+    public function setState($state){
+        $this->state = $state;
+    }
+
+    public function setZipcode($zipcode){
+        $this->zipcode = $zipcode;
+    }
+
     public function setResponse($response){
         $this->response = $response;
     }

diff --git a/src/US_Enrichment/Result.php b/src/US_Enrichment/Result.php
@@ -64,13 +64,15 @@ private function createAttributes($dataSetName, $dataSubsetName, $attributesObj)
     }
 
     private function createSecondaryData($responseObj, $dataSubsetName) {
-        if ($dataSubsetName = 'count'){
+        if ($dataSubsetName == 'count'){
             $attributes = new SecondaryCountAttributes($responseObj);
             $this->count = $attributes->count;
         }
-        $attributes = new SecondaryAttributes($responseObj);
-        $this->rootAddress = $attributes->rootAddress;
-        $this->aliases[] = $attributes->aliases;
-        $this->secondaries[] = $attributes->secondaries;
+        else {
+            $attributes = new SecondaryAttributes($responseObj);
+            $this->rootAddress = $attributes->rootAddress;
+            $this->aliases[] = $attributes->aliases;
+            $this->secondaries[] = $attributes->secondaries;
+        }
     }
 }
diff --git a/src/US_Enrichment/SecondaryAttributes.php b/src/US_Enrichment/SecondaryAttributes.php
@@ -34,14 +34,16 @@ private function createRootAddress($rootAddress){
     }
 
     private function createAliases($aliasesArray){
-        foreach($aliasesArray as $value){
-            $this->aliases = new AliasesEntry($value);
+        if ($aliasesArray != null) {
+            foreach($aliasesArray as $value){
+                $this->aliases[] = new AliasesEntry($value);
+            }
         }
     }
 
     private function createSecondaries($secondariesArray){
         foreach($secondariesArray as $value){
-            $this->secondaries = new SecondariesEntry($value);
+            $this->secondaries[] = new SecondariesEntry($value);
         }
     }
 }
diff --git a/tests/US_Enrichment/ClientTest.php b/tests/US_Enrichment/ClientTest.php
@@ -9,11 +9,13 @@
 require_once(dirname(dirname(__FILE__)) . '/Mocks/MockSender.php');
 require_once(dirname(dirname(__FILE__)) . '/Mocks/MockCrashingSender.php');
 require_once(dirname(dirname(dirname(__FILE__))) . '/src/US_Enrichment/Client.php');
+require_once(dirname(dirname(dirname(__FILE__))) . '/src/US_Enrichment/Lookup.php');
 require_once(dirname(dirname(dirname(__FILE__))) . '/src/URLPrefixSender.php');
 use SmartyStreets\PhpSdk\Tests\Mocks\MockSerializer;
 use SmartyStreets\PhpSdk\Tests\Mocks\RequestCapturingSender;
 use SmartyStreets\PhpSdk\URLPrefixSender;
 use SmartyStreets\PhpSdk\US_Enrichment\Client;
+use SmartyStreets\PhpSdk\US_Enrichment\Lookup;
 use PHPUnit\Framework\TestCase;
 
 class ClientTest extends TestCase {
@@ -28,4 +30,32 @@ public function testSendingLookup() {
 
         $this->assertEquals("http://localhost/123/property/principal?", $capturingSender->getRequest()->getUrl());
     }
+    public function testSendingAddressComponentLookup() {
+        $capturingSender = new RequestCapturingSender();
+        $sender = new URLPrefixSender("http://localhost/", $capturingSender);
+        $serializer = new MockSerializer(null);
+        $client = new Client($sender, $serializer);
+        $lookup = new Lookup();
+        $lookup->setStreet("123 Test Street");
+        $lookup->setCity("Test City");
+        $lookup->setState("Test State");
+        $lookup->setZipcode("Test Zipcode");
+
+        $client->sendPropertyPrincipalLookup($lookup);
+
+        $this->assertEquals("http://localhost/search/property/principal?street=123+Test+Street&city=Test+City&state=Test+State&zipcode=Test+Zipcode", $capturingSender->getRequest()->getUrl());
+    }
+
+    public function testSendingFreeformLookup() {
+        $capturingSender = new RequestCapturingSender();
+        $sender = new URLPrefixSender("http://localhost/", $capturingSender);
+        $serializer = new MockSerializer(null);
+        $client = new Client($sender, $serializer);
+        $lookup = new Lookup();
+        $lookup->setFreeform("123 Test Street City State Zipcode");
+
+        $client->sendPropertyPrincipalLookup($lookup);
+
+        $this->assertEquals("http://localhost/search/property/principal?freeform=123+Test+Street+City+State+Zipcode", $capturingSender->getRequest()->getUrl());
+    }
 }