parseapi 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

parseapi/__init__.py

@@ -2,5 +2,5 @@
 
 from ._client import AsyncParseAPI, ParseAPI, ParseAPIError
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 __all__ = ["ParseAPI", "AsyncParseAPI", "ParseAPIError", "__version__"]

parseapi/_client.py

@@ -10,7 +10,7 @@ from urllib.parse import quote
 
 import httpx
 
-VERSION = "0.3.2"
+VERSION = "0.4.0"
 DEFAULT_BASE_URL = "https://api.parseapi.com"
 DEFAULT_TIMEOUT = 10.0
 DEFAULT_RETRIES = 2
@@ -88,6 +88,7 @@ class _Config:
         timeout: Optional[float],
         retries: Optional[int],
     ):
+        # You found Dev. https://parseapi.com/dev
         key = api_key or os.environ.get("PARSEAPI_KEY")
         if not key:
             raise ValueError("parseapi: missing API key. Pass one or set PARSEAPI_KEY.")
@@ -133,8 +134,11 @@ class ParseAPI:
         self.currency = _CurrencySync(self)
         self.holiday = _HolidaySync(self)
         self.emoji = _EmojiSync(self)
+        self.naics = _NaicsSync(self)
         self.tariff = _TariffSync(self)
         self.date = _DateSync(self)
+        self.measure = _MeasureSync(self)
+        self.time = _TimeSync(self)
         self.timezone = _TimezoneSync(self)
         self.address = _AddressSync(self)
 
@@ -169,10 +173,14 @@ class ParseAPI:
 
     # Plain methods (no subresources)
 
-    def district(self, code: str, *, country: Optional[str] = None, state: Optional[str] = None) -> Json:
-        return self._get(f"/district/{_seg(code)}", {"country": country, "state": state})
+    def district(self, code: str, *, country: Optional[str] = None, state: Optional[str] = None, deep: bool = False) -> Json:
+        return self._get(f"/district/{_seg(code)}", {"country": country, "state": state, "deep": deep})
 
     def email(self, email: str, *, deep: bool = False) -> Json:
+        """Parse an email and check its format and domain. Deep explicitly requests a metered
+        deliverability check. Deep checks use one attempt by default. An explicit retry
+        count can repeat paid usage.
+        """
         return self._get(f"/email/{_seg(email)}", {"deep": deep})
 
     def vat(
@@ -183,27 +191,46 @@ class ParseAPI:
         deep: bool = False,
         from_vat: Optional[str] = None,
     ) -> Json:
+        """Check VAT format and checksum. Deep requests a metered registry check where supported. Deep
+        checks use one attempt by default. Supply your own VAT number for a consultation
+        reference when supported.
+        """
         return self._get(f"/vat/{_seg(number)}", {"country": country, "deep": deep, "from": from_vat})
 
