2015-11-16

add by city, state, landarea, waterarea method

Author: MacHu-GWU

long_description.rst

@@ -1,12 +1,12 @@
 Welcome to the uszipcode Documentation
 ====================================================================================================
 
-``uszipcode`` is the most powerful and easy to use zipcode information searchengine in Python. Besides geometry data (also boundary info), several useful census data points are also served: `population`, `population density`, `total wage`, `average annual wage`, `house of units`, `land area`, `water area`. The geometry and geocoding data is from google map API on Oct 2015. The geometry data in `this another popular zipcode python package <https://pypi.python.org/pypi/zipcode>`_ is not accurate any more, if you exam it on google map. To know more about the data, `click here <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/uszipcode/data/__init__.html#module-uszipcode.data>`_.
+``uszipcode`` is the most powerful and easy to use zipcode information searchengine in Python. Besides geometry data (also boundary info), several useful census data points are also served: `population`, `population density`, `total wage`, `average annual wage`, `house of units`, `land area`, `water area`. The geometry and geocoding data I am using is from google map API on Oct 2015. To know more about the data, `click here <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/uszipcode/data/__init__.html#module-uszipcode.data>`_. `Another pupolar zipcode Python extension <https://pypi.python.org/pypi/zipcode>`_ has lat, lng accuracy issue, which doesn't give me reliable results of searching by coordinate and radius.
 
 **Highlight**:
 
-1. `rich methods <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#list-of-the-way-you-can-search>`_ are provided for getting zipcode anyway you want. 
-2. `fuzzy city name and state name <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#search-by-city-and-state>`_ allows you to search **WITHOUT using exactly accurate input**. **This is very helpful if you need to build a web app with it**.
+1. `Rich methods <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#list-of-the-way-you-can-search>`_ are provided for getting zipcode anyway you want. 
+2. `Fuzzy city name and state name <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#search-by-city-and-state>`_ allows you to search **WITHOUT using exactly accurate input**. **This is very helpful if you need to build a web app with it**.
 3. You can easily `sort your results <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#sortby-descending-and-returns-keyword>`_ by `population`, `area`, `wealthy` and etc...
 
 **Quick links**:

readme.rst

@@ -1,13 +1,13 @@
 Welcome to the uszipcode Documentation
 ====================================================================================================
 
-``uszipcode`` is the most powerful and easy to use zipcode information searchengine in Python. Besides geometry data (also boundary info), several useful census data points are also served: `population`, `population density`, `total wage`, `average annual wage`, `house of units`, `land area`, `water area`. The geometry and geocoding data is from google map API on Oct 2015. The geometry data in `this another popular zipcode python package <https://pypi.python.org/pypi/zipcode>`_ is not accurate any more, if you exam it on google map. To know more about the data, `click here <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/uszipcode/data/__init__.html#module-uszipcode.data>`_.
+``uszipcode`` is the most powerful and easy to use zipcode information searchengine in Python. Besides geometry data (also boundary info), several useful census data points are also served: `population`, `population density`, `total wage`, `average annual wage`, `house of units`, `land area`, `water area`. The geometry and geocoding data I am using is from google map API on Oct 2015. To know more about the data, `click here <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/uszipcode/data/__init__.html#module-uszipcode.data>`_. `Another pupolar zipcode Python extension <https://pypi.python.org/pypi/zipcode>`_ has lat, lng accuracy issue, which doesn't give me reliable results of searching by coordinate and radius.
 
 **Highlight**:
 
-1. `rich methods <search_way_>`_ are provided for getting zipcode anyway you want. 
-2. `fuzzy city name and state name <by_city_and_state_>`_ allows you to search **WITHOUT using exactly accurate input**. **This is very helpful if you need to build a web app with it**.
-3. You can easily `sort your results <keyword_>`_ by `population`, `area`, `wealthy` and etc...
+1. `Rich methods <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#list-of-the-way-you-can-search>`_ are provided for getting zipcode anyway you want. 
+2. `Fuzzy city name and state name <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#search-by-city-and-state>`_ allows you to search **WITHOUT using exactly accurate input**. **This is very helpful if you need to build a web app with it**.
+3. You can easily `sort your results <http://www.wbh-doc.com.s3.amazonaws.com/uszipcode/index.html#sortby-descending-and-returns-keyword>`_ by `population`, `area`, `wealthy` and etc...
 
 **Quick links**:
 
