prismadata 0.7.0__tar.gz → 0.8.0__tar.gz

{prismadata-0.7.0 → prismadata-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prismadata
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python client for the PrismaData location intelligence API
 License: MIT
 License-File: LICENSE

{prismadata-0.7.0 → prismadata-0.8.0}/prismadata/__init__.py

@@ -17,6 +17,11 @@ Async usage::
 
 from ._types import (
     BorderResult,
+    CnpjEnrichedResult,
+    CnpjMetadataRawResult,
+    CnpjMetadataResult,
+    CnpjRawResult,
+    CnpjResult,
     CommercialClusterResult,
     GeocodeResult,
     IncomePdfResult,
@@ -77,6 +82,11 @@ __all__ = [
     "RateLimitError",
     "ValidationError",
     "BorderResult",
+    "CnpjEnrichedResult",
+    "CnpjMetadataRawResult",
+    "CnpjMetadataResult",
+    "CnpjRawResult",
+    "CnpjResult",
     "CommercialClusterResult",
     "GeocodeResult",
     "IncomePdfResult",

{prismadata-0.7.0 → prismadata-0.8.0}/prismadata/_constants.py

@@ -5,6 +5,9 @@ BASE_URL = "https://api.prismadata.io/v1"
 MAX_BATCH_SIZE = 1024
 MAX_ROUTING_BATCH = 16
 
+MAX_CNPJ_BATCH_FLAT = 1024
+MAX_CNPJ_BATCH_RAW = 256
+
 DEFAULT_TIMEOUT = 30
 TOKEN_RENEW_MARGIN = 60
 

{prismadata-0.7.0 → prismadata-0.8.0}/prismadata/_types.py

@@ -138,6 +138,93 @@ class QuotaInfo(TypedDict, total=False):
     reset: int
 
 
+class CnpjResult(TypedDict, total=False):
+    """Response from ``cnpj()`` — flat shape (49 scalar keys).
+
+    Full field list at https://docs.prismadata.io/cnpj. Categoria prefix is
+    ``pessoa_juridica`` (to avoid ``prismadata__cnpj__cnpj`` collisions).
+    """
+    prismadata__pessoa_juridica__cnpj: str
+    prismadata__pessoa_juridica__cnpj_basico: str
+    prismadata__pessoa_juridica__razao_social: str
+    prismadata__pessoa_juridica__nome_fantasia: str
+    prismadata__pessoa_juridica__situacao_cadastral: str
+    prismadata__pessoa_juridica__data_abertura: str
+    prismadata__pessoa_juridica__natureza_juridica_codigo: str
+    prismadata__pessoa_juridica__natureza_juridica_descricao: str
+    prismadata__pessoa_juridica__porte: str
+    prismadata__pessoa_juridica__capital_social: str
+    prismadata__pessoa_juridica__cnae_principal_codigo: str
+    prismadata__pessoa_juridica__cnae_principal_descricao: str
+    prismadata__pessoa_juridica__cnae_secundario_1: str
+    prismadata__pessoa_juridica__cnae_secundario_2: str
+    prismadata__pessoa_juridica__cnae_secundario_3: str
+    prismadata__pessoa_juridica__total_cnaes_secundarios: int
+    prismadata__pessoa_juridica__logradouro: str
+    prismadata__pessoa_juridica__numero: str
+    prismadata__pessoa_juridica__bairro: str
+    prismadata__pessoa_juridica__municipio_nome: str
+    prismadata__pessoa_juridica__uf: str
+    prismadata__pessoa_juridica__cep: str
+    prismadata__pessoa_juridica__latitude: str
+    prismadata__pessoa_juridica__longitude: str
+    prismadata__pessoa_juridica__qualidade_geocodificacao_score: int
+    prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao: str
+    prismadata__pessoa_juridica__total_socios: int
+    prismadata__pessoa_juridica__total_socios_pf: int
+    prismadata__pessoa_juridica__total_socios_pj: int
+    prismadata__pessoa_juridica__data_publicacao_rfb: str
+    prismadata__pessoa_juridica__data_processamento: str
+
+
+class CnpjRawResult(TypedDict, total=False):
+    """Response from ``cnpj_raw()`` — F1 schema with nested ``socios`` list.
+
+    See https://docs.prismadata.io/cnpj.
+    """
+    prismadata__pessoa_juridica__cnpj: str
+    prismadata__pessoa_juridica__razao_social: str
+    prismadata__pessoa_juridica__cnaes_secundarios: list[str]
+    prismadata__pessoa_juridica__socios: list[dict[str, Any]]
+
+
+class CnpjMetadataResult(TypedDict, total=False):
+    """Response from ``cnpj_metadata()`` — flat coverage buckets.
+
+    See https://docs.prismadata.io/cnpj.
+    """
+    prismadata__pessoa_juridica__versao_dados: str
+    prismadata__pessoa_juridica__data_publicacao_rfb: str
+    prismadata__pessoa_juridica__data_processamento: str
+    prismadata__pessoa_juridica__total_cnpjs_carregados: int
+    prismadata__pessoa_juridica__cobertura_geo_muito_alta: int
+    prismadata__pessoa_juridica__cobertura_geo_alta: int
+    prismadata__pessoa_juridica__cobertura_geo_media: int
+    prismadata__pessoa_juridica__cobertura_geo_baixa: int
+    prismadata__pessoa_juridica__cobertura_geo_muito_baixa: int
+    prismadata__pessoa_juridica__cobertura_geo_falha: int
+    prismadata__pessoa_juridica__cobertura_geo_sem_geo: int
+
+
+class CnpjMetadataRawResult(TypedDict, total=False):
+    """Response from ``cnpj_raw_metadata()`` — nested coverage dict."""
+    prismadata__pessoa_juridica__versao_dados: str
+    prismadata__pessoa_juridica__data_publicacao_rfb: str
+    prismadata__pessoa_juridica__data_processamento: str
+    prismadata__pessoa_juridica__total_cnpjs_carregados: int
+    prismadata__pessoa_juridica__cobertura_geo: dict[str, int]
+
+
+class CnpjEnrichedResult(CnpjResult, total=False):
+    """Response from ``cnpj_enriched()`` / values of ``cnpj_batch_enriched()``.
+
+    Extends :class:`CnpjResult` with keys from each active geo flag
+    (``prismadata__slum__*``, ``prismadata__border__*`` etc.). When the CNPJ
+    has no lat/lng the geo pillars are silently skipped — only the 49
+    ``pessoa_juridica`` keys are returned. See https://docs.prismadata.io/cnpj.
+    """
+
+
 class TipologiaResult(TypedDict, total=False):
     """Response from ``tipologia()`` (coordinate-based lookup).
 

{prismadata-0.7.0 → prismadata-0.8.0}/prismadata/_validation.py

@@ -2,10 +2,16 @@
 
 from __future__ import annotations
 
+import re
 from typing import Any
 
 _VALID_PROFILES = {"car", "foot", "bike"}
 
+_CNPJ_NON_ALNUM = re.compile(r"[^A-Za-z0-9]")
+_CNPJ_BODY_PATTERN = re.compile(r"^[A-Z0-9]{12}$")
+_CNPJ_DV_WEIGHTS_1 = (5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2)
+_CNPJ_DV_WEIGHTS_2 = (6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2)
+
 _RANKING_SCOPE = {"national": "nacional", "state": "uf", "city": "municipio"}
 _RANKING_CRITERION = {"score": "score", "pdvs": "pdvs", "density": "densidade"}
 _SEARCH_FILTER_KEYS = {
@@ -46,6 +52,41 @@ def validate_route_points(points: list) -> None:
         )
 
 
+def _cnpj_char_value(c: str) -> int:
+    return ord(c) - ord("0")
+
+
+def _cnpj_dv(body: str, weights: tuple[int, ...]) -> str:
+    total = sum(_cnpj_char_value(c) * w for c, w in zip(body, weights))
+    resto = total % 11
+    return "0" if resto < 2 else str(11 - resto)
+
+
+def validate_cnpj(cnpj: str) -> str:
+    """Normalize and validate a CNPJ (supports alphanumeric NT COCAD/SUARA 49/2024).
+
+    Accepts masked input (e.g. ``12.345.678/0001-95``) and lowercase letters.
+    Returns the normalized 14-char CNPJ. Raises ``ValueError`` if invalid.
+    """
+    if not isinstance(cnpj, str):
+        raise ValueError(f"cnpj must be a string, got {type(cnpj).__name__}")
+    normalized = _CNPJ_NON_ALNUM.sub("", cnpj).upper()
+    if len(normalized) != 14:
+        raise ValueError(f"cnpj must have 14 alphanumeric chars, got {len(normalized)}")
+    if len(set(normalized)) == 1:
+        raise ValueError("cnpj cannot have all identical characters")
+    body, dv = normalized[:12], normalized[12:]
+    if not _CNPJ_BODY_PATTERN.match(body):
+        raise ValueError("cnpj body (positions 1-12) must be A-Z or 0-9")
+    if not dv.isdigit():
+        raise ValueError("cnpj check digits (positions 13-14) must be digits")
+    if _cnpj_dv(body, _CNPJ_DV_WEIGHTS_1) != dv[0]:
+        raise ValueError("cnpj first check digit is invalid")
+    if _cnpj_dv(body + dv[0], _CNPJ_DV_WEIGHTS_2) != dv[1]:
+        raise ValueError("cnpj second check digit is invalid")
+    return normalized
+
+
 def validate_address_fields(**fields: Any) -> None:
     """Raise ValueError if no address field is provided."""
     if not any(v is not None for v in fields.values()):

{prismadata-0.7.0 → prismadata-0.8.0}/prismadata/async_client.py

@@ -19,6 +19,8 @@ from ._constants import (
     DEFAULT_TIMEOUT,
     DIRECTION_MAP,
     MAX_BATCH_SIZE,
+    MAX_CNPJ_BATCH_FLAT,
+    MAX_CNPJ_BATCH_RAW,
     MAX_ROUTING_BATCH,
 )
 from ._prepare import async_batch_complete, async_batch_prepare, async_wait_until_ready
@@ -28,6 +30,7 @@ from ._validation import (
     translate_ranking_scope,
     translate_search_filters,
     validate_address_fields,
+    validate_cnpj,
     validate_lat_lng,
     validate_profile,
     validate_route_points,
@@ -39,6 +42,11 @@ if TYPE_CHECKING:
 
     from ._types import (
         BorderResult,
+        CnpjEnrichedResult,
+        CnpjMetadataRawResult,
+        CnpjMetadataResult,
+        CnpjRawResult,
+        CnpjResult,
         CommercialClusterResult,
         GeocodeResult,
         IncomePdfResult,
@@ -717,6 +725,156 @@ class AsyncClient:
             return [clean_columns(item) for item in items]
         return items
 
+    # ------------------------------------------------------------------
+    # CNPJ (pessoa juridica)
+    # ------------------------------------------------------------------
+
+    async def cnpj(self, cnpj: str) -> CnpjResult:
+        """Individual CNPJ lookup, flat shape.
+
+        See :meth:`Client.cnpj` for full docs.
+        """
+        normalized = validate_cnpj(cnpj)
+        return self._maybe_clean(await self._get(f"/cnpj/{normalized}"))
+
+    async def cnpj_raw(self, cnpj: str) -> CnpjRawResult:
+        """Individual CNPJ lookup with F1 schema.
+
+        See :meth:`Client.cnpj_raw` for full docs.
+        """
+        normalized = validate_cnpj(cnpj)
+        return self._maybe_clean(await self._get(f"/cnpj/raw/{normalized}"))
+
+    async def cnpj_batch(
+        self,
+        cnpjs: list[str],
+        *,
+        timeout: int | None = None,
+    ) -> dict[str, CnpjResult | None]:
+        """Batch CNPJ lookup, flat shape. Server caps at 1024.
+
+        See :meth:`Client.cnpj_batch` for full docs.
+        """
+        if len(cnpjs) > MAX_CNPJ_BATCH_FLAT:
+            raise ValueError(
+                f"Batch limit is {MAX_CNPJ_BATCH_FLAT} CNPJs per call, got {len(cnpjs)}"
+            )
+        normalized = [validate_cnpj(c) for c in cnpjs]
+        result = await self._post("/cnpj/batch", {"cnpjs": normalized}, timeout=timeout)
+        if self._clean:
+            return {k: clean_columns(v) if isinstance(v, dict) else v for k, v in result.items()}
+        return result
+
+    async def cnpj_raw_batch(
+        self,
+        cnpjs: list[str],
+        *,
+        timeout: int | None = None,
+    ) -> dict[str, CnpjRawResult | None]:
+        """Batch CNPJ lookup with F1 schema. Server caps at 256.
+
+        See :meth:`Client.cnpj_raw_batch` for full docs.
+        """
+        if len(cnpjs) > MAX_CNPJ_BATCH_RAW:
+            raise ValueError(
+                f"Batch limit is {MAX_CNPJ_BATCH_RAW} CNPJs per call, got {len(cnpjs)}"
+            )
+        normalized = [validate_cnpj(c) for c in cnpjs]
+        result = await self._post("/cnpj/raw/batch", {"cnpjs": normalized}, timeout=timeout)
+        if self._clean:
+            return {k: clean_columns(v) if isinstance(v, dict) else v for k, v in result.items()}
+        return result
+
+    async def cnpj_metadata(self) -> CnpjMetadataResult:
+        """Dataset metadata (flat).
+
+        See :meth:`Client.cnpj_metadata` for full docs.
+        """
+        return self._maybe_clean(await self._get("/cnpj/metadata"))
+
+    async def cnpj_raw_metadata(self) -> CnpjMetadataRawResult:
+        """Dataset metadata with ``cobertura_geo`` as nested dict.
+
+        See :meth:`Client.cnpj_raw_metadata` for full docs.
+        """
+        return self._maybe_clean(await self._get("/cnpj/raw/metadata"))
+
+    async def cnpj_enriched(
+        self,
+        cnpj: str,
+        *,
+        slum: bool = False,
+        prison: bool = False,
+        border: bool = False,
+        personal_income_static: bool = False,
+        personal_income_pdf: bool = False,
+        commercial_cluster: bool = False,
+        infosc: bool = False,
+        tipologia: bool = False,
+        sandbox: bool = False,
+    ) -> CnpjEnrichedResult:
+        """CNPJ lookup with geo fan-out.
+
+        See :meth:`Client.cnpj_enriched` for full docs.
+        """
+        normalized = validate_cnpj(cnpj)
+        flags = {
+            "slum": slum,
+            "prison": prison,
+            "border": border,
+            "personal_income_static": personal_income_static,
+            "personal_income_pdf": personal_income_pdf,
+            "commercial_cluster": commercial_cluster,
+            "infosc": infosc,
+            "tipologia": tipologia,
+            "sandbox": sandbox,
+        }
+        params = {k: "true" for k, v in flags.items() if v}
+        return self._maybe_clean(
+            await self._get(f"/cnpj/{normalized}/enriched", params)
+        )
+
+    async def cnpj_batch_enriched(
+        self,
+        cnpjs: list[str],
+        *,
+        slum: bool = False,
+        prison: bool = False,
+        border: bool = False,
+        personal_income_static: bool = False,
+        personal_income_pdf: bool = False,
+        commercial_cluster: bool = False,
+        infosc: bool = False,
+        tipologia: bool = False,
+        timeout: int | None = None,
+    ) -> dict[str, CnpjEnrichedResult | None]:
+        """Batch CNPJ lookup with geo fan-out. Server caps at 256.
+
+        See :meth:`Client.cnpj_batch_enriched` for full docs.
+        """
+        if len(cnpjs) > MAX_CNPJ_BATCH_RAW:
+            raise ValueError(
+                f"Batch limit is {MAX_CNPJ_BATCH_RAW} CNPJs per call, got {len(cnpjs)}"
+            )
+        normalized = [validate_cnpj(c) for c in cnpjs]
+        body = {
+            "cnpjs": normalized,
+            "flags": {
+                "slum": slum,
+                "prison": prison,
+                "border": border,
+                "personal_income_static": personal_income_static,
+                "personal_income_pdf": personal_income_pdf,
+                "commercial_cluster": commercial_cluster,
+                "infosc": infosc,
+                "tipologia": tipologia,
+            },
+        }
+        result = await self._post("/cnpj/batch/enriched", body, timeout=timeout)
+        if self._clean:
+            return {k: clean_columns(v) if isinstance(v, dict) else v for k, v in result.items()}
+        return result
+
     # ------------------------------------------------------------------
     # Batch operations
     # ------------------------------------------------------------------

{prismadata-0.7.0 → prismadata-0.8.0}/prismadata/client.py

@@ -22,6 +22,8 @@ from ._constants import (
     ENV_PASSWORD,
     ENV_USERNAME,
     MAX_BATCH_SIZE,
+    MAX_CNPJ_BATCH_FLAT,
+    MAX_CNPJ_BATCH_RAW,
     MAX_ROUTING_BATCH,
 )
 from ._http import HttpClient, _handle_response
@@ -32,6 +34,7 @@ from ._validation import (
     translate_ranking_scope,
     translate_search_filters,
     validate_address_fields,
+    validate_cnpj,
     validate_lat_lng,
     validate_profile,
     validate_route_points,
@@ -43,6 +46,11 @@ if TYPE_CHECKING:
 
     from ._types import (
         BorderResult,
+        CnpjEnrichedResult,
+        CnpjMetadataRawResult,
+        CnpjMetadataResult,
+        CnpjRawResult,
+        CnpjResult,
         CommercialClusterResult,
         GeocodeResult,
         IncomePdfResult,
@@ -923,6 +931,162 @@ class Client:
             return [clean_columns(item) for item in items]
         return items
 
+    # ------------------------------------------------------------------
+    # CNPJ (pessoa juridica)
+    # ------------------------------------------------------------------
+
+    def cnpj(self, cnpj: str) -> CnpjResult:
+        """Individual CNPJ lookup, flat shape (49 scalar keys, no nested lists).
+
+        Accepts masked or alphanumeric input; the SDK normalizes and validates
+        the check digits locally before hitting the server.
+        See https://docs.prismadata.io/cnpj.
+        """
+        normalized = validate_cnpj(cnpj)
+        return self._maybe_clean(self._get(f"/cnpj/{normalized}"))
+
+    def cnpj_raw(self, cnpj: str) -> CnpjRawResult:
+        """Individual CNPJ lookup with F1 schema (``socios`` and ``cnaes`` as lists).
+
+        See https://docs.prismadata.io/cnpj.
+        """
+        normalized = validate_cnpj(cnpj)
+        return self._maybe_clean(self._get(f"/cnpj/raw/{normalized}"))
+
+    def cnpj_batch(
+        self,
+        cnpjs: list[str],
+        *,
+        timeout: int | None = None,
+    ) -> dict[str, CnpjResult | None]:
+        """Batch CNPJ lookup, flat shape. Server caps at 1024 per call.
+
+        Returns a dict indexed by the normalized CNPJ, with ``None`` for
+        CNPJs not found by the server. See https://docs.prismadata.io/cnpj.
+        """
+        if len(cnpjs) > MAX_CNPJ_BATCH_FLAT:
+            raise ValueError(
+                f"Batch limit is {MAX_CNPJ_BATCH_FLAT} CNPJs per call, got {len(cnpjs)}"
+            )
+        normalized = [validate_cnpj(c) for c in cnpjs]
+        result = self._post("/cnpj/batch", {"cnpjs": normalized}, timeout=timeout)
+        if self._clean:
+            return {k: clean_columns(v) if isinstance(v, dict) else v for k, v in result.items()}
+        return result
+
+    def cnpj_raw_batch(
+        self,
+        cnpjs: list[str],
+        *,
+        timeout: int | None = None,
+    ) -> dict[str, CnpjRawResult | None]:
+        """Batch CNPJ lookup with F1 schema. Server caps at 256 per call
+        (raw payload is larger than flat).
+
+        See https://docs.prismadata.io/cnpj.
+        """
+        if len(cnpjs) > MAX_CNPJ_BATCH_RAW:
+            raise ValueError(
+                f"Batch limit is {MAX_CNPJ_BATCH_RAW} CNPJs per call, got {len(cnpjs)}"
+            )
+        normalized = [validate_cnpj(c) for c in cnpjs]
+        result = self._post("/cnpj/raw/batch", {"cnpjs": normalized}, timeout=timeout)
+        if self._clean:
+            return {k: clean_columns(v) if isinstance(v, dict) else v for k, v in result.items()}
+        return result
+
+    def cnpj_metadata(self) -> CnpjMetadataResult:
+        """Dataset metadata (version + geo coverage buckets, flat).
+
+        See https://docs.prismadata.io/cnpj.
+        """
+        return self._maybe_clean(self._get("/cnpj/metadata"))
+
+    def cnpj_raw_metadata(self) -> CnpjMetadataRawResult:
+        """Dataset metadata with ``cobertura_geo`` as a nested dict.
+
+        See https://docs.prismadata.io/cnpj.
+        """
+        return self._maybe_clean(self._get("/cnpj/raw/metadata"))
+
+    def cnpj_enriched(
+        self,
+        cnpj: str,
+        *,
+        slum: bool = False,
+        prison: bool = False,
+        border: bool = False,
+        personal_income_static: bool = False,
+        personal_income_pdf: bool = False,
+        commercial_cluster: bool = False,
+        infosc: bool = False,
+        tipologia: bool = False,
+        sandbox: bool = False,
+    ) -> CnpjEnrichedResult:
+        """CNPJ lookup with optional fan-out to geo pillars.
+
+        When a flag is set, the server appends ``prismadata__<flag>__*`` keys
+        to the flat response. When the CNPJ has no lat/lng, geo flags are
+        silently skipped and only the 49 ``pessoa_juridica`` keys come back
+        (``qualidade_geocodificacao_classificacao`` will be ``"FALHA"`` or
+        ``null``). See https://docs.prismadata.io/cnpj.
+        """
+        normalized = validate_cnpj(cnpj)
+        flags = {
+            "slum": slum,
+            "prison": prison,
+            "border": border,
+            "personal_income_static": personal_income_static,
+            "personal_income_pdf": personal_income_pdf,
+            "commercial_cluster": commercial_cluster,
+            "infosc": infosc,
+            "tipologia": tipologia,
+            "sandbox": sandbox,
+        }
+        params = {k: "true" for k, v in flags.items() if v}
+        return self._maybe_clean(self._get(f"/cnpj/{normalized}/enriched", params))
+
+    def cnpj_batch_enriched(
+        self,
+        cnpjs: list[str],
+        *,
+        slum: bool = False,
+        prison: bool = False,
+        border: bool = False,
+        personal_income_static: bool = False,
+        personal_income_pdf: bool = False,
+        commercial_cluster: bool = False,
+        infosc: bool = False,
+        tipologia: bool = False,
+        timeout: int | None = None,
+    ) -> dict[str, CnpjEnrichedResult | None]:
+        """Batch CNPJ lookup with optional geo fan-out. Server caps at 256 per call.
+
+        See https://docs.prismadata.io/cnpj.
+        """
+        if len(cnpjs) > MAX_CNPJ_BATCH_RAW:
+            raise ValueError(
+                f"Batch limit is {MAX_CNPJ_BATCH_RAW} CNPJs per call, got {len(cnpjs)}"
+            )
+        normalized = [validate_cnpj(c) for c in cnpjs]
+        body = {
+            "cnpjs": normalized,
+            "flags": {
+                "slum": slum,
+                "prison": prison,
+                "border": border,
+                "personal_income_static": personal_income_static,
+                "personal_income_pdf": personal_income_pdf,
+                "commercial_cluster": commercial_cluster,
+                "infosc": infosc,
+                "tipologia": tipologia,
+            },
+        }
+        result = self._post("/cnpj/batch/enriched", body, timeout=timeout)
+        if self._clean:
+            return {k: clean_columns(v) if isinstance(v, dict) else v for k, v in result.items()}
+        return result
+
     # ------------------------------------------------------------------
     # Batch operations
     # ------------------------------------------------------------------

{prismadata-0.7.0 → prismadata-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "prismadata"
-version = "0.7.0"
+version = "0.8.0"
 description = "Python client for the PrismaData location intelligence API"
 authors = ["PrismaData <contato@prismadata.io>"]
 license = "MIT"