permisapi-client 0.7.1__tar.gz → 0.8.0__tar.gz

{permisapi_client-0.7.1 → permisapi_client-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: permisapi-client
-Version: 0.7.1
+Version: 0.8.0
 Summary: Client Python officiel pour PermisAPI : permis de construire France en API REST.
 Project-URL: Homepage, https://permisapi.fr
 Project-URL: Documentation, https://permisapi.fr/docs

{permisapi_client-0.7.1 → permisapi_client-0.8.0}/permisapi_client/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "PermisAPIValidationError",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.8.0"

{permisapi_client-0.7.1 → permisapi_client-0.8.0}/permisapi_client/client.py

@@ -13,7 +13,7 @@ from permisapi_client.exceptions import error_from_response
 
 DEFAULT_BASE_URL = "https://api.permisapi.fr"
 DEFAULT_TIMEOUT = 15.0
-USER_AGENT = "permisapi-client-python/0.7.1"
+USER_AGENT = "permisapi-client-python/0.8.0"
 
 
 def _raise_for_status(resp: httpx.Response) -> None:
@@ -63,6 +63,32 @@ class _PermitsResource:
         Champs autorises : date_reelle_autorisation, date_depot,
         an_depot, superficie_terrain. Prefixe `-` pour descendant.
         Tout autre champ retourne 422 (et non ignore silencieusement).
+
+        Filtre `min_score` (Pro+ uniquement) : retourne uniquement les
+        permis avec un Score Opportunite MDB >= N (0-100). Use case
+        marchand de biens : shortliste les top opportunites en 1 call
+        au lieu de fetch + filter cote client. Cout quota special :
+        `limit` unites au lieu de 1 (anti-abus, equivalent a N calls
+        /score). Header X-RateLimit-Cost confirme.
+
+        Filtre `max_risk` (Pro+ uniquement) : exclut les permis dont
+        la commune est classee au-dessus du tier specifie (low /
+        moderate / high / critical). Exemple `max_risk="moderate"`
+        retourne uniquement les permis low + moderate. Cout quota =
+        limit (anti-abus, equivalent a N calls /risks). Lookup via
+        colonne materialisee `permits.risk_tier` (refresh par
+        scripts/materialize_risks.py mensuel).
+
+        Filtre `plu_zone_type` (Pro+ uniquement) : prefix de zonage
+        urbanisme parmi U / AU / A / N / OTHER. Exemple
+        `plu_zone_type="U"` retourne uniquement les permis en zone
+        urbaine constructible. Cout quota = limit.
+
+        Filtre `plu_constructible` (Pro+ uniquement) : booleen.
+        `plu_constructible=True` retourne uniquement les permis ou le
+        verdict heuristique est constructible (zone U ou AU). Pratique
+        combine avec `min_score` pour shortlister les vraies
+        opportunites MDB. Cout quota = limit.
         """
         return self._c._get("/v1/permits", params=params)
 
@@ -101,6 +127,24 @@ class _PermitsResource:
             params={"section": section, "numero": numero},
         )
 
+    def parcelle(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/parcelle : geometrie cadastre DGFiP.
+
+        Plans Pro et superieurs uniquement (402 si Free / Explorer).
+        Retourne {num_pa, comm_code, section, numero, cadastre_id,
+        surface_m2 (contenance officielle DGFiP), geometry (GeoJSON
+        Polygon WGS84), cached_at, source}.
+
+        404 si la parcelle n'est pas encore en cache (commune hors
+        couverture Etalab ou pas encore materialise par
+        scripts/ingest_cadastre.py).
+
+        Use case : afficher le polygon precis sur une carte (vs juste
+        un point lat/lng), comparer surface DGFiP vs Sitadel, cross-ref
+        avec DVF en parcelle precise.
+        """
+        return self._c._get(f"/v1/permits/{num_pa}/parcelle")
+
     def dvf(
         self,
         num_pa: str,
@@ -430,6 +474,37 @@ class PermisAPI:
         self.alerts = _AlertsResource(self)
         self.me = _MeResource(self)
 
+    def search(
+        self,
+        q: str,
+        *,
+        dep_code: str | None = None,
+        limit: int = 20,
+    ) -> list[dict[str, Any]]:
+        """GET /v1/search : recherche fuzzy par texte sur les adresses.
+
+        Utilise pg_trgm cote DB. Insensible aux accents et a la casse,
+        tolerant aux typos courants. Latence ~50-200ms.
+
+        Tous plans (Free, Explorer, Pro, Business, Enterprise) avec
+        respect du scope geo. Cout quota = 1 unite (endpoint
+        d'acquisition, pas premium).
+
+        Args:
+            q: texte libre, min 2 chars (ex "republique bordeaux",
+               "rue victor hugo paris", "cours de l'ile")
+            dep_code: optionnel, restreindre a un departement
+            limit: 1-50, default 20
+
+        Returns:
+            Liste de PermitSummary tries par pertinence (similarity)
+            puis date desc.
+        """
+        params: dict[str, Any] = {"q": q, "limit": limit}
+        if dep_code is not None:
+            params["dep_code"] = dep_code
+        return self._get("/v1/search", params=params)
+
     def close(self) -> None:
         self._http.close()
 
@@ -546,6 +621,11 @@ class _AsyncPermitsResource:
         Voir _PermitsResource.risks pour la doc complete."""
         return await self._c._get(f"/v1/permits/{num_pa}/risks")
 
+    async def parcelle(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/parcelle : version async. Plans Pro+ only.
+        Voir _PermitsResource.parcelle pour la doc complete."""
+        return await self._c._get(f"/v1/permits/{num_pa}/parcelle")
+
     async def full_view(self, num_pa: str) -> dict[str, Any]:
         """GET /v1/permits/{num_pa}/360 : version async. Vue agregee 6-en-1.
 
@@ -682,6 +762,20 @@ class AsyncPermisAPI:
         self.alerts = _AsyncAlertsResource(self)
         self.me = _AsyncMeResource(self)
 
+    async def search(
+        self,
+        q: str,
+        *,
+        dep_code: str | None = None,
+        limit: int = 20,
+    ) -> list[dict[str, Any]]:
+        """GET /v1/search : version async. Voir PermisAPI.search pour
+        la doc complete (fuzzy pg_trgm sur full_address)."""
+        params: dict[str, Any] = {"q": q, "limit": limit}
+        if dep_code is not None:
+            params["dep_code"] = dep_code
+        return await self._get("/v1/search", params=params)
+
     async def close(self) -> None:
         await self._http.aclose()
 

{permisapi_client-0.7.1 → permisapi_client-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "permisapi-client"
-version = "0.7.1"
+version = "0.8.0"
 description = "Client Python officiel pour PermisAPI : permis de construire France en API REST."
 readme = "README.md"
 requires-python = ">=3.9"