@@ -143,7 +143,7 @@ You can add ``standard_only=False`` parameter to enable returning Po Box type zi
 Search by Latitude and Longitude
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can search all zipcode with-in range of XXX miles to a coordinate. You can add ``returns=xxx`` to set maxiumum number of zipcode can be returned. By default, it's 5. Use ``returns=0`` to remove the limit. **The results are sorted by the distance from the center, from lowest to highest.
+You can search all zipcode with-in range of XXX miles to a coordinate. You can add ``returns=xxx`` to set maxiumum number of zipcode can be returned. By default, it's 5. Use ``returns=0`` to remove the limit. **The results are sorted by the distance from the center, from lowest to highest**.
 
 .. code-block:: python
 

uszipcode/searchengine.py

@@ -214,7 +214,7 @@ def by_city_and_state(self, city, state, standard_only=True):
         """Search zipcode information by City and State name.
         
         You can use either short state name and long state name. My engine use
-        fuzzy search and guess what is you want.
+        fuzzy match and guess what is you want.
         
         :param city: city name.
         :param state: 2 letter short name or long name.
@@ -258,6 +258,76 @@ def by_city_and_state(self, city, state, standard_only=True):
             res.append(Zipcode(self.all_column, list(row)))
 
         return res
+
+    def by_city(self, city, standard_only=True):
+        """Search zipcode information by City and State name.
+        
+        My engine use fuzzy match and guess what is you want.
+        
+        :param city: city name.
+        :param standard_only: boolean, default True, only returns standard 
+          type zipcode
+        """
+        # find out what is the city that user looking for
+        select_sql = "SELECT City FROM zipcode WHERE City == '%s'" % city
+        all_city = [record[0] for record in self.cursor.execute(select_sql)]
+        
+        choice, confidence = extractOne(city.lower(), all_city)
+        if confidence < 70:
+            raise Exception("Cannot found '%s' in '%s'." % (city, state))
+        else:
+            city = choice
+
+        # execute query
+        select_sql = \
+        """
+        SELECT * FROM zipcode 
+        WHERE City = '%s'
+        """ % (city,)
+        if standard_only:
+            select_sql = select_sql + self._standard_only_param
+
+        res = list()
+        for row in self.cursor.execute(select_sql):
+            res.append(Zipcode(self.all_column, list(row)))
+        
+        return res
+    
+    def by_state(self, state, standard_only=True):
+        """Search zipcode information by State name.
+        
+        You can use either short state name and long state name. My engine use
+        fuzzy match and guess what is you want.
+        
+        :param state: 2 letter short name or long name.
+        :param standard_only: boolean, default True, only returns standard 
+          type zipcode
+        """
+        # check if it is a abbreviate name
+        if state.upper() in self.all_state_short:
+            state = state.upper()
+        # if not, find out what is the state that user looking for
+        else:
+            choice, confidence = extractOne(state.lower(), self.all_state_long)
+            if confidence < 70:
+                raise Exception("'%s' is not a valid statename, use 2 letter "
+                                "short name or correct full name please." % state)
+            state = STATE_ABBR_LONG_TO_SHORT[choice]
+
+        # execute query
+        select_sql = \
+        """
+        SELECT * FROM zipcode 
+        WHERE State = '%s'
+        """ % (state,)
+        if standard_only:
+            select_sql = select_sql + self._standard_only_param
+
+        res = list()
+        for row in self.cursor.execute(select_sql):
+            res.append(Zipcode(self.all_column, list(row)))
+        
+        return res
 
     def by_prefix(self, prefix, standard_only=True, 
             sortby="ZipCode", descending=False, returns=_DEFAULT_LIMIT):
@@ -374,6 +444,58 @@ def by_density(self, lower=-1, upper=2**30, standard_only=True,
             res.append(Zipcode(self.all_column, list(row)))
         return res
 
+    def by_landarea(self, lower=-1, upper=2**30, standard_only=True, 
+            sortby="ZipCode", descending=False, returns=_DEFAULT_LIMIT):
+        """Search zipcode information by landarea range.
+        
+        :param lower: minimal landarea
+        :param upper: maximum landarea
+        :param standard_only: boolean, default True, only returns standard 
+          type zipcode
+        :param sortby: string, default ``"Zipcode"``
+        :param descending: boolean, default False
+        :param returns: int, default 5
+        """
+        select_sql = \
+        """
+        SELECT * FROM zipcode WHERE LandArea >= %f AND LandArea <= %f
+        """ % (lower, upper)
+        if standard_only:
+            select_sql = select_sql + self._standard_only_param
+        select_sql = select_sql + self.get_sortby_sql(sortby, descending)
+        select_sql = select_sql + self.get_limit_sql(returns)
+        
+        res = list()
+        for row in self.cursor.execute(select_sql):
+            res.append(Zipcode(self.all_column, list(row)))
+        return res
+
+    def by_waterarea(self, lower=-1, upper=2**30, standard_only=True, 
+            sortby="ZipCode", descending=False, returns=_DEFAULT_LIMIT):
+        """Search zipcode information by landarea range.
+        
+        :param lower: minimal waterarea
+        :param upper: maximum waterarea
+        :param standard_only: boolean, default True, only returns standard 
+          type zipcode
+        :param sortby: string, default ``"Zipcode"``
+        :param descending: boolean, default False
+        :param returns: int, default 5
+        """
+        select_sql = \
+        """
+        SELECT * FROM zipcode WHERE WaterArea >= %f AND WaterArea <= %f
+        """ % (lower, upper)
+        if standard_only:
+            select_sql = select_sql + self._standard_only_param
+        select_sql = select_sql + self.get_sortby_sql(sortby, descending)
+        select_sql = select_sql + self.get_limit_sql(returns)
+        
+        res = list()
+        for row in self.cursor.execute(select_sql):
+            res.append(Zipcode(self.all_column, list(row)))
+        return res
+    
     def by_totalwages(self, lower=-1, upper=2**30, standard_only=True, 
             sortby="ZipCode", descending=False, returns=_DEFAULT_LIMIT):
         """Search zipcode information by total annual wages.

