datamarket 0.9.28__tar.gz → 0.9.30__tar.gz

{datamarket-0.9.28 → datamarket-0.9.30}/PKG-INFO

@@ -1,17 +1,17 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: datamarket
-Version: 0.9.28
+Version: 0.9.30
 Summary: Utilities that integrate advanced scraping knowledge into just one library.
+Home-page: https://datamarket.es
 License: GPL-3.0-or-later
 Author: DataMarket
 Author-email: techsupport@datamarket.es
-Requires-Python: >=3.12,<4.0
+Requires-Python: >=3.12,<3.13
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: alchemy
 Provides-Extra: aws
 Provides-Extra: azure-storage-blob
@@ -40,6 +40,7 @@ Provides-Extra: openpyxl
 Provides-Extra: pandas
 Provides-Extra: pandera
 Provides-Extra: peerdb
+Provides-Extra: pii
 Provides-Extra: pillow
 Provides-Extra: playwright
 Provides-Extra: playwright-stealth
@@ -83,6 +84,7 @@ Requires-Dist: google-auth-oauthlib (>=1.0.0,<2.0.0) ; extra == "google-auth-oau
 Requires-Dist: html2text (>=2024.0.0,<2025.0.0) ; extra == "html2text"
 Requires-Dist: httpx[http2] (>=0.28.0,<0.29.0) ; extra == "httpx"
 Requires-Dist: inflection (>=0.5.0,<0.6.0)
+Requires-Dist: jellyfish (>=1.0.0,<2.0.0)
 Requires-Dist: jinja2 (>=3.0.0,<4.0.0)
 Requires-Dist: json5 (>=0.10.0,<0.11.0) ; extra == "json5"
 Requires-Dist: lxml[html-clean] (>=5.0.0,<6.0.0) ; extra == "lxml"
@@ -95,6 +97,8 @@ Requires-Dist: pendulum (>=3.0.0,<4.0.0)
 Requires-Dist: pillow (>=11.0.0,<12.0.0) ; extra == "pillow"
 Requires-Dist: playwright (==1.47.0) ; extra == "playwright"
 Requires-Dist: pre-commit (>=4.0.0,<5.0.0)
+Requires-Dist: presidio-analyzer[phonenumbers] (>=2.0.0,<3.0.0) ; extra == "pii"
+Requires-Dist: presidio-anonymizer (>=2.0.0,<3.0.0) ; extra == "pii"
 Requires-Dist: psycopg2-binary (>=2.0.0,<3.0.0)
 Requires-Dist: pyarrow (>=19.0.0,<20.0.0) ; extra == "pyarrow"
 Requires-Dist: pycountry (>=24.0.0,<25.0.0)
@@ -110,14 +114,16 @@ Requires-Dist: retry (>=0.9.0,<0.10.0) ; extra == "retry"
 Requires-Dist: shapely (>=2.0.0,<3.0.0) ; extra == "shapely"
 Requires-Dist: soda-core-mysql (>=3.0.0,<4.0.0) ; extra == "soda-core-mysql"
 Requires-Dist: soda-core-postgres (>=3.0.0,<4.0.0) ; extra == "soda-core-postgres"
+Requires-Dist: spacy (>=3.0.0,<4.0.0) ; extra == "pii"
+Requires-Dist: spacy-langdetect (>=0.1.0,<0.2.0) ; extra == "pii"
 Requires-Dist: stem (>=1.0.0,<2.0.0) ; extra == "stem" or extra == "proxy"
 Requires-Dist: tenacity (>=9.0.0,<10.0.0)
+Requires-Dist: tf-playwright-stealth (>=1.0.0,<2.0.0)
 Requires-Dist: tqdm (>=4.0.0,<5.0.0) ; extra == "tqdm"
 Requires-Dist: typer (>=0.15.0,<0.16.0)
 Requires-Dist: unidecode (>=1.0.0,<2.0.0)
 Requires-Dist: xmltodict (>=0.14.0,<0.15.0) ; extra == "xmltodict"
 Project-URL: Documentation, https://github.com/Data-Market/datamarket