-    def iban(self, iban: str, *, country: Optional[str] = None) -> Json:
-        return self._get(f"/iban/{_seg(iban)}", {"country": country})
+    def iban(self, iban: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return self._get(f"/iban/{_seg(iban)}", {"country": country, "deep": deep})
+
+    def bin(self, bin: str, *, deep: bool = False) -> Json:
+        """Look up a 6-11 digit card prefix, preserving leading zeros."""
+        return self._get(f"/bin/{_seg(bin)}", {"deep": deep})
 
     def npi(self, npi: str, *, deep: bool = False) -> Json:
         return self._get(f"/npi/{_seg(npi)}", {"deep": deep})
 
     def phone(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Parse a phone number and its formats. Pass country for national numbers when needed. Deep
+        adds numbering-plan geography on every plan. Carrier, caller, and HLR are separate metered lookups.
+        """
         return self._get(f"/phone/{_seg(number)}", {"country": country, "deep": deep})
 
-    def carrier(self, number: str, *, country: Optional[str] = None) -> Json:
-        return self._get(f"/carrier/{_seg(number)}", {"country": country})
+    def carrier(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Request a metered carrier lookup. No automatic retries by default.
+        """
+        return self._get(f"/carrier/{_seg(number)}", {"country": country, "deep": deep})
 
     def caller(self, number: str, *, country: Optional[str] = None) -> Json:
+        """Request a metered caller-name lookup for a NANP number. No automatic retries by default.
+        """
         return self._get(f"/caller/{_seg(number)}", {"country": country})
 
-    def hlr(self, number: str, *, country: Optional[str] = None) -> Json:
-        return self._get(f"/hlr/{_seg(number)}", {"country": country})
+    def hlr(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Look up phone status at the last check. Live means assigned and connected means reachable
+        at that check. Cached results may be returned. Null means unconfirmed. Deep adds network
+        diagnostics within the same metered lookup. No automatic retries by default."""
+        return self._get(f"/hlr/{_seg(number)}", {"country": country, "deep": deep})
 
     def domain(self, domain: str, *, deep: bool = False) -> Json:
+        """Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC on paid plans."""
         return self._get(f"/domain/{_seg(domain)}", {"deep": deep})
 
     def asn(self, asn: str) -> Json:
@@ -212,6 +239,14 @@ class ParseAPI:
     def mac(self, mac: str) -> Json:
         return self._get(f"/mac/{_seg(mac)}")
 
+    def dns(self, domain: str, *, type: str | None = None) -> Json:
+        """Published DNS records with TTLs. Omit type to check all supported types.
+
+        Type selects the question and may include its CNAME chain. Values retain
+        DNS presentation syntax, including TXT quoting. Pooled on every plan.
+        """
+        return self._get(f"/dns/{_seg(domain)}", {"type": type})
+
     def mx(self, domain: str) -> Json:
         return self._get(f"/mx/{_seg(domain)}")
 
@@ -224,19 +259,26 @@ class ParseAPI:
     def company(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
         return self._get(f"/company/{_seg(number)}", {"country": country, "deep": deep})
 
-    def language(self, code: str) -> Json:
-        return self._get(f"/language/{_seg(code)}")
+    def language(self, code: str, *, deep: bool = False) -> Json:
+        return self._get(f"/language/{_seg(code)}", {"deep": deep})
 
-    def name(self, name: str) -> Json:
-        return self._get(f"/name/{_seg(name)}")
+    def name(self, name: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Parse a name. Country is an ISO2 gender context, not nationality."""
+        return self._get(f"/name/{_seg(name)}", {"country": country, "deep": deep})
 
     def elevation(self, lat: float, lon: float) -> Json:
         return self._get("/elevation", {"lat": lat, "lon": lon})
 
     def point(self, lat: float, lon: float, *, deep: bool = False) -> Json:
+        """Resolve the country, state, district and timezone at coordinates. Deep adds terrain and
+        compact nearest-city context on every plan. The timezone ID stays in core. The nearest
+        city is null when none is within 200 km."""
         return self._get("/point", {"lat": lat, "lon": lon, "deep": deep})
 
     def weather(self, lat: float, lon: float, *, deep: bool = False, date: Optional[str] = None) -> Json:
+        """Get current conditions in metric and imperial units. Paid deep adds specialist current
+        measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-
+        MM-DD) in deep.history alongside current conditions. Date alone does not request history."""
         return self._get("/weather", {"lat": lat, "lon": lon, "deep": deep, "date": date})
 
 
@@ -245,9 +287,13 @@ class _IpSync:
         self._client = client
 
     def __call__(self, ip: str, *, deep: bool = False) -> Json:
+        """Look up an IP. Deep enrichment is included with a paid plan, without a separate check meter.
+        """
         return self._client._get(f"/ip/{_seg(ip)}", {"deep": deep})
 
     def self(self, *, deep: bool = False) -> Json:
+        """Look up the public IP making this request. On a server, this is the server's IP.
+        """
         return self._client._get("/ip", {"deep": deep})
 
 
@@ -277,8 +323,8 @@ class _CountrySync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, code: str) -> Json:
-        return self._client._get(f"/country/{_seg(code)}")
+    def __call__(self, code: str, *, deep: bool = False) -> Json:
+        return self._client._get(f"/country/{_seg(code)}", {"deep": deep})
 
     def states(self, code: str) -> Json:
         return self._client._get(f"/country/{_seg(code)}/states")
@@ -288,22 +334,22 @@ class _StateSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, code: str, *, country: Optional[str] = None) -> Json:
-        return self._client._get(f"/state/{_seg(code)}", {"country": country})
+    def __call__(self, code: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get(f"/state/{_seg(code)}", {"country": country, "deep": deep})
 
-    def districts(self, code: str, *, country: Optional[str] = None) -> Json:
-        return self._client._get(f"/state/{_seg(code)}/districts", {"country": country})
+    def districts(self, code: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get(f"/state/{_seg(code)}/districts", {"country": country, "deep": deep})
 
 
 class _CitySync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, name: str, *, country: Optional[str] = None, state: Optional[str] = None) -> Json:
-        return self._client._get(f"/city/{_seg(name)}", {"country": country, "state": state})
+    def __call__(self, name: str, *, country: Optional[str] = None, state: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get(f"/city/{_seg(name)}", {"country": country, "state": state, "deep": deep})
 
-    def id(self, id: str) -> Json:
-        return self._client._get(f"/city/id/{_seg(id)}")
+    def id(self, id: str, *, deep: bool = False) -> Json:
+        return self._client._get(f"/city/id/{_seg(id)}", {"deep": deep})
 
     def search(
         self,
@@ -312,11 +358,12 @@ class _CitySync:
         country: Optional[str] = None,
         state: Optional[str] = None,
         limit: Optional[int] = None,
+        deep: bool = False,
     ) -> Json:
-        return self._client._get("/city", {"q": query, "country": country, "state": state, "limit": limit})
+        return self._client._get("/city", {"q": query, "country": country, "state": state, "limit": limit, "deep": deep})
 
-    def nearest(self, lat: float, lon: float) -> Json:
-        return self._client._get("/city", {"lat": lat, "lon": lon})
+    def nearest(self, lat: float, lon: float, *, deep: bool = False) -> Json:
+        return self._client._get("/city", {"lat": lat, "lon": lon, "deep": deep})
 
     def nearby(
         self,
@@ -327,10 +374,11 @@ class _CitySync:
         country: Optional[str] = None,
         state: Optional[str] = None,
         limit: Optional[int] = None,
+        deep: bool = False,
     ) -> Json:
         return self._client._get(
             f"/city/{_seg(name)}/nearby",
-            {"radius": radius, "unit": unit, "country": country, "state": state, "limit": limit},
+            {"radius": radius, "unit": unit, "country": country, "state": state, "limit": limit, "deep": deep},
         )
 
 
@@ -338,8 +386,11 @@ class _PostalSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, code: str, *, country: Optional[str] = None) -> Json:
-        return self._client._get(f"/postal/{_seg(code)}", {"country": country})
+    def __call__(self, code: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Look up a postal area. Pass country when known. Check nullable coordinates before another
+        location lookup.
+        """
+        return self._client._get(f"/postal/{_seg(code)}", {"country": country, "deep": deep})
 
     def nearby(
         self,
@@ -348,19 +399,20 @@ class _PostalSync:
         country: Optional[str] = None,
         radius: Optional[float] = None,
         unit: Optional[str] = None,
+        deep: bool = False,
     ) -> Json:
-        return self._client._get(f"/postal/{_seg(code)}/nearby", {"country": country, "radius": radius, "unit": unit})
+        return self._client._get(f"/postal/{_seg(code)}/nearby", {"country": country, "radius": radius, "unit": unit, "deep": deep})
 
-    def distance(self, from_postal: str, to_postal: str, *, country: Optional[str] = None) -> Json:
-        return self._client._get(f"/postal/{_seg(from_postal)}/distance/{_seg(to_postal)}", {"country": country})
+    def distance(self, from_postal: str, to_postal: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get(f"/postal/{_seg(from_postal)}/distance/{_seg(to_postal)}", {"country": country, "deep": deep})
 
 
 class _CurrencySync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, code: str) -> Json:
-        return self._client._get(f"/currency/{_seg(code)}")
+    def __call__(self, code: str, *, deep: bool = False) -> Json:
+        return self._client._get(f"/currency/{_seg(code)}", {"deep": deep})
 
     def rate(
         self, base: str, quote_currency: str, *, date: Optional[str] = None, amount: Optional[float] = None
@@ -385,11 +437,24 @@ class _EmojiSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, emoji: str) -> Json:
-        return self._client._get(f"/emoji/{_seg(emoji)}")
+    def __call__(self, emoji: str, *, deep: bool = False) -> Json:
+        return self._client._get(f"/emoji/{_seg(emoji)}", {"deep": deep})
+
+    def search(self, query: str, *, limit: Optional[int] = None, deep: bool = False) -> Json:
+        return self._client._get("/emoji", {"q": query, "limit": limit, "deep": deep})
+
+
+class _NaicsSync:
+    def __init__(self, client: ParseAPI):
+        self._client = client
+
+    def __call__(self, code: str, *, deep: bool = False) -> Json:
+        """Look up a US NAICS 2022 code and its hierarchy."""
+        return self._client._get(f"/naics/{_seg(code)}", {"deep": deep})
 
-    def search(self, query: str, *, limit: Optional[int] = None) -> Json:
-        return self._client._get("/emoji", {"q": query, "limit": limit})
+    def search(self, query: str, *, limit: Optional[int] = None, deep: bool = False) -> Json:
+        """Search industry keywords. Limit defaults to 10 and accepts 1-50."""
+        return self._client._get("/naics", {"q": query, "limit": limit, "deep": deep})
 
 
 class _TariffSync:
@@ -397,6 +462,10 @@ class _TariffSync:
         self._client = client
 
     def __call__(self, code: str, *, deep: bool = False, origin: Optional[str] = None) -> Json:
+        """Look up the general US duty schedule line. Paid deep adds units and the special and other
+        schedule columns. Add origin with deep to resolve country-specific measures. Without
+        origin, schedule detail remains available and origin-dependent fields are null. A null
+        effective rate is not a zero rate."""
         return self._client._get(f"/tariff/{_seg(code)}", {"deep": deep, "origin": origin})
 
     def search(self, query: str) -> Json:
@@ -432,8 +501,11 @@ class AsyncParseAPI:
         self.currency = _CurrencyAsync(self)
         self.holiday = _HolidayAsync(self)
         self.emoji = _EmojiAsync(self)
+        self.naics = _NaicsAsync(self)
         self.tariff = _TariffAsync(self)
         self.date = _DateAsync(self)
+        self.measure = _MeasureAsync(self)
+        self.time = _TimeAsync(self)
         self.timezone = _TimezoneAsync(self)
         self.address = _AddressAsync(self)
 
@@ -470,10 +542,14 @@ class AsyncParseAPI:
                 continue
             raise _error_from(response)
 
-    async def district(self, code: str, *, country: Optional[str] = None, state: Optional[str] = None) -> Json:
-        return await self._get(f"/district/{_seg(code)}", {"country": country, "state": state})
+    async def district(self, code: str, *, country: Optional[str] = None, state: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._get(f"/district/{_seg(code)}", {"country": country, "state": state, "deep": deep})
 
     async def email(self, email: str, *, deep: bool = False) -> Json:
+        """Parse an email and check its format and domain. Deep explicitly requests a metered
+        deliverability check. Deep checks use one attempt by default. An explicit retry
+        count can repeat paid usage.
+        """
         return await self._get(f"/email/{_seg(email)}", {"deep": deep})
 
     async def vat(
@@ -484,27 +560,46 @@ class AsyncParseAPI:
         deep: bool = False,
         from_vat: Optional[str] = None,
     ) -> Json:
+        """Check VAT format and checksum. Deep requests a metered registry check where supported. Deep
+        checks use one attempt by default. Supply your own VAT number for a consultation
+        reference when supported.
+        """
         return await self._get(f"/vat/{_seg(number)}", {"country": country, "deep": deep, "from": from_vat})
 
-    async def iban(self, iban: str, *, country: Optional[str] = None) -> Json:
-        return await self._get(f"/iban/{_seg(iban)}", {"country": country})
+    async def iban(self, iban: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._get(f"/iban/{_seg(iban)}", {"country": country, "deep": deep})
+
+    async def bin(self, bin: str, *, deep: bool = False) -> Json:
+        """Look up a 6-11 digit card prefix, preserving leading zeros."""
+        return await self._get(f"/bin/{_seg(bin)}", {"deep": deep})
 
     async def npi(self, npi: str, *, deep: bool = False) -> Json:
         return await self._get(f"/npi/{_seg(npi)}", {"deep": deep})
 
     async def phone(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Parse a phone number and its formats. Pass country for national numbers when needed. Deep
+        adds numbering-plan geography on every plan. Carrier, caller, and HLR are separate metered lookups.
+        """
         return await self._get(f"/phone/{_seg(number)}", {"country": country, "deep": deep})
 
-    async def carrier(self, number: str, *, country: Optional[str] = None) -> Json:
-        return await self._get(f"/carrier/{_seg(number)}", {"country": country})
+    async def carrier(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Request a metered carrier lookup. No automatic retries by default.
+        """
+        return await self._get(f"/carrier/{_seg(number)}", {"country": country, "deep": deep})
 
     async def caller(self, number: str, *, country: Optional[str] = None) -> Json:
+        """Request a metered caller-name lookup for a NANP number. No automatic retries by default.
+        """
         return await self._get(f"/caller/{_seg(number)}", {"country": country})
 
-    async def hlr(self, number: str, *, country: Optional[str] = None) -> Json:
-        return await self._get(f"/hlr/{_seg(number)}", {"country": country})
+    async def hlr(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Look up phone status at the last check. Live means assigned and connected means reachable
+        at that check. Cached results may be returned. Null means unconfirmed. Deep adds network
+        diagnostics within the same metered lookup. No automatic retries by default."""
+        return await self._get(f"/hlr/{_seg(number)}", {"country": country, "deep": deep})
 
     async def domain(self, domain: str, *, deep: bool = False) -> Json:
+        """Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC on paid plans."""
         return await self._get(f"/domain/{_seg(domain)}", {"deep": deep})
 
     async def asn(self, asn: str) -> Json:
@@ -513,6 +608,14 @@ class AsyncParseAPI:
     async def mac(self, mac: str) -> Json:
         return await self._get(f"/mac/{_seg(mac)}")
 
+    async def dns(self, domain: str, *, type: str | None = None) -> Json:
+        """Published DNS records with TTLs. Omit type to check all supported types.
+
+        Type selects the question and may include its CNAME chain. Values retain
+        DNS presentation syntax, including TXT quoting. Pooled on every plan.
+        """
+        return await self._get(f"/dns/{_seg(domain)}", {"type": type})
+
     async def mx(self, domain: str) -> Json:
         return await self._get(f"/mx/{_seg(domain)}")
 
@@ -525,19 +628,26 @@ class AsyncParseAPI:
     async def company(self, number: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
         return await self._get(f"/company/{_seg(number)}", {"country": country, "deep": deep})
 
-    async def language(self, code: str) -> Json:
-        return await self._get(f"/language/{_seg(code)}")
+    async def language(self, code: str, *, deep: bool = False) -> Json:
+        return await self._get(f"/language/{_seg(code)}", {"deep": deep})
 
-    async def name(self, name: str) -> Json:
-        return await self._get(f"/name/{_seg(name)}")
+    async def name(self, name: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Parse a name. Country is an ISO2 gender context, not nationality."""
+        return await self._get(f"/name/{_seg(name)}", {"country": country, "deep": deep})
 
     async def elevation(self, lat: float, lon: float) -> Json:
         return await self._get("/elevation", {"lat": lat, "lon": lon})
 
     async def point(self, lat: float, lon: float, *, deep: bool = False) -> Json:
+        """Resolve the country, state, district and timezone at coordinates. Deep adds terrain and
+        compact nearest-city context on every plan. The timezone ID stays in core. The nearest
+        city is null when none is within 200 km."""
         return await self._get("/point", {"lat": lat, "lon": lon, "deep": deep})
 
     async def weather(self, lat: float, lon: float, *, deep: bool = False, date: Optional[str] = None) -> Json:
+        """Get current conditions in metric and imperial units. Paid deep adds specialist current
+        measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-
+        MM-DD) in deep.history alongside current conditions. Date alone does not request history."""
         return await self._get("/weather", {"lat": lat, "lon": lon, "deep": deep, "date": date})
 
 
@@ -546,9 +656,13 @@ class _IpAsync:
         self._client = client
 
     async def __call__(self, ip: str, *, deep: bool = False) -> Json:
+        """Look up an IP. Deep enrichment is included with a paid plan, without a separate check meter.
+        """
         return await self._client._get(f"/ip/{_seg(ip)}", {"deep": deep})
 
     async def self(self, *, deep: bool = False) -> Json:
+        """Look up the public IP making this request. On a server, this is the server's IP.
+        """
         return await self._client._get("/ip", {"deep": deep})
 
 
@@ -578,8 +692,8 @@ class _CountryAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, code: str) -> Json:
-        return await self._client._get(f"/country/{_seg(code)}")
+    async def __call__(self, code: str, *, deep: bool = False) -> Json:
+        return await self._client._get(f"/country/{_seg(code)}", {"deep": deep})
 
     async def states(self, code: str) -> Json:
         return await self._client._get(f"/country/{_seg(code)}/states")
@@ -589,22 +703,22 @@ class _StateAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, code: str, *, country: Optional[str] = None) -> Json:
-        return await self._client._get(f"/state/{_seg(code)}", {"country": country})
+    async def __call__(self, code: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get(f"/state/{_seg(code)}", {"country": country, "deep": deep})
 
-    async def districts(self, code: str, *, country: Optional[str] = None) -> Json:
-        return await self._client._get(f"/state/{_seg(code)}/districts", {"country": country})
+    async def districts(self, code: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get(f"/state/{_seg(code)}/districts", {"country": country, "deep": deep})
 
 
 class _CityAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, name: str, *, country: Optional[str] = None, state: Optional[str] = None) -> Json:
-        return await self._client._get(f"/city/{_seg(name)}", {"country": country, "state": state})
+    async def __call__(self, name: str, *, country: Optional[str] = None, state: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get(f"/city/{_seg(name)}", {"country": country, "state": state, "deep": deep})
 
-    async def id(self, id: str) -> Json:
-        return await self._client._get(f"/city/id/{_seg(id)}")
+    async def id(self, id: str, *, deep: bool = False) -> Json:
+        return await self._client._get(f"/city/id/{_seg(id)}", {"deep": deep})
 
     async def search(
         self,
@@ -613,11 +727,12 @@ class _CityAsync:
         country: Optional[str] = None,
         state: Optional[str] = None,
         limit: Optional[int] = None,
+        deep: bool = False,
     ) -> Json:
-        return await self._client._get("/city", {"q": query, "country": country, "state": state, "limit": limit})
+        return await self._client._get("/city", {"q": query, "country": country, "state": state, "limit": limit, "deep": deep})
 
-    async def nearest(self, lat: float, lon: float) -> Json:
-        return await self._client._get("/city", {"lat": lat, "lon": lon})
+    async def nearest(self, lat: float, lon: float, *, deep: bool = False) -> Json:
+        return await self._client._get("/city", {"lat": lat, "lon": lon, "deep": deep})
 
     async def nearby(
         self,
@@ -628,10 +743,11 @@ class _CityAsync:
         country: Optional[str] = None,
         state: Optional[str] = None,
         limit: Optional[int] = None,
+        deep: bool = False,
     ) -> Json:
         return await self._client._get(
             f"/city/{_seg(name)}/nearby",
-            {"radius": radius, "unit": unit, "country": country, "state": state, "limit": limit},
+            {"radius": radius, "unit": unit, "country": country, "state": state, "limit": limit, "deep": deep},
         )
 
 
@@ -639,8 +755,11 @@ class _PostalAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, code: str, *, country: Optional[str] = None) -> Json:
-        return await self._client._get(f"/postal/{_seg(code)}", {"country": country})
+    async def __call__(self, code: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        """Look up a postal area. Pass country when known. Check nullable coordinates before another
+        location lookup.
+        """
+        return await self._client._get(f"/postal/{_seg(code)}", {"country": country, "deep": deep})
 
     async def nearby(
         self,
@@ -649,21 +768,22 @@ class _PostalAsync:
         country: Optional[str] = None,
         radius: Optional[float] = None,
         unit: Optional[str] = None,
+        deep: bool = False,
     ) -> Json:
         return await self._client._get(
-            f"/postal/{_seg(code)}/nearby", {"country": country, "radius": radius, "unit": unit}
+            f"/postal/{_seg(code)}/nearby", {"country": country, "radius": radius, "unit": unit, "deep": deep}
         )
 
-    async def distance(self, from_postal: str, to_postal: str, *, country: Optional[str] = None) -> Json:
-        return await self._client._get(f"/postal/{_seg(from_postal)}/distance/{_seg(to_postal)}", {"country": country})
+    async def distance(self, from_postal: str, to_postal: str, *, country: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get(f"/postal/{_seg(from_postal)}/distance/{_seg(to_postal)}", {"country": country, "deep": deep})
 
 
 class _CurrencyAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, code: str) -> Json:
-        return await self._client._get(f"/currency/{_seg(code)}")
+    async def __call__(self, code: str, *, deep: bool = False) -> Json:
+        return await self._client._get(f"/currency/{_seg(code)}", {"deep": deep})
 
     async def rate(
         self, base: str, quote_currency: str, *, date: Optional[str] = None, amount: Optional[float] = None
@@ -688,11 +808,24 @@ class _EmojiAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, emoji: str) -> Json:
-        return await self._client._get(f"/emoji/{_seg(emoji)}")
+    async def __call__(self, emoji: str, *, deep: bool = False) -> Json:
+        return await self._client._get(f"/emoji/{_seg(emoji)}", {"deep": deep})
+
+    async def search(self, query: str, *, limit: Optional[int] = None, deep: bool = False) -> Json:
+        return await self._client._get("/emoji", {"q": query, "limit": limit, "deep": deep})
+
+
+class _NaicsAsync:
+    def __init__(self, client: AsyncParseAPI):
+        self._client = client
+
+    async def __call__(self, code: str, *, deep: bool = False) -> Json:
+        """Look up a US NAICS 2022 code and its hierarchy."""
+        return await self._client._get(f"/naics/{_seg(code)}", {"deep": deep})
 
-    async def search(self, query: str, *, limit: Optional[int] = None) -> Json:
-        return await self._client._get("/emoji", {"q": query, "limit": limit})
+    async def search(self, query: str, *, limit: Optional[int] = None, deep: bool = False) -> Json:
+        """Search industry keywords. Limit defaults to 10 and accepts 1-50."""
+        return await self._client._get("/naics", {"q": query, "limit": limit, "deep": deep})
 
 
 class _TariffAsync:
@@ -700,6 +833,10 @@ class _TariffAsync:
         self._client = client
 
     async def __call__(self, code: str, *, deep: bool = False, origin: Optional[str] = None) -> Json:
+        """Look up the general US duty schedule line. Paid deep adds units and the special and other
+        schedule columns. Add origin with deep to resolve country-specific measures. Without
+        origin, schedule detail remains available and origin-dependent fields are null. A null
+        effective rate is not a zero rate."""
         return await self._client._get(f"/tariff/{_seg(code)}", {"deep": deep, "origin": origin})
 
     async def search(self, query: str) -> Json:
@@ -710,33 +847,46 @@ class _DateSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, date: str, *, format: Optional[str] = None, to: Optional[str] = None) -> Json:
-        return self._client._get(f"/date/{_seg(date)}", {"format": format, "to": to})
+    def __call__(self, date: str, *, format: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get(f"/date/{_seg(date)}", {"format": format, "to": to, "deep": deep})
 
-    def today(self, *, to: Optional[str] = None) -> Json:
-        return self._client._get("/date", {"to": to})
+    def today(self, *, to: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get("/date", {"to": to, "deep": deep})
 
 
 class _DateAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, date: str, *, format: Optional[str] = None, to: Optional[str] = None) -> Json:
-        return await self._client._get(f"/date/{_seg(date)}", {"format": format, "to": to})
+    async def __call__(self, date: str, *, format: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get(f"/date/{_seg(date)}", {"format": format, "to": to, "deep": deep})
+
+    async def today(self, *, to: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get("/date", {"to": to, "deep": deep})
+
+
+class _TimeSync:
+    def __init__(self, client: ParseAPI):
+        self._client = client
 
-    async def today(self, *, to: Optional[str] = None) -> Json:
-        return await self._client._get("/date", {"to": to})
+    def __call__(self, timezone: Optional[str] = None, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        """Current local time, UTC by default. With to, offsetless at is source wall time."""
+        path = "/time" if timezone is None else f"/time/{_seg(timezone)}"
+        return self._client._get(path, {"at": at, "to": to, "deep": deep})
+
+    def at(self, lat: float, lon: float, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get("/time", {"lat": lat, "lon": lon, "at": at, "to": to, "deep": deep})
 
 
 class _TimezoneSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, id: str, *, at: Optional[str] = None, to: Optional[str] = None) -> Json:
-        return self._client._get(f"/timezone/{_seg(id)}", {"at": at, "to": to})
+    def __call__(self, id: str, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get(f"/timezone/{_seg(id)}", {"at": at, "to": to, "deep": deep})
 
-    def at(self, lat: float, lon: float, *, at: Optional[str] = None) -> Json:
-        return self._client._get("/timezone", {"lat": lat, "lon": lon, "at": at})
+    def at(self, lat: float, lon: float, *, at: Optional[str] = None, deep: bool = False) -> Json:
+        return self._client._get("/timezone", {"lat": lat, "lon": lon, "at": at, "deep": deep})
 
 
 class _AddressSync:
@@ -748,18 +898,35 @@ class _AddressSync:
 
     def search(self, query: str, *, country: Optional[str] = None, postal: Optional[str] = None,
         city: Optional[str] = None, state: Optional[str] = None, ip: Optional[str] = None) -> Json:
+        """Find address suggestions using the context supplied. Prefer postal, or city and state,
+        from the form. ip is an optional end-user locality hint for server-side calls. An empty
+        result has reason more_input, missing_context or no_matches. Suggestions have reason null.
+        Operational failures are errors."""
         return self._client._get("/address", {"q": query, "country": country, "postal": postal, "city": city, "state": state, "ip": ip})
 
 
+class _TimeAsync:
+    def __init__(self, client: AsyncParseAPI):
+        self._client = client
+
+    async def __call__(self, timezone: Optional[str] = None, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        """Current local time, UTC by default. With to, offsetless at is source wall time."""
+        path = "/time" if timezone is None else f"/time/{_seg(timezone)}"
+        return await self._client._get(path, {"at": at, "to": to, "deep": deep})
+
+    async def at(self, lat: float, lon: float, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get("/time", {"lat": lat, "lon": lon, "at": at, "to": to, "deep": deep})
+
+
 class _TimezoneAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, id: str, *, at: Optional[str] = None, to: Optional[str] = None) -> Json:
-        return await self._client._get(f"/timezone/{_seg(id)}", {"at": at, "to": to})
+    async def __call__(self, id: str, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get(f"/timezone/{_seg(id)}", {"at": at, "to": to, "deep": deep})
 
-    async def at(self, lat: float, lon: float, *, at: Optional[str] = None) -> Json:
-        return await self._client._get("/timezone", {"lat": lat, "lon": lon, "at": at})
+    async def at(self, lat: float, lon: float, *, at: Optional[str] = None, deep: bool = False) -> Json:
+        return await self._client._get("/timezone", {"lat": lat, "lon": lon, "at": at, "deep": deep})
 
 
 class _AddressAsync:
@@ -771,4 +938,40 @@ class _AddressAsync:
 
     async def search(self, query: str, *, country: Optional[str] = None, postal: Optional[str] = None,
         city: Optional[str] = None, state: Optional[str] = None, ip: Optional[str] = None) -> Json:
+        """Find address suggestions using the context supplied. Prefer postal, or city and state,
+        from the form. ip is an optional end-user locality hint for server-side calls. An empty
+        result has reason more_input, missing_context or no_matches. Suggestions have reason null.
+        Operational failures are errors."""
         return await self._client._get("/address", {"q": query, "country": country, "postal": postal, "city": city, "state": state, "ip": ip})
+
+
+class _MeasureSync:
+    def __init__(self, client: ParseAPI):
+        self._client = client
+
+    def __call__(self, measure: str, *, to: Optional[str] = None, locale: Optional[str] = None, system: Optional[str] = None) -> Json:
+        """Parse or convert a measurement. Amount is a decimal string. Without to, use the
+        type's canonical unit. Locale and system (us or imperial) resolve explicit ambiguity.
+        Invalid measurements return valid=False and a reason. Invalid targets raise an API error.
+        """
+        return self._client._get(f"/measure/{_seg(measure)}", {"to": to, "locale": locale, "system": system})
+
+    def units(self, *, query: Optional[str] = None, type: Optional[str] = None, unit: Optional[str] = None) -> Json:
+        """Discover reviewed units. unit filters compatible conversion targets."""
+        return self._client._get("/measure/units", {"q": query, "type": type, "unit": unit})
+
+
+class _MeasureAsync:
+    def __init__(self, client: AsyncParseAPI):
+        self._client = client
+
+    async def __call__(self, measure: str, *, to: Optional[str] = None, locale: Optional[str] = None, system: Optional[str] = None) -> Json:
+        """Parse or convert a measurement. Amount is a decimal string. Without to, use the
+        type's canonical unit. Locale and system (us or imperial) resolve explicit ambiguity.
+        Invalid measurements return valid=False and a reason. Invalid targets raise an API error.
+        """
+        return await self._client._get(f"/measure/{_seg(measure)}", {"to": to, "locale": locale, "system": system})
+
+    async def units(self, *, query: Optional[str] = None, type: Optional[str] = None, unit: Optional[str] = None) -> Json:
+        """Discover reviewed units. unit filters compatible conversion targets."""
+        return await self._client._get("/measure/units", {"q": query, "type": type, "unit": unit})

parseapi-0.4.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.5
+Name: parseapi
+Version: 0.4.0
+Summary: Official ParseAPI client for Python. One key, minimal JSON, fast.
+Project-URL: Homepage, https://parseapi.com
+Project-URL: Documentation, https://parseapi.com/docs
+Project-URL: Repository, https://github.com/parseapi/python
+Author-email: ParseAPI <hello@parseapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: currency,email validation,geolocation,ip,parseapi,phone validation,postal,timezone,weather
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# parseapi
+
+Official ParseAPI client for Python.
+
+```bash
+pip install parseapi
+```
+
+```python
+from parseapi import ParseAPI
+
+parse = ParseAPI("your-api-key")
+country = parse.country("US")
+```
+
+Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEAPI_KEY` from the environment.
+
+## API versions
+
+Choose your team's API version in [Dashboard → API version](https://parseapi.com/dashboard/versions). One setting applies to every key, including new and replacement keys. Existing teams keep `1.0.0`; new teams start on `2.0.0`. Keep the same keys and lookup URLs. Installing or upgrading the package does not change the team's setting.
+
+Published SDK `0.3.2` matches API `1.0.0`. The examples and response types in this source tree target API `2.0.0`, including changes that are not in `0.3.2`. Use a package release documented for your team's version. These types do not model every historical response; moving to `2.0.0` may require updating code that reads renamed, moved or removed fields.
+
+Test the target contract in a separate development team before changing your production team's version. A change applies to every integration in that team. See [API versions and migration](https://parseapi.com/docs/versioning).
+
+## Weather from a postal code
+
+Start with the postal code, then pass its coordinates to weather. Reuse the client from the example above.
+
+```python
+place = parse.postal("28202", country="US")
+lat, lon = place["latitude"], place["longitude"]
+if lat is not None and lon is not None:
+    weather = parse.weather(lat, lon)
+    print(weather)
+```
+
+The coordinates represent the postal area. Weather is for that point. Missing coordinates skip the weather lookup. This composition performs two ordinary lookups when coordinates are available, with the retry policy below.
+
+## Supply the context you know
+
+Pass `country` when a postal code or national phone number needs disambiguation. A complete international phone number already carries its country context. For a numeric date such as `03/04/2026`, supply the intended `format`. Defaults resolve what the input establishes. Ambiguous input needs your context.
+
+Results are plain data. Pass a returned code or coordinate to another operation when the task needs it. Check nullable values before composing the next call.
+
+Use `parse.postal("28202", country="US", deep=True)` for US ZIP tax references. `deep.tax` names the levy and `deep.tax_rate` is a percentage, so `7.9` means 7.9%. The state, county, city and special components explain that combined rate. An exact address can differ. Country and state lookups provide their own geographic reference rates, which should not be added to the ZIP rate. `None` means unknown and `0` means known zero. Country `deep.tax_id_format` and `deep.tax_id_regex` describe registration-number format only. Use `vat` for a metered registration check with `deep` explicitly enabled.
+
+## Calls
+
+One method per endpoint, named after the route.
+
+```python
+parse.ip("8.8.8.8")
+parse.ip.self()
+parse.email("hello@gmail.com")
+parse.vat("DE136695976")
+parse.iban("DE89370400440532013000")
+parse.bin("424242")
+parse.npi("1881018208")
+parse.phone("+14155552671")
+parse.carrier("+14155552671")
+parse.caller("+14155552671")
+parse.hlr("+14155552671")
+parse.postal("SW1A 1AA")
+parse.postal("28202", country="US")
+parse.postal.nearby("28202", country="US", radius=40)
+parse.postal.distance("28202", "10001", country="US")
+parse.address("1600 Pennsylvania Ave NW, Washington DC", country="US")
+parse.address.search("1600 Pennsylvania", country="US", postal="20500")
+parse.company("51 824 753 556", country="AU")
+parse.city("charlotte", country="US")
+parse.city.id("city_mb8mbqrkz8zb")
+parse.city.search("char", country="US", limit=10)
+parse.city.nearest(35.2271, -80.8431)
+parse.city.nearby("denver", radius=8, unit="mi")
+parse.country("US")
+parse.country.states("US")
+parse.state("colorado")
+parse.state("NC", country="US")
+parse.state.districts("NC", country="US")
+parse.district("37081")
+parse.continent("NA")
+parse.continent.countries("NA")
+parse.bloc("EU")
+parse.bloc.countries("EU")
+parse.currency("USD")
+parse.currency.rate("USD", "EUR")
+parse.language("en")
+parse.name("BILLY OSHALL")
+parse.name("Andrea", country="IT", deep=True)
+parse.time()  # UTC now
+parse.time("America/New_York")
+parse.time("America/New_York", at="2026-09-05T15:00:00", to="Europe/London")
+parse.time.at(39.77, -104.9)
+parse.date("03/04/2026", format="mdy")
+parse.date.today()
+parse.holiday("US", year=2026)
+parse.holiday.date("US", "2026-12-25")
+parse.elevation(35.2271, -80.8431)
+parse.point(36.0726, -79.792)
+parse.weather(40.7128, -74.006)
+parse.domain("example.com")
+parse.asn("AS13335")
+parse.mac("00:1B:63:84:45:E6")
+parse.mx("example.com")
+parse.dns("example.com")
+parse.dns("_dmarc.example.com", type="TXT")
+parse.useragent(ua_string)
+parse.vin("1HGCM82633A004352")
+parse.naics("541511")
+parse.naics.search("coffee shop", limit=5)
+parse.tariff("8471.30.01.00")
+parse.tariff.search("sunglasses")
+parse.emoji("rocket")
+parse.emoji.search("fire")
+```
+
+NAICS paid deep records include classification `deep.exclusions`, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include `match`: the matched `field` (`name`, `term` or `naics`) and `text`, plus `corrections` with `from` and `to` tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit `match`. Older responses may omit it.
+
+Responses are plain dicts, exactly the JSON the API returns. `country.states("US")` requests states directly; it does not fetch a country first. Required inputs are positional and optional behavior uses keyword arguments, leaving room for new options without changing existing calls. Reuse a client across calls. Use `with ParseAPI(...) as parse:` or call `parse.close()` when finished.
+
+DNS uses pooled requests on every plan. Omit `type` to check A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, SRV and PTR. Records contain `name`, `type`, `ttl` in seconds and a DNS presentation `value`. TXT values retain quoting and chunk boundaries. A selected question can include its CNAME chain. Empty records mean no records. Lookup failures remain errors.
+
+## Async
+
+Same lookup methods and keyword arguments, with `await`. Use a context manager to close the client when the work is done.
+
+```python
+from parseapi import AsyncParseAPI
+
+async with AsyncParseAPI("your-api-key") as parse:
+    country = await parse.country("US")
+```
+
+## Time
+
+`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+
+## Measurements
+
+```python
+result = parse.measure("5 ft 11 in", to="cm")
+units = parse.measure.units(unit="m")
+```
+
+`amount` is a decimal string, such as `"180.34"`. Without `to`, the API returns the canonical unit for the measurement type. Pass `locale` for number formatting and `system` (`us` or `imperial`) when a customary unit needs context. Ambiguous input returns `valid: false`, a `reason`, and available `choices`. Invalid or incompatible target units use the normal API error.
+
+Unit discovery accepts optional `query`, `type`, and `unit` filters. `unit` selects compatible targets. Omit the filters for the reviewed catalog. Both operations use pooled requests.
+
+## Place statistics and optional detail
+
+Postal and District paid profiles include `deep.property_tax` where supported. It contains `annual_median`, `currency` and `period`: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (`YYYY-YYYY`). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
+
+```python
+place = parse.postal("28202", country="US", deep=True)
+property_tax = (place.get("deep") or {}).get("property_tax")
+```
+
+Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population and its period remain in core.
+
+Point returns the timezone ID with the core location. Its optional deep detail adds terrain and compact nearest-city context on every plan. A nearest city is null when none is within 200 km.
+
+Weather returns current conditions by default. Paid deep adds specialist current measurements, forecasts and related detail. A past `date` is a UTC day and requires deep: it adds `deep.history` alongside current conditions. Date alone does not request history.
+
+```python
+parse.weather(40.7128, -74.006, deep=True, date="2026-08-15")
+```
+
+Tariff starts with the general schedule line. Paid deep adds units and the special and other schedule columns. An optional origin then resolves country-specific measures. The three calls below show those successive choices. Without origin, schedule detail is still returned and origin-dependent fields are null. A null effective rate is not a zero rate.
+
+```python
+parse.tariff("8471.30.01.00")
+parse.tariff("8471.30.01.00", deep=True)
+parse.tariff("8471.30.01.00", deep=True, origin="CN")
+```
+
+Address search uses context from the form: prefer postal, or city and state. An optional end-user `ip` is a locality hint for server-side calls. An empty result explains itself with `reason`: `more_input`, `missing_context` or `no_matches`. With suggestions, reason is null. Older responses may omit it, and future reasons remain strings. Catalog and lookup failures use the existing API errors.
+
+HLR reports status at the last check. `live` means assigned and `connected` means reachable at that check. Cached results may be returned. Null means unconfirmed. Deep diagnostics stay within the same metered lookup.
+
+## Deep
+
+Choose enrichment for the question you need answered.
+
+| Operation | What `deep` requests |
+|---|---|
+| IP | Richer IP fields included with a paid plan. No separate check meter. |
+| Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use `dns` for DNS records and `mx` for mail routing. |
+| Email | A metered deliverability check, using included email checks or enabled on-demand usage. |
+| VAT | A metered registry check where supported, using included VAT checks or enabled on-demand usage. |
+| Phone, Time, Date, Currency, Language, Emoji, IBAN, Point | Optional detail in the same pooled request on every plan. |
+| Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
+| Name, NAICS | Name evidence or the industry definition profile on paid plans. |
+| VIN, NPI, Tariff, Company | The complete product detail bag on paid plans. |
+| Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
+| Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
+
+Carrier, caller, and HLR are separate metered operations. Choose them explicitly when you need their answers. Ordinary lookups retry twice by default. Metered checks use one attempt by default. Setting retries explicitly can repeat paid usage.
+
+Without `deep`, the response omits that key. When requested, it is an empty object if access is locked or the operation has no deep fields. Otherwise it contains the available fields. A missing or null field means unknown.
+
+```python
+ip = parse.ip("52.94.76.10", deep=True)
+ip.get("deep", {}).get("datacenter")  # True, False, or None
+```
+
+## Errors
+
+Every non-2xx response raises `ParseAPIError` with `status`, `code`, `docs`, and `request_id`. Branch on `code`.
+
+```python
+from parseapi import ParseAPIError
+
+try:
+    parse.city("atlantis")
+except ParseAPIError as err:
+    if err.code == "not_found":
+        ...  # no such city
+```
+
+Network and decoding failures keep their native error types. Responses such as `valid: false` are successful API answers, not exceptions.
+
+## Options
+
+```python
+parse = ParseAPI(
+    "your-api-key",
+    timeout=10.0,  # timeout for each connect, read, write, or pool phase
+)
+```
+
+Requires Python 3.9 or later. One dependency (httpx).
+
+Ordinary lookups retry network failures, 429, and 500/502/503/504 responses twice by default. Carrier, caller, HLR, and email or VAT with `deep=True` make one attempt by default. Address with `deep=True` also uses one attempt, reserving the same behavior for future verification.
+
+An explicit client `retries` setting overrides those defaults; `retries=0` always makes one attempt. Another attempt can consume additional usage if the earlier response was lost. Cancelling an async task stops the call and any retry wait. Automatic redirects are disabled.
+
+## Docs
+
+Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)
+
+BIN lookup accepts 6-11 digits as a string, including leading zeros. Spaces and hyphens are accepted. `prefix` is the actual longest match and can be shorter than the input. Unknown reference fields are null. `deep` adds an empty object on every plan.
+
+
+## Optional detail
+
+The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, NAICS and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
+
+```python
+basic = parse.time("America/New_York")
+detail = parse.time("America/New_York", deep=True)
+print(basic["at"], detail.get("deep", {}).get("next_dst"))
+```

parseapi-0.4.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+parseapi/__init__.py,sha256=SId1i8NW8kO5uuh4j-UeLcd2Smo6luEYiOdYWPiioZQ,199
+parseapi/_client.py,sha256=yfQCvENzLFIQ2WJjOPZHUeSSC6D7jaL_HtOYCtXAxVU,42523
+parseapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+parseapi-0.4.0.dist-info/METADATA,sha256=GlA4b9aLP-83ZIFtqQmD93LHUX1xy8PawCkdmw2kVeM,15212
+parseapi-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+parseapi-0.4.0.dist-info/licenses/LICENSE,sha256=3IF5YNQQ6vF8sAs9hGRcovgEetJuzSwKqoE1TXLMoRs,1065
+parseapi-0.4.0.dist-info/RECORD,,

parseapi-0.3.2.dist-info/METADATA

@@ -1,155 +0,0 @@
-Metadata-Version: 2.5
-Name: parseapi
-Version: 0.3.2
-Summary: Official ParseAPI client for Python. One key, minimal JSON, fast.
-Project-URL: Homepage, https://parseapi.com
-Project-URL: Documentation, https://parseapi.com/docs
-Project-URL: Repository, https://github.com/parseapi/python
-Author-email: ParseAPI <hello@parseapi.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: currency,email validation,geolocation,ip,parseapi,phone validation,postal,timezone,weather
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
-Requires-Dist: httpx>=0.24
-Description-Content-Type: text/markdown
-
-# parseapi
-
-Official ParseAPI client for Python.
-
-```bash
-pip install parseapi
-```
-
-```python
-from parseapi import ParseAPI
-
-parse = ParseAPI("your-api-key")
-country = parse.country("US")
-```
-
-Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEAPI_KEY` from the environment.
-
-## Calls
-
-One method per endpoint, named after the route.
-
-```python
-parse.ip("8.8.8.8")
-parse.ip.self()
-parse.email("hello@gmail.com")
-parse.vat("DE136695976")
-parse.iban("DE89370400440532013000")
-parse.npi("1881018208")
-parse.phone("+14155552671")
-parse.carrier("+14155552671")
-parse.caller("+14155552671")
-parse.hlr("+14155552671")
-parse.postal("SW1A 1AA")
-parse.postal("28202", country="US")
-parse.postal.nearby("28202", country="US", radius=40)
-parse.postal.distance("28202", "10001", country="US")
-parse.address("1600 Pennsylvania Ave NW, Washington DC", country="US")
-parse.address.search("1600 Pennsylvania", country="US", postal="20500")
-parse.company("51 824 753 556", country="AU")
-parse.city("charlotte", country="US")
-parse.city.id("city_mb8mbqrkz8zb")
-parse.city.search("char", country="US", limit=10)
-parse.city.nearest(35.2271, -80.8431)
-parse.city.nearby("denver", radius=8, unit="mi")
-parse.country("US")
-parse.country.states("US")
-parse.state("colorado")
-parse.state("NC", country="US")
-parse.state.districts("NC", country="US")
-parse.district("37081")
-parse.continent("NA")
-parse.continent.countries("NA")
-parse.bloc("EU")
-parse.bloc.countries("EU")
-parse.currency("USD")
-parse.currency.rate("USD", "EUR")
-parse.language("en")
-parse.name("BILLY OSHALL")
-parse.timezone("America/New_York")
-parse.timezone("America/New_York", at="2026-09-05T15:00:00", to="Europe/London")
-parse.timezone.at(39.77, -104.9)
-parse.date("03/04/2026", format="mdy")
-parse.date.today()
-parse.holiday("US", year=2026)
-parse.holiday.date("US", "2026-12-25")
-parse.elevation(35.2271, -80.8431)
-parse.point(36.0726, -79.792)
-parse.weather(40.7128, -74.006)
-parse.domain("example.com")
-parse.asn("AS13335")
-parse.mac("00:1B:63:84:45:E6")
-parse.mx("example.com")
-parse.useragent(ua_string)
-parse.vin("1HGCM82633A004352")
-parse.tariff("8471.30.01.00")
-parse.tariff.search("sunglasses")
-parse.emoji("rocket")
-parse.emoji.search("fire")
-```
-
-Responses are plain dicts, exactly the JSON the API returns. `country.states("US")` requests states directly; it does not fetch a country first. Required inputs are positional and optional behavior uses keyword arguments, leaving room for new options without changing existing calls. Reuse a client across calls. Use `with ParseAPI(...) as parse:` or call `parse.close()` when finished.
-
-## Async
-
-Same lookup methods and keyword arguments, with `await`. Use a context manager to close the client when the work is done.
-
-```python
-from parseapi import AsyncParseAPI
-
-async with AsyncParseAPI("your-api-key") as parse:
-    country = await parse.country("US")
-```
-
-## Deep
-
-Pass `deep=True` to include the nested `deep` object with richer fields.
-
-```python
-ip = parse.ip("52.94.76.10", deep=True)
-ip["deep"]["datacenter"]  # True
-```
-
-## Errors
-
-Every non-2xx response raises `ParseAPIError` with `status`, `code`, `docs`, and `request_id`. Branch on `code`.
-
-```python
-from parseapi import ParseAPIError
-
-try:
-    parse.city("atlantis")
-except ParseAPIError as err:
-    if err.code == "not_found":
-        ...  # no such city
-```
-
-Network and decoding failures keep their native error types. Responses such as `valid: false` are successful API answers, not exceptions.
-
-## Options
-
-```python
-parse = ParseAPI(
-    "your-api-key",
-    timeout=10.0,  # timeout for each connect, read, write, or pool phase
-)
-```
-
-Requires Python 3.9 or later. One dependency (httpx).
-
-Ordinary lookups retry network failures, 429, and 500/502/503/504 responses twice by default. Carrier, caller, HLR, and email or VAT with `deep=True` make one attempt by default. Address with `deep=True` also uses one attempt, reserving the same behavior for future verification.
-
-An explicit client `retries` setting overrides those defaults; `retries=0` always makes one attempt. Another attempt can consume additional usage if the earlier response was lost. Cancelling an async task stops the call and any retry wait. Automatic redirects are disabled.
-
-## Docs
-
-Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)

parseapi-0.3.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-parseapi/__init__.py,sha256=K26G0Ln_MpBNehukrxXzNqpfhs6a_ln0UPH5jQut4KQ,199
-parseapi/_client.py,sha256=n6wcmuqP8eOEWaxxWk2p7qBF1OZfye3yWZuFs5DRNWI,28816
-parseapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-parseapi-0.3.2.dist-info/METADATA,sha256=_V4PWtBMcwU-nYgmbigCGrbrA4vjSFFNqPb1Lblx3aU,5108
-parseapi-0.3.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-parseapi-0.3.2.dist-info/licenses/LICENSE,sha256=3IF5YNQQ6vF8sAs9hGRcovgEetJuzSwKqoE1TXLMoRs,1065
-parseapi-0.3.2.dist-info/RECORD,,