uszipcode/tests/test_searchengine.py

@@ -31,21 +31,41 @@ def test_all(self):
             self.assertEqual(zipcode.City, "Nickerson")
             self.assertEqual(zipcode.State, "KS")
 
+            res = search.by_state("RI")
+            zipcode = res[0]
+            self.assertEqual(zipcode.Zipcode, "02804")
+            self.assertEqual(zipcode.City, "Ashaway")
+            self.assertEqual(zipcode.State, "RI")
+
+            res = search.by_city("Vienna")
+            zipcode = res[0]
+            self.assertEqual(zipcode.Zipcode, "04360")
+            self.assertEqual(zipcode.City, "Vienna")
+            self.assertEqual(zipcode.State, "ME")
+                     
             res = search.by_prefix("208",
-                sortby="Population", descending=True, returns=0)
+                sortby="Zipcode", descending=True, returns=0)
             self.assertEqual(len(res), 34)
 
             res = search.by_pattern("100",
-                sortby="Population", descending=True, returns=0)
+                sortby="Zipcode", descending=True, returns=0)
             self.assertEqual(len(res), 97)
 
             res = search.by_population(lower=100000,
-                sortby="Population", descending=True, returns=0)
+                sortby="Population", descending=False, returns=0)
             self.assertEqual(len(res), 10)
 
             res = search.by_density(lower=10000,
-                sortby="Population", descending=True, returns=0)
+                sortby="Density", descending=False, returns=0)
             self.assertEqual(len(res), 631)
+
+            res = search.by_landarea(lower=1000,
+                sortby="LandArea", descending=False, returns=0)
+            self.assertEqual(len(res), 181)
+
+            res = search.by_waterarea(lower=100,
+                sortby="WaterArea", descending=False, returns=0)
+            self.assertEqual(len(res), 30)
 
             res = search.by_totalwages(lower=1000**3,
                 sortby="Population", descending=True, returns=0)