Merge pull request #61 from smartystreets/eric/add-custom-parameter

Eric/add custom parameter
smartystreets · Dec 17, 2024 · 0e470a7 · 0e470a7
2 parents 2edfd8c + 21f9963
commit 0e470a7
Show file tree

Hide file tree

Showing 34 changed files with 454 additions and 15 deletions.
diff --git a/examples/InternationalAutocompleteExample.php b/examples/InternationalAutocompleteExample.php
@@ -36,6 +36,9 @@ public function run() {
         $lookup->setCountry("FRA");
         $lookup->setLocality("Paris");
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter", "value");
+
         try {
             $client->sendLookup($lookup); // The candidates are also stored in the lookup's 'result' field.
             foreach ($lookup->getResult() as $candidate) {

diff --git a/examples/InternationalExample.php b/examples/InternationalExample.php
@@ -43,6 +43,9 @@ public function run() {
         $lookup->setCountry("Brazil");
         $lookup->setPostalCode("02516-050");
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter", "value");
+
         try {
             $client->sendLookup($lookup); // The candidates are also stored in the lookup's 'result' field.
             $this->displayResults($lookup);

diff --git a/examples/USAutocompleteProExample.php b/examples/USAutocompleteProExample.php
@@ -51,6 +51,9 @@ public function run()
             $lookup->setMaxResults(5);
             $lookup->setSource("all");
 
+            // Uncomment the below line to add a custom parameter to the API call
+            // $lookup->addCustomParameter("parameter", "value");
+
             $client->sendLookup($lookup);
             $this->displayResultsFilter($lookup);
         }

diff --git a/examples/USEnrichmentExample.php b/examples/USEnrichmentExample.php
@@ -41,6 +41,22 @@ public function run()
         $lookup->setCity("Somerville");
         $lookup->setState("NJ");
         $lookup->setZipcode("08876");
+
+        // Use the setIncludeArray function to set the include or exclude parameter using an existing array:
+        // $tempArray = array("assessed_improvement_percent", "assessed_improvement_value");
+        // $lookup->setIncludeArray($tempArray);
+        // OR
+        // $lookup->setExcludeArray($tempArray);
+
+        // Or use the addIncludeAttributes function to set the attributes you would like to include or exclude one by one:
+        // $lookup->addIncludeAttribute("assessed_improvement_percent");
+        // $lookup->addIncludeAttribute("assessed_improvement_value");
+        // OR
+        // $lookup->addExcludeAttribute("assessed_improvement_percent");
+        // $lookup->addExcludeAttribute("assessed_improvement_value");
+
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter", "value");
 
         // You can also send an address in freeform by uncommenting the line below
         // $lookup->setFreeform("56 Union Ave Somerville NJ 08876");

diff --git a/examples/USExtractExample.php b/examples/USExtractExample.php
@@ -35,6 +35,9 @@ public function run() {
         $lookup->isAggressive();
         $lookup->setAddressesHaveLineBreaks(false);
         $lookup->setAddressesPerLine(2);
+
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter", "value");
         try {
             $client->sendLookup($lookup);
             $this->displayResults($lookup);

diff --git a/examples/USReverseGeoExample.php b/examples/USReverseGeoExample.php
@@ -34,6 +34,9 @@ public function run()
 
         $lookup = new Lookup(40.111111, -111.111111);
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter", "value");
+
         try {
             $client->sendLookup($lookup);
             $this->displayResults($lookup);

diff --git a/examples/USStreetLookupsWithMatchStrategyExamples.php b/examples/USStreetLookupsWithMatchStrategyExamples.php
@@ -31,6 +31,9 @@ public function run() {
         $addressWithStrictStrategy->setState("utah");
         $addressWithStrictStrategy->setMatchStrategy(Lookup::STRICT);
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $addressWithStrictStrategy->addCustomParameter("parameter", "value");
+
         $addressWithInvalidStrategy = new Lookup();
         $addressWithInvalidStrategy->setStreet("693 W 1150 S");
         $addressWithInvalidStrategy->setCity("provo");

diff --git a/examples/UsStreetMultipleAddressesExample.php b/examples/UsStreetMultipleAddressesExample.php
@@ -48,6 +48,9 @@ public function run()
         // this will always return at least one result even if the address is invalid.
         // Refer to the documentation for additional MatchStrategy options.
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $address0->addCustomParameter("parameter","value");
+
         $address1 = new Lookup("1 Rosedale, Baltimore, Maryland"); // Freeform addresses work too.
         $address1->setMaxCandidates(1); // Allows up to ten possible matches to be returned (default is 1).
 

diff --git a/examples/UsStreetSingleAddressExample.php b/examples/UsStreetSingleAddressExample.php
@@ -44,10 +44,14 @@ public function run() {
         $lookup->setState("CA");
         $lookup->setZipcode("21229");
         $lookup->setMaxCandidates(3);
+        $lookup->setCountySource(lookup::GEOGRAPHIC);
         $lookup->setMatchStrategy(Lookup::INVALID); // "invalid" is the most permissive match,
                                                                  // this will always return at least one result even if the address is invalid.
                                                                  // Refer to the documentation for additional MatchStrategy options.
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter","value");
+
         try {
             $client->sendLookup($lookup);
             $this->displayResults($lookup);

diff --git a/examples/UsZIPCodeMultipleLookupsExample.php b/examples/UsZIPCodeMultipleLookupsExample.php
@@ -35,6 +35,9 @@ public function run() {
         $lookup0 = new Lookup();
         $lookup0->setZIPCode("12345");  // A Lookup may have a ZIP Code, city and state, or city, state, and ZIP Code
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup0->addCustomParameter("parameter","value");
+
         $lookup1 = new Lookup();
         $lookup1->setInputId("01189998819991197253"); // Optional ID from your system
         $lookup1->setCity("Phoenix");

diff --git a/examples/UsZIPCodeSingleLookupExample.php b/examples/UsZIPCodeSingleLookupExample.php
@@ -34,6 +34,9 @@ public function run() {
         $lookup->setCity("Mountain View");
         $lookup->setState("California");
 
+        // Uncomment the below line to add a custom parameter to the API call
+        // $lookup->addCustomParameter("parameter", "value");
+
         try {
             $client->sendLookup($lookup);
             $this->displayResults($lookup);

diff --git a/src/International_Autocomplete/Client.php b/src/International_Autocomplete/Client.php
@@ -53,6 +53,10 @@ private function buildRequest(Lookup $lookup) {
         $request->setParameter("include_only_locality", $lookup->getLocality());
         $request->setParameter("include_only_postal_code", $lookup->getPostalCode());
 
+        foreach ($lookup->getCustomParamArray() as $key => $value) {
+            $request->setParameter($key, $value);
+        }
+
         return $request;
     }
 }
diff --git a/src/International_Autocomplete/Lookup.php b/src/International_Autocomplete/Lookup.php
@@ -18,7 +18,8 @@ class Lookup {
             $address_id,
             $maxResults,
             $locality,
-            $postalCode;
+            $postalCode,
+            $customParamArray;
     //endregion
 
     /**
@@ -29,6 +30,7 @@ public function __construct($search = null) {
         $this->result = array();
         $this->search = $search;
         $this->maxResults = Lookup::MAX_RESULTS_DEFAULT;
+        $this->customParamArray = array();
     }
 
     //region [ Getters ]
@@ -65,6 +67,10 @@ public function getPostalCode() {
         return $this->postalCode;
     }
 
+    public function getCustomParamArray() {
+        return $this->customParamArray;
+    }
+
     //endregion
 
     //region [ Setter ]
@@ -100,4 +106,8 @@ public function setPostalCode($postalCode) {
     }
 
     //endregion
+
+    public function addCustomParameter($parameter, $value) {
+        $this->customParamArray[$parameter] = $value;
+    }
 }
diff --git a/src/International_Street/Client.php b/src/International_Street/Client.php
@@ -58,6 +58,10 @@ private function buildRequest(Lookup $lookup) {
         $request->setParameter("administrative_area", $lookup->getAdministrativeArea());
         $request->setParameter("postal_code", $lookup->getPostalCode());
 
+        foreach ($lookup->getCustomParamArray() as $key => $value) {
+            $request->setParameter($key, $value);
+        }
+
         return $request;
     }
 

diff --git a/src/International_Street/Lookup.php b/src/International_Street/Lookup.php
@@ -24,14 +24,16 @@ class Lookup {
             $organization,
             $locality,
             $administrativeArea,
-            $postalCode;
+            $postalCode,
+            $customParamArray;
 
     //endregion
 
     //region [ Constructors ]
 
     public function __construct() {
         $this->result = array();
+        $this->customParamArray = array();
     }
 
     public function setFreeformInput($freeform, $country) {
@@ -144,6 +146,10 @@ public function getPostalCode() {
         return $this->postalCode;
     }
 
+    public function getCustomParamArray() {
+        return $this->customParamArray;
+    }
+
     //endregion
 
     //region [ Setters ]
@@ -218,4 +224,8 @@ public function setPostalCode($postalCode) {
     }
 
     //endregion
+
+    public function addCustomParameter($parameter, $value) {
+        $this->customParamArray[$parameter] = $value;
+    }
 }
diff --git a/src/US_Autocomplete_Pro/Client.php b/src/US_Autocomplete_Pro/Client.php
@@ -57,6 +57,10 @@ private function buildRequest(Lookup $lookup) {
         $request->setParameter("selected", $lookup->getSelected());
         $request->setParameter("source", $lookup->getSource());
 
+        foreach ($lookup->getCustomParamArray() as $key => $value) {
+            $request->setParameter($key, $value);
+        }
+
         return $request;
     }
 

diff --git a/src/US_Autocomplete_Pro/Lookup.php b/src/US_Autocomplete_Pro/Lookup.php
@@ -27,7 +27,8 @@ class Lookup {
             $preferRatio,
             $preferGeolocation,
             $selected,
-            $source;
+            $source,
+            $customParamArray;
 
     //endregion
 
@@ -47,6 +48,7 @@ public function __construct($search = null) {
         $this->preferZIPCodes = array();
         $this->preferRatio = Lookup::PREFER_RATIO_DEFAULT;
         $this->preferGeolocation = new GeolocateType(GEOLOCATE_TYPE_CITY);
+        $this->customParamArray = array();
     }
 
     public function addCityFilter($city) {
@@ -79,6 +81,10 @@ public function addPreferZIPCode($zipcode) {
         $this->preferZIPCodes[] = $zipcode;
     }
 
+    public function addCustomParameter($parameter, $value) {
+        $this->customParamArray[$parameter] = $value;
+    }
+
     //region [ Getters ]
 
     public function getResult() {
@@ -141,6 +147,10 @@ public function getSource() {
         return $this->source;
     }
 
+    public function getCustomParamArray() {
+        return $this->customParamArray;
+    }
+
     function getMaxResultsStringIfSet() {
         if ($this->maxResults == Lookup::MAX_RESULTS_DEFAULT)
             return null;
@@ -152,6 +162,7 @@ function getPreferRatioStringIfSet() {
             return null;
         return strval($this->preferRatio);
     }
+
     //endregion
 
     //region [ Setter ]

diff --git a/src/US_Enrichment/Client.php b/src/US_Enrichment/Client.php
@@ -156,6 +156,14 @@ private function buildRequest(Lookup $lookup) {
             $request->setParameter("state", $lookup->getState());
             $request->setParameter("zipcode", $lookup->getZipcode());
         }
+
+        $request->setParameter("include", $this->buildFilterString($lookup->getIncludeArray()));
+        $request->setParameter("exclude", $this->buildFilterString($lookup->getExcludeArray()));
+
+        foreach ($lookup->getCustomParamArray() as $key => $value) {
+            $request->setParameter($key, $value);
+        }
+
         return $request;
     }
 
@@ -173,4 +181,11 @@ private function getUrlPrefix($lookup){
             return $lookup->getSmartyKey() . "/" . $lookup->getDataSetName() . "/" . $lookup->getDataSubsetName();
         }
     }
+
+    private function buildFilterString($list) {
+        if (empty($list))
+            return null;
+
+        return join(',', $list);
+    }
 }
diff --git a/src/US_Enrichment/Lookup.php b/src/US_Enrichment/Lookup.php
@@ -14,12 +14,15 @@ class Lookup {
         $zipcode,
         $dataSetName,
         $dataSubsetName,
-        $response;
+        $include,
+        $exclude,
+        $response,
+        $customParamArray;
 
     //endregion
 
     public function __construct($smartyKey = null, $dataSetName = null, $dataSubsetName = null, $freeform = null, $street = null, $city = null, $state = null,
-    $zipcode = null) {
+    $zipcode = null, $include = null, $exclude = null) {
         $this->smartyKey = $smartyKey;
         $this->dataSetName = $dataSetName;
         $this->dataSubsetName = $dataSubsetName;
@@ -28,7 +31,10 @@ public function __construct($smartyKey = null, $dataSetName = null, $dataSubsetN
         $this->city = $city;
         $this->state = $state;
         $this->zipcode = $zipcode;
+        $this->include = array();
+        $this->exclude = array();
         $this->response = null;
+        $this->customParamArray = array();
     }
 
     public function getSmartyKey(){
@@ -62,11 +68,23 @@ public function getDataSetName(){
     public function getDataSubsetName(){
         return $this->dataSubsetName;
     }
+
+    public function getIncludeArray() {
+        return $this->include;
+    }
+
+    public function getExcludeArray() {
+        return $this->exclude;
+    }
 
     public function getResponse() {
         return $this->response;
     }
 
+    public function getCustomParamArray() {
+        return $this->customParamArray;
+    }
+
     public function setSmartyKey($smartyKey) {
         $this->smartyKey = $smartyKey;
     }
@@ -99,7 +117,27 @@ public function setZipcode($zipcode){
         $this->zipcode = $zipcode;
     }
 
+    public function setIncludeArray($include) {
+        $this->include = $include;
+    }
+
+    public function setExcludeArray($exclude) {
+        $this->exclude = $exclude;
+    }
+
     public function setResponse($response){
         $this->response = $response;
     }
+
+    public function addIncludeAttribute($attribute) {
+        array_push($this->include, $attribute);
+    }
+
+    public function addExcludeAttribute($attribute) {
+        array_push($this->exclude, $attribute);
+    }
+
+    public function addCustomParameter($parameter, $value) {
+        $this->customParamArray[$parameter] = $value;
+    }
 }