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

Eric/enrichment address search

Author: RyanLCox1

examples/us_enrichment_example.py

@@ -1,6 +1,7 @@
 import os
 
 from smartystreets_python_sdk import SharedCredentials, StaticCredentials, exceptions, ClientBuilder
+from smartystreets_python_sdk.us_enrichment.lookup import Lookup as EnrichmentLookup
 
 
 # from smartystreets_python_sdk.us_enrichment import
@@ -30,17 +31,34 @@ def run():
     # client = ClientBuilder(credentials).with_http_proxy('localhost:8080', 'user', 'password').build_us_street_api_client()
     # Uncomment the line above to try it with a proxy instead
 
-    smarty_key = "1682393594"
+    smarty_key = "325023201"
+
+    lookup = EnrichmentLookup()
+    freeform_lookup = EnrichmentLookup()
+
+    lookup.street = "56 Union Ave"
+    lookup.city = "Somerville"
+    lookup.state = "NJ"
+    lookup.zipcode = "08876"
+
+    freeform_lookup.freeform = "56 Union Ave Somerville NJ 08876"
+
     try:
+        # use the below line to send a lookup with a smarty key
         results = client.send_property_principal_lookup(smarty_key)
+        # Or, uncomment the below line to send a lookup with an address in components
+        # results = client.send_property_principal_lookup(lookup)
+        # Or, uncomment the below line to send a lookup with an address in freeform
+        # results = client.send_property_principal_lookup(freeform_lookup)
+
         # results = client.send_generic_lookup(smarty_key, 'property', 'principal')
         # Uncomment the line above to try it as a generic lookup instead
     except Exception as err:
         print(err)
         return
 
     if not results:
-        print("No results found. This means the Smartykey is likely not valid.")
+        print("No results found. This means the Smartykey or address is likely not valid, or does not have data in this dataset")
         return
 
     top_result = results[0]

smartystreets_python_sdk/us_enrichment/client.py

@@ -12,44 +12,79 @@ def __init__(self, sender, serializer):
         self.sender = sender
         self.serializer = serializer
 
-    def send_property_financial_lookup(self, smartykey):
-        l = FinancialLookup(smartykey)
-        send_lookup(self, l)
-        return l.result
-
-    def send_property_principal_lookup(self, smartykey):
-        l = PrincipalLookup(smartykey)
-        send_lookup(self, l)
-        return l.result
+    def send_property_financial_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = FinancialLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'property'
+            lookup.dataSubset = 'financial'
+            send_lookup(self, lookup)
+            return lookup.result
+        
+    def send_property_principal_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = PrincipalLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'property'
+            lookup.dataSubset = 'principal'
+            send_lookup(self, lookup)
+            return lookup.result
 
-    def send_geo_reference_lookup(self, smartykey):
-        l = GeoReferenceLookup(smartykey)
-        send_lookup(self, l)
-        return l.result
+    def send_geo_reference_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = GeoReferenceLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'geo-reference'
+            lookup.dataSubset = None
+            send_lookup(self, lookup)
+            return lookup.result
 
-    def send_secondary_lookup(self, smartykey):
-        l = SecondaryLookup(smartykey)
-        send_lookup(self, l)
-        return l.result
+    def send_secondary_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = SecondaryLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'secondary'
+            lookup.dataSubset = None
+            send_lookup(self, lookup)
+            return lookup.result
 
-    def send_secondary_count_lookup(self, smartykey):
-        l = SecondaryCountLookup(smartykey)
-        send_lookup(self, l)
-        return l.result
+    def send_secondary_count_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = SecondaryCountLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'secondary'
+            lookup.dataSubset = 'count'
+            send_lookup(self, lookup)
+            return lookup.result
 
-    def send_generic_lookup(self, smartykey, dataset, dataSubset):
-        l = Lookup(smartykey, dataset, dataSubset)
-        send_lookup(self, l)
-        return l.result
+    def send_generic_lookup(self, lookup, dataset, dataSubset):
+        if isinstance(lookup, str):
+            l = Lookup(lookup, dataset, dataSubset)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = dataset
+            lookup.dataSubset = dataSubset
+            send_lookup(self, lookup)
+            return lookup.result
 
 
 def send_lookup(client: Client, lookup):
     """
     Sends a Lookup object to the US Enrichment API and stores the result in the Lookup's result field.
     """
