Merge pull request #53 from smartystreets/eric/add-geo-reference

Add GeoReference and Generic Lookup Capabilities for the US Address Enrichment API

Author: RyanLCox1

examples/us_enrichment_example.py

@@ -33,6 +33,8 @@ def run():
     smarty_key = "1682393594"
     try:
         results = client.send_property_principal_lookup(smarty_key)
+        # 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

smartystreets_python_sdk/us_enrichment/client.py

@@ -1,6 +1,6 @@
 from smartystreets_python_sdk import Request
 from smartystreets_python_sdk.exceptions import SmartyException
-from .lookup import FinancialLookup, PrincipalLookup
+from .lookup import FinancialLookup, PrincipalLookup, GeoReferenceLookup, Lookup
 from .response import Response
 
 
@@ -21,6 +21,16 @@ def send_property_principal_lookup(self, smartykey):
         l = PrincipalLookup(smartykey)
         send_lookup(self, l)
         return l.result
+    
+    def send_geo_reference_lookup(self, smartykey):
+        l = GeoReferenceLookup(smartykey)
+        send_lookup(self, l)
+        return l.result
+    
+    def send_generic_lookup(self, smartykey, dataset, dataSubset):
+        l = Lookup(smartykey, dataset, dataSubset)
+        send_lookup(self, l)
+        return l.result
 
 
 def send_lookup(client: Client, lookup):
@@ -47,6 +57,10 @@ def send_lookup(client: Client, lookup):
 
 def build_request(lookup):
     request = Request()
+    if lookup.dataSubset == None:
+        request.url_components = lookup.smartykey + "/" + lookup.dataset
+        return request
+    
     request.url_components = lookup.smartykey + "/" + lookup.dataset + "/" + lookup.dataSubset
 
     return request

smartystreets_python_sdk/us_enrichment/lookup.py

@@ -1,6 +1,8 @@
 propertyDataset = "property"
 financialDataSubset = "financial"
 principalDataSubset = "principal"
+geoReferenceDataset = "geo-reference"
+noneDataSubset = None
 
 class Lookup:
     def __init__(self, smartykey, dataset, dataSubset):
@@ -15,4 +17,8 @@ def __init__(self, smartykey):
 
 class PrincipalLookup(Lookup):
     def __init__(self, smartykey):
-        super().__init__(smartykey, propertyDataset, principalDataSubset)
+        super().__init__(smartykey, propertyDataset, principalDataSubset)
+
+class GeoReferenceLookup(Lookup):
+    def __init__(self, smartykey):
+        super().__init__(smartykey, geoReferenceDataset, noneDataSubset)

smartystreets_python_sdk/us_enrichment/response.py

@@ -3,7 +3,7 @@ def __init__(self, obj):
         self.smarty_key = obj.get('smarty_key', None)
         self.data_set_name = obj.get('data_set_name', None)
         self.data_subset_name = obj.get('data_subset_name', None)
-        self.attributes = get_attributes(self.data_set_name, self.data_subset_name, obj.get('attributes'))
+        self.attributes = get_attributes(self.data_set_name, self.data_subset_name, obj.get('attributes', None))
 
     def __str__(self):
         lines = [self.__class__.__name__ + ':']
@@ -21,6 +21,8 @@ def get_attributes(dataset, data_subset, attribute_obj):
             return FinancialAttributes(attribute_obj)
         if data_subset == "principal":
             return PrincipalAttributes(attribute_obj)
+    if dataset == "geo-reference":
+        return GeoReferenceOutputCategories(attribute_obj)
 
 
 class PrincipalAttributes:
@@ -387,7 +389,16 @@ def __init__(self, obj):
         self.zoning = obj.get('zoning', None)
 
     def __str__(self):
-        return self.__dict__.__str__()
+        lines = ['']
+        for key, val in vars(self).items():
+            if type(val) is list:
+                lines.append(key + ': ')
+                for item in val:
+                    for subkey, subval in vars(item).items():
+                        lines += '    {}: {}'.format(subkey, subval).split('\n')
+            else:
+                lines.append(key + ': ' + str(val))
+        return '\n    '.join(lines)
 
 
 class FinancialAttributes:
@@ -492,7 +503,16 @@ def __init__(self, obj):
         self.widow_tax_exemption = obj.get('widow_tax_exemption', None)
 
     def __str__(self):
