finish zip codes option

Author: Mohamed Ben Makhlouf

pyzipcodeapi/api.py

@@ -2,7 +2,7 @@
 from http.client import HTTPSConnection
 from io import StringIO
 from json import loads
-from urllib.parse import urlencode
+from urllib.parse import quote_plus, urlencode
 from xml.etree.ElementTree import Element, fromstring
 
 import requests
@@ -15,10 +15,13 @@
     MultiDistance,
     MultiRadius,
     Radius,
+    ZipCode,
 )
 from pyzipcodeapi.enums import CountryEnum, DistanceUnitEnum, FormatEnum, GeoUnitEnum
 from pyzipcodeapi.options import OPTIONS
 
+ResultType = DictReader | bytes | type | Element | Error | list[type]
+
 BASE_URL = "https://www.zipcodeapi.com/rest/{api_key}/{option}.{format}/"
 FORMAT = ["json", "xml", "csv"]
 
@@ -149,9 +152,7 @@ def _post(self, option: str, path: str, data: dict):
             headers=headers,
         )
 
-    def _parse_response(
-        self, data_class: type | None = None
-    ) -> DictReader | bytes | type | Element | Error | list[type]:
+    def _parse_response(self, data_class: type | None = None) -> ResultType:
         response = self.con.getresponse()
         success = response.status == 200
         data = response.read()
@@ -250,3 +251,19 @@ def multi_info(
         """multi-info.<format>/<zip_code>/<units>"""
         self._get("multi-info", f"{','.join(zip_codes)}/{units}")
         return self._parse_response()
+
+    def city_zip_codes(
+        self, city: str, state: str
+    ) -> ZipCode | DictReader | Element:
+        """
+        US: city-zips.<format>/<city>/<state>
+        CA: city-postal-codes.<format>/<city>/<province>
+        """
+        option = "city-postal-codes" if self.country == CountryEnum.CA else "city-zips"
+        self._get(option, f"{quote_plus(city)}/{quote_plus(state)}")
+        return self._parse_response(data_class=ZipCode)
+
+    def state_zip_codes(self, state: str) -> ZipCode | DictReader | Element:
+        """state-zips.<format>/<state>"""
+        self._get("state-zips", f"{quote_plus(state)}")
+        return self._parse_response(data_class=ZipCode)

pyzipcodeapi/dataclass.py

@@ -68,3 +68,8 @@ class Info:
     timezone: dict
     acceptable_city_names: list[dict]
     area_codes: list[int]
+
+
+@dataclass
+class ZipCode:
+    zip_codes: list[str]

pyzipcodeapi/example.py

@@ -44,6 +44,12 @@
     # https://www.zipcodeapi.com/rest/<api_key>/multi-info.<format>/<zip_code>/<units>
     print(zca.multi_info(zip_codes=["22911"], units=ug))
     print("------------------")
+    # https://www.zipcodeapi.com/rest/<api_key>/city-zips.<format>/<city>/<state>
+    print(zca.city_zip_codes(city="New York", state="VA"))
+    print("------------------")
+    # https://www.zipcodeapi.com/rest/<api_key>/state-zips.<format>/<state>
+    print(zca.state_zip_codes(state="VA"))
+    print("------------------")
     # https://www.zipcodeapi.com/rest/<api_key>/radius-sql.<format>/<lat>/<long>/<lat_long_units>/<distance>/<units>/
     # <lat_field_name>/<long_field_name>/<precision>
     print(