-Project-URL: Homepage, https://datamarket.es
 Project-URL: Repository, https://github.com/Data-Market/datamarket
 Description-Content-Type: text/markdown
 

{datamarket-0.9.28 → datamarket-0.9.30}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "datamarket"
-version = "0.9.28"
+version = "0.9.30"
 description = "Utilities that integrate advanced scraping knowledge into just one library."
 authors = ["DataMarket <techsupport@datamarket.es>"]
 license = "GPL-3.0-or-later"
@@ -15,7 +15,7 @@ classifiers = [
 ]
 
 [tool.poetry.dependencies]
-python = "^3.12"
+python = ">=3.12,<3.13"
 typer = "~0.15.0"
 psycopg2-binary = "^2.0.0"
 requests = "^2.0.0"
@@ -32,6 +32,7 @@ unidecode = "^1.0.0"
 numpy = "^2.0.0"
 pycountry = "^24.0.0"
 geopy = "^2.0.0"
+jellyfish = "^1.0.0"
 
 boto3 = { version = "~1.35.0", optional = true }
 lxml = { extras = ["html-clean"], version = "^5.0.0", optional = true }
@@ -75,6 +76,12 @@ openpyxl = { version = "^3.0.0", optional = true }
 httpx = { extras = ["http2"], version = "~0.28.0", optional = true }
 SQLAlchemy = { version = "^2.0.0", optional = true }
 camoufox = { extras = ["geoip"], version = "~0.4.11", optional = true }
+presidio-analyzer = { version = "^2.0.0", optional = true, extras = [
+    "phonenumbers",
+] }
+presidio-anonymizer = { version = "^2.0.0", optional = true }
+spacy = { version = "^3.0.0", optional = true }
+spacy-langdetect = { version = "~0.1.0", optional = true }
 
 [tool.poetry.extras]
 boto3 = ["boto3"]
@@ -127,6 +134,9 @@ peerdb = ["boto3", "clickhouse-driver"]
 proxy = ["stem"]
 alchemy = ["SQLAlchemy"]
 
+# Other groups
+pii = ["presidio-analyzer", "presidio-anonymizer", "spacy", "spacy-langdetect"]
+
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

datamarket-0.9.30/src/datamarket/interfaces/nominatim.py