-    if lookup is None or lookup.smartykey is None or not isinstance(lookup.smartykey, str) or len(
-            lookup.smartykey.strip()) == 0:
-        raise SmartyException('Client.send() requires a Lookup with the "smartykey" field set as a string')
+    if lookup is None or (lookup.smartykey is None and lookup.street is None and lookup.freeform is None):
+        raise SmartyException('Client.send() requires a Lookup with either the "smartykey", "street, or "freeform" field set as a string')
 
     request = build_request(lookup)
 
@@ -67,10 +102,37 @@ def send_lookup(client: Client, lookup):
 
 def build_request(lookup):
     request = Request()
-    if lookup.dataSubset == None:
-        request.url_components = lookup.smartykey + "/" + lookup.dataset
+    if lookup.smartykey != None:
+        if lookup.dataSubset == None:
+            request.url_components = lookup.smartykey + "/" + lookup.dataset
+            return request
+    
+        request.url_components = lookup.smartykey + "/" + lookup.dataset + "/" + lookup.dataSubset
+
+        return request
+    else:
+        if lookup.dataSubset == None:
+            request.url_components = 'search/' + lookup.dataset
+            request.parameters = remap_keys(lookup)
+            return request
+    
+        request.url_components = 'search/' + lookup.dataset + "/" + lookup.dataSubset
+
+        request.parameters = remap_keys(lookup)
         return request
 
-    request.url_components = lookup.smartykey + "/" + lookup.dataset + "/" + lookup.dataSubset
+def remap_keys(lookup):
+    converted_lookup = {}
+
+    add_field(converted_lookup, 'freeform', lookup.freeform)
+    add_field(converted_lookup, 'street', lookup.street)
+    add_field(converted_lookup, 'city', lookup.city)
+    add_field(converted_lookup, 'state', lookup.state)
+    add_field(converted_lookup, 'zipcode', lookup.zipcode)
+
+    return converted_lookup
+
 
-    return request
+def add_field(converted_lookup, key, value):
+    if value:
+        converted_lookup[key] = value

smartystreets_python_sdk/us_enrichment/lookup.py

@@ -7,28 +7,33 @@
 noneDataSubset = None
 
 class Lookup:
-    def __init__(self, smartykey, dataset, dataSubset):
+    def __init__(self, smartykey = None, dataset = None, dataSubset = None, freeform = None, street = None, city = None, state = None, zipcode = None):
         self.smartykey = smartykey
         self.dataset = dataset
         self.dataSubset = dataSubset
+        self.freeform = freeform
+        self.street = street
+        self.city = city
+        self.state = state
+        self.zipcode = zipcode
         self.result = []
 
 class FinancialLookup(Lookup):
-    def __init__(self, smartykey):
+    def __init__(self, smartykey = None):
         super().__init__(smartykey, propertyDataset, financialDataSubset)
 
 class PrincipalLookup(Lookup):
-    def __init__(self, smartykey):
+    def __init__(self, smartykey = None):
         super().__init__(smartykey, propertyDataset, principalDataSubset)
 
 class GeoReferenceLookup(Lookup):
-    def __init__(self, smartykey):
+    def __init__(self, smartykey = None):
         super().__init__(smartykey, geoReferenceDataset, noneDataSubset)
 
 class SecondaryLookup(Lookup):
-    def __init__(self, smartykey):
+    def __init__(self, smartykey = None):
         super().__init__(smartykey, secondaryDataset, noneDataSubset)
 
 class SecondaryCountLookup(Lookup):
-    def __init__(self, smartykey):
+    def __init__(self, smartykey = None):
         super().__init__(smartykey, secondaryDataset, countDataSubset)

test/us_enrichment/client_test.py

@@ -23,6 +23,25 @@ def test_sending_Financial_Lookup(self):
         function_result = client.send_property_financial_lookup("xxx")
         self.assertEqual(result, function_result)
 
+    def test_sending_Financial_address_Lookup(self):
+        capturing_sender = RequestCapturingSender()
+        sender = URLPrefixSender('http://localhost/', capturing_sender)
+        serializer = FakeSerializer(None)
+        client = Client(sender, serializer)
+        lookup = FinancialLookup()
+        lookup.street = "street"
+        lookup.city = "city"
+        lookup.state = "state"
+        lookup.zipcode = "zipcode"
+        result = send_lookup(client, lookup)
+
+        self.assertEqual("property", lookup.dataset)
+        self.assertEqual("financial", lookup.dataSubset)
+        self.assertEqual(lookup.result, result)
+
+        function_result = client.send_property_financial_lookup(lookup)
+        self.assertEqual(result, function_result)
+
     def test_sending_principal_lookup(self):
         capturing_sender = RequestCapturingSender()
         sender = URLPrefixSender('http://localhost/', capturing_sender)
