wozapi 1.0.0__tar.gz

wozapi-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+node_modules/
+bin/
+obj/

wozapi-1.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: wozapi
+Version: 1.0.0
+Summary: WOZ-waarde, BAG-adresgegevens en kadastrale percelen van elk Nederlands adres via 1 endpoint. Client voor woz-api.nl.
+Project-URL: Homepage, https://woz-api.nl
+Project-URL: Documentation, https://wozapi.github.io/
+Project-URL: Repository, https://github.com/WozApi/wozapi-clients
+Project-URL: Prijzen, https://woz-api.nl/woz-api-prijs
+Author-email: WozApi <info@woz-api.nl>
+License: MIT
+Keywords: bag,kadaster,nederland,proptech,vastgoed,woz,woz-api,woz-waarde
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Dutch
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# wozapi (Python)
+
+Python-client voor de [WOZ API van woz-api.nl](https://woz-api.nl): de WOZ-waarde,
+BAG-adresgegevens en kadastrale percelen van elk Nederlands adres in 1 JSON-response.
+Geen externe afhankelijkheden, alleen de standaardbibliotheek.
+
+## Installeren
+
+```bash
+pip install wozapi
+```
+
+Nog niet gepubliceerd? Kopieer dan `wozapi.py` naar je project; het bestand staat op zichzelf.
+
+## Gebruik
+
+```python
+from wozapi import WozApi, WozApiError
+
+client = WozApi("jouw-api-key")
+
+try:
+    adres = client.adres("Spuistraat 36C, 1012 TT Amsterdam")
+    for woz in adres["woz"]:
+        print(woz["peildatum"], woz["vastgesteldeWaarde"])
+except WozApiError as fout:
+    print(fout.status, fout.bericht)
+```
+
+Perceelgrenzen als GeoJSON meesturen:
+
+```python
+adres = client.adres("Spuistraat 36C, 1012 TT Amsterdam", geometrie=True)
+```
+
+Zoeken op BAG-identificatie in plaats van een adrestekst:
+
+```python
+client.nummeraanduiding("0363200000218908")
+client.adresseerbaar_object("0363010000740855")
+```
+
+Creditsaldo opvragen:
+
+```python
+print(client.credits())
+```
+
+## Wat kost het
+
+Een gratis account geeft 10 credits. 1 credit is 1 uniek adres, en hetzelfde adres binnen
+7 dagen opnieuw opvragen kost geen extra credit. De prijs per credit begint bij EUR 0,35
+excl. btw en daalt bij grotere afname; zie [de prijzen](https://woz-api.nl/woz-api-prijs).
+
+Geen zin in code? Met de [Excel-wizard](https://woz-api.nl/woz-waarden-in-excel) upload je een
+bestand met adressen en krijg je het aangevuld terug.
+
+## Documentatie
+
+- API-referentie: [woz-api.nl/swagger](https://woz-api.nl/swagger/index.html)
+- Uitleg en achtergrond: [woz-api.nl/artikelen](https://woz-api.nl/artikelen)
+- Ontwikkeling van WOZ-waarden per regio: [woz-api.nl/woz-waarde-ontwikkeling](https://woz-api.nl/woz-waarde-ontwikkeling)
+
+## Licentie
+
+MIT

wozapi-1.0.0/README.md

@@ -0,0 +1,66 @@
+# wozapi (Python)
+
+Python-client voor de [WOZ API van woz-api.nl](https://woz-api.nl): de WOZ-waarde,
+BAG-adresgegevens en kadastrale percelen van elk Nederlands adres in 1 JSON-response.
+Geen externe afhankelijkheden, alleen de standaardbibliotheek.
+
+## Installeren
+
+```bash
+pip install wozapi
+```
+
+Nog niet gepubliceerd? Kopieer dan `wozapi.py` naar je project; het bestand staat op zichzelf.
+
+## Gebruik
+
+```python
+from wozapi import WozApi, WozApiError
+
+client = WozApi("jouw-api-key")
+
+try:
+    adres = client.adres("Spuistraat 36C, 1012 TT Amsterdam")
+    for woz in adres["woz"]:
+        print(woz["peildatum"], woz["vastgesteldeWaarde"])
+except WozApiError as fout:
+    print(fout.status, fout.bericht)
+```
+
+Perceelgrenzen als GeoJSON meesturen:
+
+```python
+adres = client.adres("Spuistraat 36C, 1012 TT Amsterdam", geometrie=True)
+```
+
+Zoeken op BAG-identificatie in plaats van een adrestekst:
+
+```python
+client.nummeraanduiding("0363200000218908")
+client.adresseerbaar_object("0363010000740855")
+```
+
+Creditsaldo opvragen:
+
+```python
+print(client.credits())
+```
+
+## Wat kost het
+
+Een gratis account geeft 10 credits. 1 credit is 1 uniek adres, en hetzelfde adres binnen
+7 dagen opnieuw opvragen kost geen extra credit. De prijs per credit begint bij EUR 0,35
+excl. btw en daalt bij grotere afname; zie [de prijzen](https://woz-api.nl/woz-api-prijs).
+
+Geen zin in code? Met de [Excel-wizard](https://woz-api.nl/woz-waarden-in-excel) upload je een
+bestand met adressen en krijg je het aangevuld terug.
+
+## Documentatie
+
+- API-referentie: [woz-api.nl/swagger](https://woz-api.nl/swagger/index.html)
+- Uitleg en achtergrond: [woz-api.nl/artikelen](https://woz-api.nl/artikelen)
+- Ontwikkeling van WOZ-waarden per regio: [woz-api.nl/woz-waarde-ontwikkeling](https://woz-api.nl/woz-waarde-ontwikkeling)
+
+## Licentie
+
+MIT

wozapi-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wozapi"
+version = "1.0.0"
+description = "WOZ-waarde, BAG-adresgegevens en kadastrale percelen van elk Nederlands adres via 1 endpoint. Client voor woz-api.nl."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "WozApi", email = "info@woz-api.nl" }]
+keywords = ["woz", "woz-api", "woz-waarde", "bag", "kadaster", "nederland", "vastgoed", "proptech"]
+
+# Bewust geen dependencies: de client gebruikt alleen de standaardbibliotheek, zodat hij in elke
+# omgeving werkt zonder dependency-discussie. Dat is ook de reden dat hij een enkele module is
+# en geen package met submodules.
+dependencies = []
+
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Natural Language :: Dutch",
+]
+
+[project.urls]
+Homepage = "https://woz-api.nl"
+Documentation = "https://wozapi.github.io/"
+Repository = "https://github.com/WozApi/wozapi-clients"
+Prijzen = "https://woz-api.nl/woz-api-prijs"
+
+[tool.hatch.build.targets.wheel]
+# Een enkele module, geen map. Zonder deze regel zoekt hatchling naar een map "wozapi" en faalt.
+only-include = ["wozapi.py"]
+sources = ["."]
+
+[tool.hatch.build.targets.sdist]
+include = ["wozapi.py", "README.md"]

wozapi-1.0.0/wozapi.py

@@ -0,0 +1,128 @@
+"""
+WozApi: WOZ-waarde, BAG-adresgegevens en kadastrale percelen van elk Nederlands adres.
+
+Dunne wrapper rond https://woz-api.nl zonder externe afhankelijkheden: alleen de
+standaardbibliotheek, zodat deze client in elke omgeving werkt zonder dependency-discussie.
+
+Snel starten:
+
+    from wozapi import WozApi
+
+    client = WozApi("jouw-api-key")
+    adres = client.adres("Spuistraat 36C, 1012 TT Amsterdam")
+    print(adres["woz"][0]["vastgesteldeWaarde"])
+
+Een gratis account op https://woz-api.nl geeft 10 credits. 1 credit is 1 uniek adres;
+hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen extra credit.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__version__ = "1.0.0"
+__all__ = ["WozApi", "WozApiError"]
+
+STANDAARD_BASIS_URL = "https://woz-api.nl"
+
+
+class WozApiError(RuntimeError):
+    """Fout van de WOZ API. Bevat de HTTP-status en, indien aanwezig, de servermelding."""
+
+    def __init__(self, status: int, bericht: str, body: str | None = None) -> None:
+        super().__init__(f"WozApi {status}: {bericht}")
+        self.status = status
+        self.bericht = bericht
+        self.body = body
+
+
+class WozApi:
+    """Client voor de WOZ API.
+
+    Args:
+        api_key: je sleutel uit https://woz-api.nl/ApiKeys.
+        basis_url: alleen aanpassen voor een testomgeving.
+        timeout: seconden voordat een request afbreekt.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        basis_url: str = STANDAARD_BASIS_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is verplicht; maak er een aan op https://woz-api.nl/ApiKeys")
+        self._api_key = api_key.strip()
+        self._basis_url = basis_url.rstrip("/")
+        self._timeout = timeout
+
+    def adres(self, adres: str, geometrie: bool = False) -> dict[str, Any]:
+        """Zoekt op een vrij ingevoerd adres, bijvoorbeeld "Spuistraat 36C, 1012 TT Amsterdam".
+
+        Args:
+            adres: het adres als tekst.
+            geometrie: ook perceelgrenzen als GeoJSON meesturen. Standaard uit, want dat
+                maakt de respons fors groter.
+        """
+        return self._get("/Api/Adres", {"adres": adres, "geometrie": geometrie})
+
+    def nummeraanduiding(self, nummeraanduiding_id: str, geometrie: bool = False) -> dict[str, Any]:
+        """Zoekt op een BAG-nummeraanduiding-id."""
+        pad = f"/Api/Nummeraanduiding/{urllib.parse.quote(str(nummeraanduiding_id))}"
+        return self._get(pad, {"geometrie": geometrie})
+
+    def adresseerbaar_object(self, object_id: str, geometrie: bool = False) -> dict[str, Any]:
+        """Zoekt op een BAG-adresseerbaarobject-id (verblijfsobject, ligplaats, standplaats)."""
+        pad = f"/Api/AdresseerbaarObject/{urllib.parse.quote(str(object_id))}"
+        return self._get(pad, {"geometrie": geometrie})
+
+    def credits(self) -> dict[str, Any]:
+        """Het resterende creditsaldo van deze sleutel."""
+        return self._get("/Api/Credits", {})
+
+    def _get(self, pad: str, parameters: dict[str, Any]) -> dict[str, Any]:
+        schoon = {
+            sleutel: ("true" if waarde is True else "false" if waarde is False else str(waarde))
+            for sleutel, waarde in parameters.items()
+            if waarde is not None
+        }
+        url = f"{self._basis_url}{pad}"
+        if schoon:
+            url = f"{url}?{urllib.parse.urlencode(schoon)}"
+
+        verzoek = urllib.request.Request(
+            url,
+            headers={
+                "X-Api-Key": self._api_key,
+                "Accept": "application/json",
+                "User-Agent": f"wozapi-python/{__version__}",
+            },
+        )
+
+        try:
+            with urllib.request.urlopen(verzoek, timeout=self._timeout) as antwoord:
+                return json.loads(antwoord.read().decode("utf-8"))
+        except urllib.error.HTTPError as fout:
+            body = fout.read().decode("utf-8", errors="replace")
+            raise WozApiError(fout.code, _melding(body, fout.reason), body) from fout
+        except urllib.error.URLError as fout:
+            raise WozApiError(0, f"netwerkfout: {fout.reason}") from fout
+
+
+def _melding(body: str, standaard: str) -> str:
+    """Haalt de servermelding uit een JSON-foutbody; valt terug op de HTTP-reden."""
+    try:
+        data = json.loads(body)
+    except (ValueError, TypeError):
+        return standaard
+    if isinstance(data, dict):
+        for sleutel in ("message", "error", "title", "detail"):
+            waarde = data.get(sleutel)
+            if isinstance(waarde, str) and waarde.strip():
+                return waarde
+    return standaard