-        return self.__dict__.__str__()
+        lines = ['']
+        for key, val in vars(self).items():
+            if type(val) is list:
+                lines.append(key + ': ')
+                for item in val:
+                    for subkey, subval in vars(item).items():
+                        lines += '    {}: {}'.format(subkey, subval).split('\n')
+            else:
+                lines.append(key + ': ' + str(val))
+        return '\n    '.join(lines)
 
 
 def get_financial_history(financial_history_obj):
@@ -549,3 +569,104 @@ def __init__(self, obj):
         self.name_title_company = obj.get('name_title_company', None)
         self.recording_date = obj.get('recording_date', None)
         self.transfer_amount = obj.get('transfer_amount', None)
+
+    def __str__(self):
+        return self.__dict__.__str__()
+    
+class GeoReferenceOutputCategories:
+    def __init__(self, obj):
+
+        self.census_block = get_geo_reference_census_block(obj.get('census_block', None))
+        self.census_county_division = get_geo_reference_census_county_division(obj.get('census_county_division', None))
+        self.census_tract = get_geo_reference_census_tract(obj.get('census_tract', None))
+        self.core_based_stat_area = get_geo_reference_core_based_stat_area(obj.get('core_based_stat_area', None))
+        self.place = get_geo_reference_place(obj.get('place', None))
+
+    def __str__(self):
+        lines = ['']
+        for key, val in vars(self).items():
+            if type(val) is list:
+                lines.append(key + ': ')
+                for item in val:
+                    for subkey, subval in vars(item).items():
+                        lines += '    {}: {}'.format(subkey, subval).split('\n')
+            else:
+                lines.append(key + ': ' + str(val))
+        return '\n    '.join(lines)
+
+class GeoReferenceCensusBlock:
+    def __init__(self, obj):
+        self.accuracy = obj.get('accuracy', None)
+        self.geoid = obj.get('geoid', None)
+
+    def __str__(self):
+        return self.__dict__.__str__()
+    
+def get_geo_reference_census_block(geo_reference_census_block_obj):
+    if geo_reference_census_block_obj is None:
+        return None
+    output = []
+    output.append(GeoReferenceCensusBlock(geo_reference_census_block_obj))
+    return output
+
+class GeoReferenceCensusCountyDivision:
+    def __init__(self, obj):
+        self.accuracy = obj.get('accuracy', None)
+        self.code = obj.get('code', None)
+        self.name = obj.get('name', None)
+
+    def __str__(self):
+        return self.__dict__.__str__()
+    
+def get_geo_reference_census_county_division(geo_reference_census_county_division_obj):
+    if geo_reference_census_county_division_obj is None:
+        return None
+    output = []
+    output.append(GeoReferenceCensusCountyDivision(geo_reference_census_county_division_obj))
+    return output
+
+class GeoReferenceCensusTract:
+    def __init__(self, obj):
+        self.code = obj.get('code', None)
+
+    def __str__(self):
+        return self.__dict__.__str__()
+    
+def get_geo_reference_census_tract(geo_reference_census_tract_obj):
+    if geo_reference_census_tract_obj is None:
+        return None
+    output = []
+    output.append(GeoReferenceCensusTract(geo_reference_census_tract_obj))
+    return output
+
+class GeoReferenceCoreBasedStatArea:
+    def __init__(self, obj):
+        self.code = obj.get('code', None)
+        self.name = obj.get('name', None)
+
+    def __str__(self):
+        return self.__dict__.__str__()
+    
+def get_geo_reference_core_based_stat_area(geo_reference_core_based_stat_area_obj):
+    if geo_reference_core_based_stat_area_obj is None:
+        return None
+    output = []
+    output.append(GeoReferenceCoreBasedStatArea(geo_reference_core_based_stat_area_obj))
+    return output
+
+class GeoReferencePlace:
+    def __init__(self, obj):
+        self.accuracy = obj.get('accuracy', None)
+        self.code = obj.get('code', None)
+        self.name = obj.get('name', None)
+        self.type = obj.get('type', None)
+
+    def __str__(self):
+        return self.__dict__.__str__()
+
+def get_geo_reference_place(geo_reference_place_obj):
+    if geo_reference_place_obj is None:
+        return None
+    output = []
+    output.append(GeoReferencePlace(geo_reference_place_obj))
+    return output