finish info option

Author: Mohamed Ben Makhlouf

pyzipcodeapi/api.py

@@ -2,13 +2,21 @@
 from http.client import HTTPSConnection
 from io import StringIO
 from json import loads
-from xml.etree.ElementTree import Element, fromstring
 from urllib.parse import urlencode
+from xml.etree.ElementTree import Element, fromstring
 
 import requests
 
-from pyzipcodeapi.dataclass import Distance, Error, MultiDistance, Radius, MultiRadius, MatchClose
-from pyzipcodeapi.enums import FormatEnum, UnitEnum, CountryEnum
+from pyzipcodeapi.dataclass import (
+    Distance,
+    Error,
+    MatchClose,
+    MultiDistance,
+    MultiRadius,
+    Radius,
+    Info,
+)
+from pyzipcodeapi.enums import CountryEnum, DistanceUnitEnum, FormatEnum, GeoUnitEnum
 from pyzipcodeapi.options import OPTIONS
 
 BASE_URL = "https://www.zipcodeapi.com/rest/{api_key}/{option}.{format}/"
@@ -120,7 +128,7 @@ def _api_call(
         body: str | None = None,
         headers: dict | None = None,
     ):
-        base_url = f"rest/v2/CA" if self.country == CountryEnum.CA else f"rest"
+        base_url = "rest/v2/CA" if self.country == CountryEnum.CA else "rest"
         self.con.request(
             method=method,
             url=f"/{base_url}/{self.api_key}/{option}.{self.format}/{path}",
@@ -141,7 +149,7 @@ def _post(self, option: str, path: str, data: dict):
             headers=headers,
         )
 