@@ -0,0 +1,294 @@
+########################################################################################################################
+# IMPORTS
+
+import gettext
+import logging
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import pycountry
+import requests
+from geopy.distance import geodesic
+from jellyfish import jaro_winkler_similarity
+
+from ..params.nominatim import POSTCODES
+from ..utils.strings import normalize
+
+########################################################################################################################
+# PARAMETERS
+
+JARO_WINKLER_THRESHOLD = 0.85
+
+########################################################################################################################
+# CLASSES
+
+logger = logging.getLogger(__name__)
+spanish = gettext.translation("iso3166-1", pycountry.LOCALES_DIR, languages=["es"])
+spanish.install()
+
+
+class GeoNames:
+    def __init__(self, endpoint: str) -> None:
+        self.endpoint = endpoint
+
+    @staticmethod
+    def validate_postcode(postcode: Union[int, str]) -> Optional[str]:
+        if isinstance(postcode, int):
+            postcode = str(postcode)
+
+        if postcode and len(postcode) == 5 and postcode[:2] in POSTCODES:
+            return postcode
+
+        if postcode and len(postcode) == 4:
+            postcode = f"0{postcode}"
+            if postcode[:2] in POSTCODES:
+                return postcode
+
+    @staticmethod
+    def get_province_from_postcode(postcode: Optional[str]) -> Optional[str]:
+        if postcode:
+            return POSTCODES[postcode[:2]]
+
+    def reverse(self, lat: Union[float, str], lon: Union[float, str]) -> Dict[str, Any]:
+        return requests.get(f"{self.endpoint}/reverse?lat={lat}&lon={lon}", timeout=30).json()
+
+
+class Nominatim:
+    def __init__(self, nominatim_endpoint: str, geonames_endpoint: str) -> None:
+        self.endpoint = nominatim_endpoint
+        self.geonames = GeoNames(geonames_endpoint)
+
+    @staticmethod
+    def _get_attribute(raw_json: Dict[str, Any], keys: List[str]) -> Any:
+        for key in keys:
+            if key in raw_json:
+                return raw_json[key]
+
+    def _calculate_distance(self, lat_str: Optional[str], lon_str: Optional[str], input_coords: Tuple[float, float]) -> float:
+        dist = float("inf")
+        if lat_str and lon_str:
+            try:
+                coords = (float(lat_str), float(lon_str))
+                dist = geodesic(input_coords, coords).km
+            except (ValueError, TypeError):
+                logger.warning("Invalid coordinates for distance calculation.")
+        return dist
+
+    def _parse_nominatim_result(self, nominatim_raw_json: Dict[str, Any]) -> Dict[str, Optional[str]]:
+        raw_address = nominatim_raw_json.get("address", {})
+
+        postcode_str = str(raw_address.get("postcode", ""))
+        postcode = self.geonames.validate_postcode(postcode_str)
+
+        city = self._get_attribute(raw_address, ["city", "town", "village"])
+        district, quarter = self._get_district_quarter(raw_address)
+
+        return {
+            "country": raw_address.get("country"),
+            "country_code": (raw_address.get("country_code") or "").lower(),
+            "state": raw_address.get("state"),
+            "province": raw_address.get("province"),
+            "city": city,
+            "postcode": postcode,
+            "district": district,
+            "quarter": quarter,
+            "street": raw_address.get("road"),
+            "number": raw_address.get("house_number"),
+        }
+
+    def _parse_geonames_result(self, geonames_raw_json: Dict[str, Any]) -> Dict[str, Optional[str]]:
+        geonames_country_code_str = geonames_raw_json.get("country_code")
+        country_name = None
+        if geonames_country_code_str:
+            try:
+                country_obj = pycountry.countries.get(alpha_2=geonames_country_code_str.upper())
+                if country_obj:
+                    country_name = spanish.gettext(country_obj.name)
+            except LookupError:
+                logger.warning(f"Country name not found for code: {geonames_country_code_str} using pycountry.")
+
+        postcode_str = str(geonames_raw_json.get("postal_code", ""))
+        postcode = self.geonames.validate_postcode(postcode_str)
+        province = self.geonames.get_province_from_postcode(postcode) if postcode else None
+        city = geonames_raw_json.get("place_name")
+
+        return {
+            "country": country_name,
+            "country_code": (geonames_country_code_str or "").lower(),
+            "state": geonames_raw_json.get("community"),
+            "province": province,
+            "city": city,
+            "postcode": postcode,
+            "district": None,
+            "quarter": None,
+            "street": None,
+            "number": None,
+        }
+
+    def _get_empty_address_result(self) -> Dict[str, None]:
+        return {
+            "country": None,
+            "country_code": None,
+            "state": None,
+            "province": None,
+            "city": None,
+            "postcode": None,
+            "district": None,
+            "quarter": None,
+            "street": None,
+            "number": None,
+        }
+
+    def _select_postcode_and_derived_province(
+        self, parsed_nominatim_result: Dict[str, Optional[str]], parsed_geonames_result: Dict[str, Optional[str]], nominatim_address_province_raw: Optional[str]
+    ) -> Tuple[Optional[str], Optional[str]]:
+        """
+        Determines the postcode and its derived province based on comparisons
+        between Nominatim and GeoNames data, and Nominatim's raw address province.
+        """
+        nominatim_postcode = parsed_nominatim_result.get("postcode")
+        geonames_postcode = parsed_geonames_result.get("postcode")
+
+        province_from_nominatim_postcode = self.geonames.get_province_from_postcode(nominatim_postcode)
+        province_from_geonames_postcode = self.geonames.get_province_from_postcode(geonames_postcode)
+
+        norm_raw_nominatim_province = (
+            normalize(nominatim_address_province_raw) if nominatim_address_province_raw else ""
+        )
+        norm_province_from_nominatim_postcode = (
+            normalize(province_from_nominatim_postcode) if province_from_nominatim_postcode else ""
+        )
+        norm_province_from_geonames_postcode = (
+            normalize(province_from_geonames_postcode) if province_from_geonames_postcode else ""
+        )
+
+        selected_postcode = None
+        selected_province_from_postcode = None
+
+        # If provinces derived from Nominatim and GeoNames postcodes differ
+        nominatim_postcode_province_matches = False
+        if norm_province_from_nominatim_postcode and norm_raw_nominatim_province:
+            nominatim_postcode_province_matches = (
+                jaro_winkler_similarity(norm_province_from_nominatim_postcode, norm_raw_nominatim_province)
+                > JARO_WINKLER_THRESHOLD
+            )
+
+        geonames_postcode_province_matches = False
+        if norm_province_from_geonames_postcode and norm_raw_nominatim_province:
+            geonames_postcode_province_matches = (
+                jaro_winkler_similarity(norm_province_from_geonames_postcode, norm_raw_nominatim_province)
+                > JARO_WINKLER_THRESHOLD
+            )
+
+        # Prefer GeoNames postcode if its province matches Nominatim's raw address province,
+        # and Nominatim's own postcode-derived province does not.
+        if nominatim_postcode_province_matches:
+            selected_postcode = nominatim_postcode
+            selected_province_from_postcode = province_from_nominatim_postcode
+        if geonames_postcode_province_matches and not nominatim_postcode_province_matches:
+            selected_postcode = geonames_postcode
+            selected_province_from_postcode = province_from_geonames_postcode
+
+        return selected_postcode, selected_province_from_postcode
+
+    def _select_final_result(
+        self,
+        parsed_nominatim_result: Dict[str, Optional[str]],
+        parsed_geonames_result: Dict[str, Optional[str]],
+        dist_nominatim: float,
+        dist_geonames: float,
+        authoritative_postcode: Optional[str],
+        authoritative_province_from_postcode: Optional[str],
+        nominatim_address_province_raw: Optional[str],
+    ) -> Dict[str, Optional[str]]:
+        """
+        Selects the final address result based on distances and applies the authoritative postcode/province.
+        """
+        if dist_nominatim <= dist_geonames and dist_nominatim != float("inf"):
+            final_result = parsed_nominatim_result
+            final_result["postcode"] = authoritative_postcode
+            final_result["province"] = nominatim_address_province_raw
+        elif dist_geonames < dist_nominatim and dist_geonames != float("inf"):
+            final_result = parsed_geonames_result
+            final_result["postcode"] = authoritative_postcode
+            final_result["province"] = authoritative_province_from_postcode
+        else:
+            final_result = self._get_empty_address_result()
+        return final_result
+
+    def _get_district_quarter(self, raw_json: Dict[str, Any]) -> Tuple[Optional[str], Optional[str]]:
+        district = self._get_attribute(raw_json, ["city_district", "suburb", "borough"])
+        quarter = self._get_attribute(raw_json, ["quarter", "neighbourhood"])
+
+        if not district and quarter:
+            district = quarter
+            quarter = None
+
+        return district, quarter
+
+    def geocode(self, address: str) -> List[Dict[str, Any]]:
+        return requests.get(f"{self.endpoint}/search?q={address}&format=json", timeout=30).json()
+
+    def geocode_parsed(self, address: str) -> Optional[Dict[str, Optional[str]]]:
+        results = self.geocode(address)
+
+        if results:
+            return self.reverse_parsed(results[0]["lat"], results[0]["lon"])
+
+    def reverse(self, lat: Union[float, str], lon: Union[float, str]) -> Dict[str, Any]:
+        return requests.get(f"{self.endpoint}/reverse?lat={lat}&lon={lon}&format=json", timeout=30).json()
+
+    def reverse_parsed(self, lat: Union[float, str], lon: Union[float, str]) -> Dict[str, Optional[str]]:
+        nominatim_response = self.reverse(lat, lon)
+        geonames_response = self.geonames.reverse(lat, lon)
+
+        # Initial parsing
+        parsed_nominatim_result = self._parse_nominatim_result(nominatim_response)
+        parsed_geonames_result = self._parse_geonames_result(geonames_response)
+
+        # Determine authoritative postcode
+        raw_nominatim_province = nominatim_response.get("address", {}).get("province")
+        selected_postcode, selected_province_from_postcode = self._select_postcode_and_derived_province(
+            parsed_nominatim_result, parsed_geonames_result, raw_nominatim_province
+        )
+
+        # Calculate distances
+        nominatim_response_lat = nominatim_response.get("lat")
+        nominatim_response_lon = nominatim_response.get("lon")
+        geonames_response_lat = geonames_response.get("lat")
+        geonames_response_lon = geonames_response.get("lon")
+
+        input_coords = None
+        try:
+            input_coords = (float(lat), float(lon))
+        except (ValueError, TypeError):
+            logger.error(f"Invalid input coordinates for distance calculation: lat={lat}, lon={lon}")
+            return self._get_empty_address_result()
+
+        dist_nominatim = self._calculate_distance(nominatim_response_lat, nominatim_response_lon, input_coords)
+        dist_geonames = self._calculate_distance(geonames_response_lat, geonames_response_lon, input_coords)
+
+        # Select final result
+        final_result = self._select_final_result(
+            parsed_nominatim_result,
+            parsed_geonames_result,
+            dist_nominatim,
+            dist_geonames,
+            selected_postcode,
+            selected_province_from_postcode,
+            raw_nominatim_province,
+        )
+
+        return final_result
+
+
+class NominatimInterface(Nominatim):
+    def __init__(self, config: Dict[str, Any]) -> None:
+        if "osm" in config:
+            self.config = config["osm"]
+
+            self.nominatim_endpoint = self.config["nominatim_endpoint"]
+            self.geonames_endpoint = self.config["geonames_endpoint"]
+
+            super().__init__(self.nominatim_endpoint, self.geonames_endpoint)
+        else:
+            logger.warning("no osm section in config")

