DEVOPS-247: add address-similarity

Author: Katsuya-Tomioka

docs/source/conf.py

@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.12.1'
+version = '1.14.3'
 # The full version, including alpha/beta/rc tags.
-release = '1.12.1'
+release = '1.14.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

examples/address_similarity.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+"""
+Example code to call Rosette API to get match score (similarity) of two addresses.
+"""
+from __future__ import print_function
+
+import argparse
+import json
+import os
+
+from rosette.api import API, AddressSimilarityParameters, RosetteException
+
+
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
+    # Create an API instance
+    api = API(user_key=key, service_url=alt_url)
+
+    params = AddressSimilarityParameters()
+    params["address1"] = {"city": "Cambridge", "state": "MA"}
+    params["address2"] = {"city": "cambridge", "state": "massachusetts"}
+    try:
+        return api.address_similarity(params)
+    except RosetteException as exception:
+        print(exception)
+
+
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
+
+if __name__ == '__main__':
+    ARGS = PARSER.parse_args()
+    RESULT = run(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))

rosette/__init__.py

@@ -12,4 +12,4 @@
 limitations under the License.
 """
 
-__version__ = '1.12.1'
+__version__ = '1.14.3'

rosette/api.py

@@ -28,7 +28,7 @@
 import requests
 import platform
 
-_BINDING_VERSION = '1.12.1'
+_BINDING_VERSION = '1.14.3'
 _GZIP_BYTEARRAY = bytearray([0x1F, 0x8b, 0x08])
 
 _ISPY3 = sys.version_info[0] == 3
@@ -246,6 +246,32 @@ def validate(self):
                     repr(option))
 
 
+class AddressSimilarityParameters(_DocumentParamSetBase):
+    """Parameter object for C{address-similarity} endpoint.
+    All are required.
+
+    C{address1} The address to be matched, a C{address} object.
+
+    C{address2} The address to be matched, a C{address} object.
+
+    The C{address} object contains these optional fields:
+      city, island, district, stateDistrict, state, countryRegion, country, worldRegion, postCode, poBox
+    """
+
+    def __init__(self):
+        self.use_multipart = False
+        _DocumentParamSetBase.__init__(self, ("address1", "address2"))
+
+    def validate(self):
+        """Internal. Do not use."""
+        for option in ("address1", "address2"):  # required
+            if self[option] is None:
+                raise RosetteException(
+                    "missingParameter",
+                    "Required Address Similarity parameter, " + option + ", not supplied",
+                    repr(option))
+
+
 class NameSimilarityParameters(_DocumentParamSetBase):
     """Parameter object for C{name-similarity} endpoint.
     All are required.
@@ -550,6 +576,7 @@ def __init__(
         }
 
         self.endpoints = {
+            'ADDRESS_SIMILARITY': 'address-similarity',
             'CATEGORIES': 'categories',
             'ENTITIES': 'entities',
             'INFO': 'info',
@@ -879,6 +906,15 @@ def relationships(self, parameters):
         @return: A python dictionary containing the results of relationship extraction."""
         return EndpointCaller(self, self.endpoints['RELATIONSHIPS']).call(parameters)
 
+    def address_similarity(self, parameters):
+        """
+        Create an L{EndpointCaller} to perform address similarity scoring and call it.
+        @param parameters: An object specifying the data,
+        and possible metadata, to be processed by the name matcher.
+        @type parameters: L{AddressSimilarityParameters}
+        @return: A python dictionary containing the results of name matching."""
+        return EndpointCaller(self, self.endpoints['ADDRESS_SIMILARITY']).call(parameters)
+
     def name_translation(self, parameters):
         """
         Create an L{EndpointCaller} to perform name analysis and translation