-    def parse_response(
+    def _parse_response(
         self, data_class: type | None = None
     ) -> DictReader | bytes | type | Element | Error | list[type]:
         response = self.con.getresponse()
@@ -165,40 +173,46 @@ def parse_response(
         return data
 
     def distance(
-        self, zip_code1: str, zip_code2: str, units: UnitEnum = UnitEnum.KM
+        self,
+        zip_code1: str,
+        zip_code2: str,
+        units: DistanceUnitEnum = DistanceUnitEnum.KM,
     ) -> Distance | DictReader | Element:
         """distance.<format>/<zip_code1>/<zip_code2>/<units>"""
         self._get("distance", f"{zip_code1}/{zip_code2}/{units}")
-        return self.parse_response(data_class=Distance)
+        return self._parse_response(data_class=Distance)
 
     def multi_distance(
-        self, zip_code: str, zip_codes: list[str], units: UnitEnum = UnitEnum.KM
+        self,
+        zip_code: str,
+        zip_codes: list[str],
+        units: DistanceUnitEnum = DistanceUnitEnum.KM,
     ) -> MultiDistance | DictReader | Element:
         """multi-distance.<format>/<zip_code>/<other_zip_codes>/<units>"""
         assert len(zip_codes) <= 100
         self._get("multi-distance", f"{zip_code}/{','.join(zip_codes)}/{units}")
-        return self.parse_response(data_class=MultiDistance)
+        return self._parse_response(data_class=MultiDistance)
 
     def radius(
         self,
         zip_code: str,
         distance: int,
         minimal: bool = False,
-        units: UnitEnum = UnitEnum.KM,
+        units: DistanceUnitEnum = DistanceUnitEnum.KM,
     ) -> Radius | DictReader | Element:
         """radius.<format>/<zip_code>/<distance>/<units>"""
         path = f"{zip_code}/{distance}/{units}"
         if minimal:
             path = f"{path}?minimal"
         self._get("radius", path)
-        return self.parse_response(data_class=Radius)
+        return self._parse_response(data_class=Radius)
 
     def multi_radius(
         self,
         distance: int,
         zip_codes: list[str] | None = None,
         addresses: list[str] | None = None,
-        units: UnitEnum = UnitEnum.KM,
+        units: DistanceUnitEnum = DistanceUnitEnum.KM,
     ) -> MultiRadius | DictReader | Element:
         """multi-radius.<format>/<distance>/<units>"""
         if zip_codes is None and addresses is None:
@@ -211,11 +225,21 @@ def multi_radius(
             assert len(addresses) <= 100
             body["addrs"] = "\n".join(addresses)
         self._post("multi-radius", f"{distance}/{units}", data=body)
-        return self.parse_response(data_class=MultiRadius)
+        return self._parse_response(data_class=MultiRadius)
 
     def match_close(
-        self, zip_codes: list[str], distance: int, units: UnitEnum = UnitEnum.KM
+        self,
+        zip_codes: list[str],
+        distance: int,
+        units: DistanceUnitEnum = DistanceUnitEnum.KM,
     ) -> list[MatchClose] | DictReader | Element:
         """match-close.<format>/<zip_codes>/<distance>/<units>"""
         self._get("match-close", f"{','.join(zip_codes)}/{distance}/{units}")
-        return self.parse_response(data_class=MatchClose)
+        return self._parse_response(data_class=MatchClose)
+
+    def info(
+        self, zip_code: str, units: GeoUnitEnum = GeoUnitEnum.DEGREES
+    ) -> Info | DictReader | Element:
+        """info.<format>/<zip_code>/<units>"""
+        self._get("info", f"{zip_code}/{units}")
+        return self._parse_response(data_class=Info)

pyzipcodeapi/dataclass.py

@@ -56,3 +56,17 @@ class MatchClose:
     zip_code1: str
     zip_code2: str
     distance: float
+
+
+
+
+@dataclass
+class Info:
+    zip_code: str
+    lat: float
+    lng: float
+    city: str
+    state: str
+    timezone: dict
+    acceptable_city_names: list[dict]
+    area_codes: list[int]

pyzipcodeapi/enums.py

@@ -7,11 +7,16 @@ class FormatEnum(str, Enum):
     CSV = "csv"
 
 
-class UnitEnum(str, Enum):
+class DistanceUnitEnum(str, Enum):
     KM = "km"
     MILE = "mile"
 
 
+class GeoUnitEnum(str, Enum):
+    DEGREES = "degrees"
+    RADIANS = "radians"
+
+
 class CountryEnum(str, Enum):
     US = "US"
     CA = "CA"

pyzipcodeapi/example.py

@@ -11,38 +11,35 @@
     obj = ZipCodeApi(API_KEY)
     # V2
     f2 = FormatEnum.JSON
-    u2 = UnitEnum.KM
+    ud = DistanceUnitEnum.KM
+    ug = GeoUnitEnum.DEGREES
     us = CountryEnum.US
     ca = CountryEnum.CA
     zca = ZipCodeApiV2(api_key=API_KEY, f=f2, country=us)
     # https://www.zipcodeapi.com/rest/<api_key>/distance.<format>/<zip_code1>/<zip_code2>/<units>
-    print(zca.distance(zip_code1="94106", zip_code2="94132", units=u2))
+    print(zca.distance(zip_code1="94106", zip_code2="94132", units=ud))
     print("------------------")
     # https://www.zipcodeapi.com/rest/<api_key>/multi-distance.<format>/<zip_code>/<other_zip_codes>/<units>
-    print(zca.multi_distance(zip_code="94106", zip_codes=["94132"], units=u2))
+    print(zca.multi_distance(zip_code="94106", zip_codes=["94132"], units=ud))
     print("------------------")
     # https://www.zipcodeapi.com/rest/<api_key>/radius.<format>/<zip_code>/<distance>/<units>
-    print(zca.radius(zip_code="94120", distance=5, units=u2, minimal=False))
+    print(zca.radius(zip_code="94120", distance=5, units=ud, minimal=False))
     print("------------------")
     # https://www.zipcodeapi.com/rest/<api_key>/multi-radius.<format>/<zip_code>/<distance>/<units>
     print(
         zca.multi_radius(
             distance=5,
             zip_codes=["22911", "22902"],
             addresses=["1827 Glissade Ln, Charlottesville VA 22911"],
-            units=u2,
+            units=ud,
         )
     )
     print("------------------")
     # https://www.zipcodeapi.com/rest/<api_key>/match-close.<format>/<zip_codes>/<distance>/<units>
-    print(
-        zca.match_close(
-            zip_codes=["22911", "22902", "22904", "22905"], distance=120, units=u2
-        )
-    )
+    print(zca.match_close(zip_codes=["22911", "22902", "22904"], distance=90, units=ud))
     print("------------------")
-    # https://www.zipcodeapi.com/rest/<api_key>/multi-info.<format>/<zip_code>/<units>
-    print(obj.get("multi-info", f).filter(zip_code="94132", units=ou))
+    # https://www.zipcodeapi.com/rest/<api_key>/info.<format>/<zip_code>/<units>
+    print(zca.info(zip_code="22911", units=ug))
     print("------------------")
     # https://www.zipcodeapi.com/rest/<api_key>/city-zips.<format>/<city>/<state>
     print(obj.get("city-zips", f).filter(city="San Francisco", state="CA"))