datamarket-0.9.30/src/datamarket/utils/strings/__init__.py

@@ -0,0 +1,2 @@
+from .normalization import *  # noqa: F403
+from .obfuscation import *  # noqa: F403

datamarket-0.9.28/src/datamarket/utils/strings.py → datamarket-0.9.30/src/datamarket/utils/strings/normalization.py

@@ -1,14 +1,14 @@
 ########################################################################################################################
 # IMPORTS
 
+import unicodedata
 from enum import Enum, auto
 from typing import Any
-import unicodedata
 
 import numpy as np
-from unidecode import unidecode
-from inflection import parameterize, underscore, titleize, camelize
+from inflection import camelize, parameterize, titleize, underscore
 from string_utils import prettify, strip_html
+from unidecode import unidecode
 
 ########################################################################################################################
 # CLASSES

datamarket-0.9.30/src/datamarket/utils/strings/obfuscation.py

@@ -0,0 +1,153 @@
+########################################################################################################################
+# IMPORTS
+
+import logging
+import warnings
+from typing import List, Optional
+
+
+class PiiDependenciesMissingError(ImportError):
+    pass
+
+
+class SpacyModelNotFoundError(ImportError):
+    pass
+
+
+try:
+    import phonenumbers
+    import spacy
+    from presidio_analyzer import AnalyzerEngine, RecognizerRegistry
+    from presidio_analyzer.nlp_engine import NlpEngineProvider
+    from presidio_analyzer.predefined_recognizers import PhoneRecognizer
+    from presidio_anonymizer import AnonymizerEngine
+    from spacy.language import Language
+    from spacy_langdetect import LanguageDetector
+except ImportError as e:
+    raise PiiDependenciesMissingError(
+        "One or more PII anonymization dependencies are missing. "
+        "Please install them by running: pip install datamarket[pii]\n"
+        f"Original error: {e}"
+    ) from e
+
+
+########################################################################################################################
+# SETTINGS
+
+logger = logging.getLogger()
+logging.getLogger("presidio-analyzer").setLevel(logging.ERROR)
+
+warnings.filterwarnings(
+    "ignore",
+    message=r"\[W108\]",
+    category=UserWarning,
+    module="spacy.pipeline.lemmatizer",
+)
+
+
+@Language.factory("language_detector")
+def get_lang_detector(nlp, name):
+    return LanguageDetector()
+
+
+########################################################################################################################
+# CLASSES
+
+
+class PiiAnonymizer:
+    SUPPORTED_LANG = ["es", "en"]
+
+    def __init__(self):
+        # Check for required spaCy models
+        required_models = {
+            "en_core_web_md": "python -m spacy download en_core_web_md",
+            "es_core_news_md": "python -m spacy download es_core_news_md",
+        }
+        missing_models_instructions = []
+        for model_name, install_command in required_models.items():
+            if not spacy.util.is_package(model_name):
+                missing_models_instructions.append(
+                    f"Model '{model_name}' not found. Please install it by running: {install_command}"
+                )
+
+        if missing_models_instructions:
+            raise SpacyModelNotFoundError("\n".join(missing_models_instructions))
+
+        self.anonymizer = AnonymizerEngine()
+        self.analyzer = self._load_analyzer_engine()
+
+        self.nlp = self._nlp()
+
+    def _nlp(self) -> Language:
+        analyzer_en_model = self.analyzer.nlp_engine.nlp.get("en")
+        shared_vocab = analyzer_en_model.vocab
+        nlp = spacy.blank("en", vocab=shared_vocab)
+
+        if nlp.has_factory("sentencizer"):
+            nlp.add_pipe("sentencizer")
+
+        if nlp.has_factory("language_detector"):
+            nlp.add_pipe("language_detector", last=True)
+
+        return nlp
+
+    @staticmethod
+    def _nlp_config():
+        return {
+            "nlp_engine_name": "spacy",
+            "models": [
+                {"lang_code": "es", "model_name": "es_core_news_md"},
+                {"lang_code": "en", "model_name": "en_core_web_md"},
+            ],
+        }
+
+    def _load_analyzer_engine(self) -> AnalyzerEngine:
+        provider = NlpEngineProvider(nlp_configuration=PiiAnonymizer._nlp_config())
+        nlp_engine = provider.create_engine()
+        phone_recognizer_es = PhoneRecognizer(
+            supported_language="es",
+            supported_regions=phonenumbers.SUPPORTED_REGIONS,
+            context=["teléfono", "móvil", "número"],
+        )
+        registry = RecognizerRegistry(supported_languages=self.SUPPORTED_LANG)
+        registry.load_predefined_recognizers(nlp_engine=nlp_engine, languages=self.SUPPORTED_LANG)
+        registry.add_recognizer(phone_recognizer_es)
+
+        analyzer = AnalyzerEngine(
+            registry=registry,
+            nlp_engine=nlp_engine,
+            supported_languages=self.SUPPORTED_LANG,
+        )
+        return analyzer
+
+    def detect_lang(self, text: str) -> str:
+        if hasattr(self, "nlp") and self.nlp:
+            with self.nlp.select_pipes(enable=["tokenizer", "sentencizer", "language_detector"]):
+                doc = self.nlp(text)
+            return doc._.language["language"]
+        else:
+            logger.error("Language detection NLP model not initialized. Cannot detect language.")
+            return "unknown"
+
+    def anonymize_text(
+        self,
+        text: str,
+        entities: Optional[List[str]] = None,
+        lang: str = "unknown",
+    ) -> str:
+        if lang == "unknown":
+            lang = self.detect_lang(text)
+            if lang not in self.SUPPORTED_LANG:
+                logger.warning(f"Support for language {lang} is not implemented yet! Fail safe to empty string.")
+                return ""
+        elif lang not in self.SUPPORTED_LANG:
+            logger.warning(f"Support for language {lang} is not implemented yet! Fail safe to empty string.")
+            return ""
+
+        analyzer_result = self.analyzer.analyze(
+            text=text,
+            entities=entities,
+            language=lang,
+        )
+        anonymizer_result = self.anonymizer.anonymize(text=text, analyzer_results=analyzer_result)
+        return anonymizer_result.text

