prismadata 0.1.0__tar.gz

prismadata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrismaData
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prismadata-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: prismadata
+Version: 0.1.0
+Summary: Python client for the PrismaData location intelligence API
+License: MIT
+License-File: LICENSE
+Keywords: geolocation,geocoding,data-science,brazil,location-intelligence
+Author: PrismaData
+Author-email: contato@prismadata.io
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Provides-Extra: all
+Provides-Extra: cache
+Provides-Extra: pandas
+Provides-Extra: progress
+Provides-Extra: sklearn
+Requires-Dist: diskcache (>=5.0) ; extra == "cache" or extra == "all"
+Requires-Dist: httpx (>=0.27,<0.28)
+Requires-Dist: pandas (>=1.5) ; extra == "pandas" or extra == "sklearn" or extra == "all"
+Requires-Dist: scikit-learn (>=1.0) ; extra == "sklearn" or extra == "all"
+Requires-Dist: tenacity (>=9.0,<10.0)
+Requires-Dist: tqdm (>=4.0) ; extra == "progress" or extra == "all"
+Project-URL: Bug Tracker, https://github.com/prismadata/python-client/issues
+Project-URL: Changelog, https://github.com/prismadata/python-client/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://prismadata.io
+Project-URL: Repository, https://github.com/prismadata/python-client
+Description-Content-Type: text/markdown
+
+# prismadata
+
+Python client for the [PrismaData](https://prismadata.io) location intelligence API.
+
+## Installation
+
+```bash
+pip install prismadata
+```
+
+With optional extras:
+
+```bash
+pip install prismadata[pandas]     # DataFrame enrichment
+pip install prismadata[sklearn]    # scikit-learn transformer
+pip install prismadata[all]        # everything (pandas, sklearn, cache, progress bars)
+```
+
+## Quick Start
+
+```python
+from prismadata import Client
+
+client = Client(api_key="your-api-key")
+
+# Geocode an address
+result = client.geocode(full_address="Av Paulista 1000, Sao Paulo")
+print(result["prismadata__geocoder__latitude"], result["prismadata__geocoder__longitude"])
+
+# Query slum proximity
+slum = client.slum(lat=-23.56, lng=-46.65)
+print(slum["prismadata__favela__distancia_m"])
+
+# Calculate a route
+route = client.route([(-23.56, -46.65), (-23.57, -46.66)])
+print(route["prismadata__routing_route__distancia_m"])
+```
+
+## Authentication
+
+The client supports two authentication methods:
+
+```python
+# Using API key
+client = Client(api_key="your-api-key")
+
+# Using username and password
+client = Client(username="your-user", password="your-pass")
+```
+
+Credentials can also be provided via environment variables:
+
+```bash
+export PRISMADATA_APIKEY="your-api-key"
+# or
+export PRISMADATA_USERNAME="your-user"
+export PRISMADATA_PASSWORD="your-pass"
+```
+
+```python
+# Picks up credentials from environment automatically
+client = Client()
+```
+
+Credential resolution order: explicit `api_key` > explicit `username`/`password` > `PRISMADATA_APIKEY` env var > `PRISMADATA_USERNAME`+`PRISMADATA_PASSWORD` env vars.
+
+## DataFrame Enrichment
+
+```python
+import pandas as pd
+from prismadata import Client
+
+client = Client(api_key="your-api-key")
+
+df = pd.DataFrame({
+    "lat": [-23.56, -23.57, -23.58],
+    "lng": [-46.65, -46.66, -46.67],
+})
+
+enriched = client.enrich(df, services=["slum", "income_static", "infosc"])
+print(enriched.columns.tolist())
+# ['lat', 'lng', 'prismadata__favela__distancia_m', ..., 'prismadata__personal_income_static__percentil_br', ...]
+
+# Use clean_columns=True for shorter column names
+client = Client(api_key="your-api-key", clean_columns=True)
+enriched = client.enrich(df, services=["slum"])
+# Column names: 'favela_distancia_m', 'favela_nome', ...
+```
+
+## scikit-learn Pipeline
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+from prismadata.sklearn import PrismaDataTransformer
+
+pipe = Pipeline([
+    ("enrich", PrismaDataTransformer(
+        api_key="your-api-key",
+        services=["slum", "income_static"],
+    )),
+    ("model", RandomForestClassifier()),
+])
+
+pipe.fit(X_train, y_train)
+```
+
+## Async Client
+
+All methods are available asynchronously via `AsyncClient`:
+
+```python
+from prismadata import AsyncClient
+
+async with await AsyncClient.create(api_key="your-api-key") as client:
+    result = await client.slum(lat=-23.56, lng=-46.65)
+    print(result)
+
+    # Batch and enrichment work the same way
+    enriched = await client.enrich(df, services=["slum", "income_static"])
+```
+
+## Error Handling
+
+```python
+from prismadata import Client
+from prismadata.exceptions import (
+    AuthenticationError,
+    BatchError,
+    RateLimitError,
+    PrismaDataError,
+)
+
+try:
+    result = client.slum_batch(large_point_dict)
+except BatchError as e:
+    # Some chunks succeeded, some failed
+    print(f"Got {len(e.partial_results)} results, {len(e.failed_keys)} failed")
+    for key, value in e.partial_results.items():
+        process(key, value)  # use what succeeded
+    retry(e.failed_keys)     # retry what failed
+except RateLimitError:
+    print("Rate limit exceeded, wait and retry")
+except AuthenticationError:
+    print("Invalid credentials")
+except PrismaDataError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Available Methods
+
+### Geocoding
+- `client.geocode(full_address=..., zipcode=..., city=..., state=...)` - Address to coordinates
+- `client.reverse_geocode(lat, lng)` - Coordinates to address
+
+### Location Services
+- `client.slum(lat, lng)` - Nearest slum/favela proximity
+- `client.prison(lat, lng)` - Nearest prison proximity
+- `client.border(lat, lng)` - Border proximity
+- `client.infosc(lat, lng)` - Census sector info
+- `client.income_static(lat, lng)` - Income percentiles
+- `client.income_pdf(lat, lng, gender=..., age=...)` - Detailed income statistics
+
+### Routing
+- `client.route(points, profile="car")` - Route between points
+- `client.isochrone(lat, lng, time_limit=600, profile="car")` - Reachable area
+
+### Address Validation
+- `client.compare_address(lat, lng, full_address=...)` - Compare address with coordinates
+- `client.validate_address(locations, addresses)` - Validate against location history
+- `client.cluster_locations(locations)` - Cluster location history
+
+### Credit
+- `client.precatory(cpf_cnpj=...)` - Credit summary (precatorios/RPVs)
+- `client.precatory_detail(cpf_cnpj=...)` - Detailed credit list
+
+### Batch Operations
+- `client.slum_batch(points)` - Batch slum queries
+- `client.prison_batch(points)` - Batch prison queries
+- `client.border_batch(points)` - Batch border queries
+- `client.infosc_batch(points)` - Batch census sector queries
+- `client.route_batch(items, profile="car")` - Batch routing
+- `client.isochrone_batch(items, profile="car")` - Batch isochrones
+
+### Aggregator
+- `client.aggregate(lat, lng, services=[...])` - Multiple services in one call
+- `client.aggregate_batch(points, services=[...])` - Batch aggregation
+- `client.geocode_aggregate(full_address=..., services=[...])` - Geocode + aggregate
+
+## Configuration
+
+```python
+client = Client(
+    api_key="your-key",
+    timeout=30,            # Request timeout (seconds)
+    cache=True,            # Enable disk cache (requires diskcache)
+    cache_ttl=86400,       # Cache TTL (seconds)
+    clean_columns=False,   # Keep 'prismadata__' prefix (default)
+    show_progress=True,    # Show tqdm progress bars
+    app_name="my-app",     # Sent as X-App header on every request
+)
+```
+
+## License
+
+MIT
+

prismadata-0.1.0/README.md

@@ -0,0 +1,206 @@
+# prismadata
+
+Python client for the [PrismaData](https://prismadata.io) location intelligence API.
+
+## Installation
+
+```bash
+pip install prismadata
+```
+
+With optional extras:
+
+```bash
+pip install prismadata[pandas]     # DataFrame enrichment
+pip install prismadata[sklearn]    # scikit-learn transformer
+pip install prismadata[all]        # everything (pandas, sklearn, cache, progress bars)
+```
+
+## Quick Start
+
+```python
+from prismadata import Client
+
+client = Client(api_key="your-api-key")
+
+# Geocode an address
+result = client.geocode(full_address="Av Paulista 1000, Sao Paulo")
+print(result["prismadata__geocoder__latitude"], result["prismadata__geocoder__longitude"])
+
+# Query slum proximity
+slum = client.slum(lat=-23.56, lng=-46.65)
+print(slum["prismadata__favela__distancia_m"])
+
+# Calculate a route
+route = client.route([(-23.56, -46.65), (-23.57, -46.66)])
+print(route["prismadata__routing_route__distancia_m"])
+```
+
+## Authentication
+
+The client supports two authentication methods:
+
+```python
+# Using API key
+client = Client(api_key="your-api-key")
+
+# Using username and password
+client = Client(username="your-user", password="your-pass")
+```
+
+Credentials can also be provided via environment variables:
+
+```bash
+export PRISMADATA_APIKEY="your-api-key"
+# or
+export PRISMADATA_USERNAME="your-user"
+export PRISMADATA_PASSWORD="your-pass"
+```
+
+```python
+# Picks up credentials from environment automatically
+client = Client()
+```
+
+Credential resolution order: explicit `api_key` > explicit `username`/`password` > `PRISMADATA_APIKEY` env var > `PRISMADATA_USERNAME`+`PRISMADATA_PASSWORD` env vars.
+
+## DataFrame Enrichment
+
+```python
+import pandas as pd
+from prismadata import Client
+
+client = Client(api_key="your-api-key")
+
+df = pd.DataFrame({
+    "lat": [-23.56, -23.57, -23.58],
+    "lng": [-46.65, -46.66, -46.67],
+})
+
+enriched = client.enrich(df, services=["slum", "income_static", "infosc"])
+print(enriched.columns.tolist())
+# ['lat', 'lng', 'prismadata__favela__distancia_m', ..., 'prismadata__personal_income_static__percentil_br', ...]
+
+# Use clean_columns=True for shorter column names
+client = Client(api_key="your-api-key", clean_columns=True)
+enriched = client.enrich(df, services=["slum"])
+# Column names: 'favela_distancia_m', 'favela_nome', ...
+```
+
+## scikit-learn Pipeline
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+from prismadata.sklearn import PrismaDataTransformer
+
+pipe = Pipeline([
+    ("enrich", PrismaDataTransformer(
+        api_key="your-api-key",
+        services=["slum", "income_static"],
+    )),
+    ("model", RandomForestClassifier()),
+])
+
+pipe.fit(X_train, y_train)
+```
+
+## Async Client
+
+All methods are available asynchronously via `AsyncClient`:
+
+```python
+from prismadata import AsyncClient
+
+async with await AsyncClient.create(api_key="your-api-key") as client:
+    result = await client.slum(lat=-23.56, lng=-46.65)
+    print(result)
+
+    # Batch and enrichment work the same way
+    enriched = await client.enrich(df, services=["slum", "income_static"])
+```
+
+## Error Handling
+
+```python
+from prismadata import Client
+from prismadata.exceptions import (
+    AuthenticationError,
+    BatchError,
+    RateLimitError,
+    PrismaDataError,
+)
+
+try:
+    result = client.slum_batch(large_point_dict)
+except BatchError as e:
+    # Some chunks succeeded, some failed
+    print(f"Got {len(e.partial_results)} results, {len(e.failed_keys)} failed")
+    for key, value in e.partial_results.items():
+        process(key, value)  # use what succeeded
+    retry(e.failed_keys)     # retry what failed
+except RateLimitError:
+    print("Rate limit exceeded, wait and retry")
+except AuthenticationError:
+    print("Invalid credentials")
+except PrismaDataError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Available Methods
+
+### Geocoding
+- `client.geocode(full_address=..., zipcode=..., city=..., state=...)` - Address to coordinates
+- `client.reverse_geocode(lat, lng)` - Coordinates to address
+
+### Location Services
+- `client.slum(lat, lng)` - Nearest slum/favela proximity
+- `client.prison(lat, lng)` - Nearest prison proximity
+- `client.border(lat, lng)` - Border proximity
+- `client.infosc(lat, lng)` - Census sector info
+- `client.income_static(lat, lng)` - Income percentiles
+- `client.income_pdf(lat, lng, gender=..., age=...)` - Detailed income statistics
+
+### Routing
+- `client.route(points, profile="car")` - Route between points
+- `client.isochrone(lat, lng, time_limit=600, profile="car")` - Reachable area
+
+### Address Validation
+- `client.compare_address(lat, lng, full_address=...)` - Compare address with coordinates
+- `client.validate_address(locations, addresses)` - Validate against location history
+- `client.cluster_locations(locations)` - Cluster location history
+
+### Credit
+- `client.precatory(cpf_cnpj=...)` - Credit summary (precatorios/RPVs)
+- `client.precatory_detail(cpf_cnpj=...)` - Detailed credit list
+
+### Batch Operations
+- `client.slum_batch(points)` - Batch slum queries
+- `client.prison_batch(points)` - Batch prison queries
+- `client.border_batch(points)` - Batch border queries
+- `client.infosc_batch(points)` - Batch census sector queries
+- `client.route_batch(items, profile="car")` - Batch routing
+- `client.isochrone_batch(items, profile="car")` - Batch isochrones
+
+### Aggregator
+- `client.aggregate(lat, lng, services=[...])` - Multiple services in one call
+- `client.aggregate_batch(points, services=[...])` - Batch aggregation
+- `client.geocode_aggregate(full_address=..., services=[...])` - Geocode + aggregate
+
+## Configuration
+
+```python
+client = Client(
+    api_key="your-key",
+    timeout=30,            # Request timeout (seconds)
+    cache=True,            # Enable disk cache (requires diskcache)
+    cache_ttl=86400,       # Cache TTL (seconds)
+    clean_columns=False,   # Keep 'prismadata__' prefix (default)
+    show_progress=True,    # Show tqdm progress bars
+    app_name="my-app",     # Sent as X-App header on every request
+)
+```
+
+## License
+
+MIT

prismadata-0.1.0/prismadata/__init__.py

@@ -0,0 +1,69 @@
+"""PrismaData - Python client for location intelligence API.
+
+Usage::
+
+    from prismadata import Client
+
+    client = Client(api_key="your-key")
+    result = client.geocode(full_address="Av Paulista 1000, Sao Paulo")
+
+Async usage::
+
+    from prismadata import AsyncClient
+
+    async with await AsyncClient.create(api_key="your-key") as client:
+        result = await client.geocode(full_address="Av Paulista 1000, Sao Paulo")
+"""
+
+from ._types import (
+    BorderResult,
+    GeocodeResult,
+    IncomePdfResult,
+    IncomeStaticResult,
+    InfoscResult,
+    IsochroneResult,
+    PrecatoryResult,
+    PrisonResult,
+    ReverseGeocodeResult,
+    RouteResult,
+    RoutingBatchResult,
+    SlumResult,
+    UserInfo,
+)
+from .async_client import AsyncClient
+from .client import Client
+from .exceptions import (
+    AuthenticationError,
+    BatchError,
+    PrismaDataError,
+    QuotaExhaustedError,
+    RateLimitError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "__version__",
+    "AuthenticationError",
+    "BatchError",
+    "PrismaDataError",
+    "QuotaExhaustedError",
+    "RateLimitError",
+    "ValidationError",
+    "BorderResult",
+    "GeocodeResult",
+    "IncomePdfResult",
+    "IncomeStaticResult",
+    "InfoscResult",
+    "IsochroneResult",
+    "PrecatoryResult",
+    "PrisonResult",
+    "ReverseGeocodeResult",
+    "RouteResult",
+    "RoutingBatchResult",
+    "SlumResult",
+    "UserInfo",
+]

prismadata-0.1.0/prismadata/_async_auth.py

@@ -0,0 +1,112 @@
+"""Async JWT authentication manager for the PrismaData API."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from ._auth import _decode_jwt_claims
+from ._constants import TOKEN_RENEW_MARGIN
+from .exceptions import AuthenticationError
+
+logger = logging.getLogger("prismadata.async_auth")
+
+
+class AsyncAuthManager:
+    """Manages JWT token lifecycle asynchronously."""
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: int,
+        *,
+        api_key: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+    ) -> None:
+        self._base_url = base_url
+        self._timeout = timeout
+        self._api_key = api_key
+        self._username = username
+        self._password = password
+        self._token: str | None = None
+        self._token_exp: float = 0.0
+        self._rate_limit: float | None = None
+        self._sandbox: bool = False
+        self._lock = asyncio.Lock()
+        self._http_client: httpx.AsyncClient | None = None
+
+    def set_http_client(self, client: httpx.AsyncClient) -> None:
+        """Attach a shared httpx.AsyncClient for token refresh requests."""
+        self._http_client = client
+
+    @property
+    def rate_limit(self) -> float | None:
+        return self._rate_limit
+
+    @property
+    def is_sandbox(self) -> bool:
+        return self._sandbox
+
+    async def authenticate(self) -> None:
+        """Force token fetch immediately."""
+        async with self._lock:
+            await self._fetch_token()
+
+    async def ensure_valid_token(self) -> None:
+        """Ensure a valid token is available, refreshing if needed."""
+        if self._token and time.time() < (self._token_exp - TOKEN_RENEW_MARGIN):
+            return
+        async with self._lock:
+            if self._token and time.time() < (self._token_exp - TOKEN_RENEW_MARGIN):
+                return
+            await self._fetch_token()
+
+    def get_headers(self) -> dict[str, str]:
+        """Return auth headers (sync — call ensure_valid_token first)."""
+        if self._api_key:
+            return {"X-Apikey": self._api_key}
+        return {"Authorization": f"Bearer {self._token}"}
+
+    async def _try_refresh_claims(self) -> None:
+        """Best-effort claim refresh in API key mode."""
+        try:
+            await self.ensure_valid_token()
+        except Exception as exc:
+            logger.warning("Claim refresh failed (API key mode): %s", exc)
+
+    async def _fetch_token(self) -> None:
+        mode = "api_key" if self._api_key else "credentials"
+        logger.debug("Fetching token (mode=%s)", mode)
+
+        if self._api_key:
+            data = {"api_key": self._api_key}
+        else:
+            data = {"username": self._username, "password": self._password}
+
+        url = f"{self._base_url}/auth/token"
+        try:
+            if self._http_client is not None:
+                resp = await self._http_client.post(url, data=data)
+            else:
+                async with httpx.AsyncClient(timeout=self._timeout) as http:
+                    resp = await http.post(url, data=data)
+        except httpx.HTTPError as exc:
+            raise AuthenticationError(f"Failed to connect to auth endpoint: {exc}") from exc
+
+        if resp.status_code in (401, 403):
+            raise AuthenticationError(f"Authentication failed: {resp.text}")
+        resp.raise_for_status()
+
+        body = resp.json()
+        self._token = body["access_token"]
+        claims = _decode_jwt_claims(self._token)
+        self._token_exp = claims.get("exp", time.time() + 3600)
+        self._rate_limit = claims.get("rate_limit")
+        self._sandbox = claims.get("sandbox", False)
+        expires_in = self._token_exp - time.time()
+        logger.debug("Token obtained, expires in %.0fs, rate_limit=%s", expires_in, self._rate_limit)