@@ -38,6 +57,26 @@ def test_sending_principal_lookup(self):
 
         function_result = client.send_property_principal_lookup("xxx")
         self.assertEqual(result, function_result)
+
+    def test_sending_principal_address_lookup(self):
+        capturing_sender = RequestCapturingSender()
+        sender = URLPrefixSender('http://localhost/', capturing_sender)
+        serializer = FakeSerializer(None)
+        client = Client(sender, serializer)
+
+        lookup = PrincipalLookup()
+        lookup.street = "street"
+        lookup.city = "city"
+        lookup.state = "state"
+        lookup.zipcode = "zipcode"
+        result = send_lookup(client, lookup)
+
+        self.assertEqual("property", lookup.dataset)
+        self.assertEqual("principal", lookup.dataSubset)
+        self.assertEqual(lookup.result, result)
+
+        function_result = client.send_property_principal_lookup(lookup)
+        self.assertEqual(result, function_result)
 
     def test_sending_geo_reference_lookup(self):
         capturing_sender = RequestCapturingSender()
@@ -54,6 +93,26 @@ def test_sending_geo_reference_lookup(self):
 
         function_result = client.send_geo_reference_lookup("xxx")
         self.assertEqual(result, function_result)
+    
+    def test_sending_geo_reference_address_lookup(self):
+        capturing_sender = RequestCapturingSender()
+        sender = URLPrefixSender('http://localhost/', capturing_sender)
+        serializer = FakeSerializer(None)
+        client = Client(sender, serializer)
+
+        lookup = GeoReferenceLookup()
+        lookup.street = "street"
+        lookup.city = "city"
+        lookup.state = "state"
+        lookup.zipcode = "zipcode"
+        result = send_lookup(client, lookup)
+
+        self.assertEqual("geo-reference", lookup.dataset)
+        self.assertEqual(None, lookup.dataSubset)
+        self.assertEqual(lookup.result, result)
+
+        function_result = client.send_geo_reference_lookup(lookup)
+        self.assertEqual(result, function_result)
 
     def test_sending_secondary_lookup(self):
         capturing_sender = RequestCapturingSender()
@@ -71,6 +130,26 @@ def test_sending_secondary_lookup(self):
         function_result = client.send_secondary_lookup("xxx")
         self.assertEqual(result, function_result)
 
+    def test_sending_secondary_address_lookup(self):
+        capturing_sender = RequestCapturingSender()
+        sender = URLPrefixSender('http://localhost/', capturing_sender)
+        serializer = FakeSerializer(None)
+        client = Client(sender, serializer)
+
+        lookup = SecondaryLookup()
+        lookup.street = "street"
+        lookup.city = "city"
+        lookup.state = "state"
+        lookup.zipcode = "zipcode"
+        result = send_lookup(client, lookup)
+
+        self.assertEqual("secondary", lookup.dataset)
+        self.assertEqual(None, lookup.dataSubset)
+        self.assertEqual(lookup.result, result)
+
+        function_result = client.send_secondary_lookup(lookup)
+        self.assertEqual(result, function_result)
+
     def test_sending_secondary_count_lookup(self):
         capturing_sender = RequestCapturingSender()
         sender = URLPrefixSender('http://localhost/', capturing_sender)
@@ -86,3 +165,23 @@ def test_sending_secondary_count_lookup(self):
 
         function_result = client.send_secondary_count_lookup("xxx")
         self.assertEqual(result, function_result)
+
+    def test_sending_secondary_count_address_lookup(self):
+        capturing_sender = RequestCapturingSender()
+        sender = URLPrefixSender('http://localhost/', capturing_sender)
+        serializer = FakeSerializer(None)
+        client = Client(sender, serializer)
+
+        lookup = SecondaryCountLookup()
+        lookup.street = "street"
+        lookup.city = "city"
+        lookup.state = "state"
+        lookup.zipcode = "zipcode"
+        result = send_lookup(client, lookup)
+
+        self.assertEqual("secondary", lookup.dataset)
+        self.assertEqual("count", lookup.dataSubset)
+        self.assertEqual(lookup.result, result)
+
+        function_result = client.send_secondary_count_lookup(lookup)
+        self.assertEqual(result, function_result)