datamarket-0.9.28/src/datamarket/interfaces/nominatim.py

@@ -1,189 +0,0 @@
-########################################################################################################################
-# IMPORTS
-
-import gettext
-import logging
-import pycountry
-from geopy.distance import geodesic
-
-import requests
-
-from ..params.nominatim import POSTCODES
-
-########################################################################################################################
-# CLASSES
-
-logger = logging.getLogger(__name__)
-spanish = gettext.translation("iso3166-1", pycountry.LOCALES_DIR, languages=["es"])
-spanish.install()
-
-
-class GeoNames:
-    def __init__(self, endpoint):
-        self.endpoint = endpoint
-
-    @staticmethod
-    def validate_postcode(postcode):
-        if isinstance(postcode, int):
-            postcode = str(postcode)
-
-        if postcode and len(postcode) == 5 and postcode[:2] in POSTCODES:
-            return postcode
-
-        if postcode and len(postcode) == 4:
-            postcode = f"0{postcode}"
-            if postcode[:2] in POSTCODES:
-                return postcode
-
-    @staticmethod
-    def get_province_from_postcode(postcode):
-        if postcode:
-            return POSTCODES[postcode[:2]]
-
-    def reverse(self, lat, lon):
-        return requests.get(f"{self.endpoint}/reverse?lat={lat}&lon={lon}").json()
-
-
-class Nominatim:
-    def __init__(self, nominatim_endpoint, geonames_endpoint):
-        self.endpoint = nominatim_endpoint
-        self.geonames = GeoNames(geonames_endpoint)
-
-    @staticmethod
-    def get_attribute(raw_json, keys):
-        for key in keys:
-            if key in raw_json:
-                return raw_json[key]
-
-    def geocode(self, address):
-        return requests.get(f"{self.endpoint}/search?q={address}&format=json").json()
-
-    def geocode_parsed(self, address):
-        results = self.geocode(address)
-
-        if results:
-            return self.reverse_parsed(results[0]["lat"], results[0]["lon"])
-
-    def reverse(self, lat, lon):
-        return requests.get(f"{self.endpoint}/reverse?lat={lat}&lon={lon}&format=json").json()
-
-    def reverse_parsed(self, lat, lon):
-        nominatim_raw_json = self.reverse(lat, lon)
-        geonames_raw_json = self.geonames.reverse(lat, lon)
-
-        nominatim_res_lat_str = nominatim_raw_json.get("lat")
-        nominatim_res_lon_str = nominatim_raw_json.get("lon")
-        geonames_res_lat_str = geonames_raw_json.get("lat")
-        geonames_res_lon_str = geonames_raw_json.get("lon")
-
-        dist_nominatim = float("inf")
-        dist_geonames = float("inf")
-
-        try:
-            input_coords = (float(lat), float(lon))
-        except (ValueError, TypeError):
-            logger.error(f"Invalid input coordinates for distance calculation: lat={lat}, lon={lon}")
-        else:
-            if nominatim_res_lat_str and nominatim_res_lon_str:
-                try:
-                    nominatim_coords = (float(nominatim_res_lat_str), float(nominatim_res_lon_str))
-                    dist_nominatim = geodesic(input_coords, nominatim_coords).km
-                except (ValueError, TypeError):
-                    logger.warning("Invalid Nominatim coordinates for distance calculation.")
-
-            if geonames_res_lat_str and geonames_res_lon_str:
-                try:
-                    geonames_coords = (float(geonames_res_lat_str), float(geonames_res_lon_str))
-                    dist_geonames = geodesic(input_coords, geonames_coords).km
-                except (ValueError, TypeError):
-                    logger.warning("Invalid GeoNames coordinates for distance calculation.")
-
-        if dist_nominatim <= dist_geonames and nominatim_res_lat_str is not None and nominatim_res_lon_str is not None:
-            # Use Nominatim data
-            raw_address = nominatim_raw_json.get("address", {})
-            postcode_str = str(raw_address.get("postcode", ""))
-            postcode = self.geonames.validate_postcode(postcode_str)
-            province = self.geonames.get_province_from_postcode(postcode) if postcode else None
-            city = self.get_attribute(raw_address, ["city", "town", "village"])
-            district, quarter = self.get_district_quarter(raw_address)
-
-            return {
-                "country": raw_address.get("country"),
-                "country_code": (raw_address.get("country_code") or "").lower(),
-                "state": raw_address.get("state"),
-                "province": province,
-                "city": city,
-                "postcode": postcode,
-                "district": district,
-                "quarter": quarter,
-                "street": raw_address.get("road"),
-                "number": raw_address.get("house_number"),
-            }
-
-        elif dist_geonames < dist_nominatim and geonames_res_lat_str is not None and geonames_res_lon_str is not None:
-            # Use GeoNames data
-            geonames_country_code_str = geonames_raw_json.get("country_code")
-            country_name = None
-            if geonames_country_code_str:
-                try:
-                    country_obj = pycountry.countries.get(alpha_2=geonames_country_code_str.upper())
-                    if country_obj:
-                        country_name = spanish.gettext(country_obj.name)
-                except LookupError:
-                    logger.warning(f"Country name not found for code: {geonames_country_code_str} using pycountry.")
-
-            postcode_str = str(geonames_raw_json.get("postal_code", ""))
-            postcode = self.geonames.validate_postcode(postcode_str)
-            province = self.geonames.get_province_from_postcode(postcode) if postcode else None
-            city = geonames_raw_json.get("place_name")
-
-            return {
-                "country": country_name,
-                "country_code": (geonames_country_code_str or "").lower(),
-                "state": geonames_raw_json.get("community"),
-                "province": province,
-                "city": city,
-                "postcode": postcode,
-                "district": None,
-                "quarter": None,
-                "street": None,
-                "number": None,
-            }
-
-        else:
-            # Neither source provided valid coordinates
-            return {
-                "country": None,
-                "country_code": None,
-                "state": None,
-                "province": None,
-                "city": None,
-                "postcode": None,
-                "district": None,
-                "quarter": None,
-                "street": None,
-                "number": None,
-            }
-
-    def get_district_quarter(self, raw_json):
-        district = self.get_attribute(raw_json, ["city_district", "suburb", "borough"])
-        quarter = self.get_attribute(raw_json, ["quarter", "neighbourhood"])
-
-        if not district and quarter:
-            district = quarter
-            quarter = None
-
-        return district, quarter
-
-
-class NominatimInterface(Nominatim):
-    def __init__(self, config):
-        if "osm" in config:
-            self.config = config["osm"]
-
-            self.nominatim_endpoint = self.config["nominatim_endpoint"]
-            self.geonames_endpoint = self.config["geonames_endpoint"]
-
-            super().__init__(self.nominatim_endpoint, self.geonames_endpoint)
-        else:
-            logger.warning("no osm section in config")