pyhemnet 0.1.0__py3-none-any.whl

pyhemnet/__init__.py

@@ -0,0 +1,15 @@
+"""Swedish Real Estate Scraper - Scrape data from Hemnet.se"""
+
+__version__ = "0.1.0"
+__author__ = "ningdp2012"
+
+# Import scraper classes
+from .hemnet import HemnetScraper
+
+# Import enums
+from .constants import HemnetItemType
+
+__all__ = [
+    "HemnetScraper",
+    "HemnetItemType",
+]

pyhemnet/constants.py

@@ -0,0 +1,21 @@
+"""Constants for Hemnet scraper"""
+
+from enum import Enum
+
+
+class HemnetItemType(str, Enum):
+    """Hemnet property item types"""
+    VILLA = "villa"
+    RADHUS = "radhus"
+    BOSTADSRATT = "bostadsratt"
+    FRITIDSHUS = "fritidshus"
+    TOMT = "tomt"
+    GARD = "gard"
+    OTHER = "other"
+
+
+# Hemnet URLs mapping
+HEMNET_URLS = {
+    "listings": "https://www.hemnet.se/bostader",
+    "sold": "https://www.hemnet.se/salda/bostader"
+}

pyhemnet/hemnet.py

@@ -0,0 +1,376 @@
+"""Hemnet scraper module for property sales data extraction"""
+
+import datetime as dt
+import json
+import logging
+import re
+
+import cloudscraper
+from bs4 import BeautifulSoup
+
+from .constants import HEMNET_URLS, HemnetItemType
+
+logger = logging.getLogger(__name__)
+
+
+class HemnetScraper:
+    """Scraper for Hemnet property sales data
+
+    Examples:
+        >>> scraper = HemnetScraper()
+        >>> listing, sold = scraper.get_summary(location_id="17932")
+        >>> homes = scraper.get_sold(
+        ...     location_id="17932",
+        ...     item_types=[HemnetItemType.VILLA, HemnetItemType.RADHUS]
+        ... )
+
+        # With strings
+        >>> homes = scraper.get_sold(
+        ...     location_id="17932",
+        ...     item_types=["villa", "radhus"]
+        ... )
+    """
+
+    def __init__(self):
+        """Initialize the Hemnet scraper"""
+        self.scraper = cloudscraper.create_scraper()
+
+    def _build_url(
+        self,
+        url_type: str,
+        location_id: str | None = None,
+        item_types: list[HemnetItemType | str] | None = None
+    ) -> str:
+        """Build URL dynamically based on type (internal)
+
+        Args:
+            url_type: Type of URL to build ('listings' or 'sold')
+            location_id: Hemnet location ID (optional)
+            item_types: List of property types (optional)
+
+        Returns:
+            Constructed URL string
+
+        Raises:
+            ValueError: If url_type is invalid
+        """
+        # Select base URL
+        base_url = HEMNET_URLS.get(url_type)
+        if base_url is None:
+            raise ValueError(f"Invalid url_type: {url_type}. Must be 'listings' or 'sold'")
+
+        params = []
+
+        # Add location_id if provided
+        if location_id:
+            params.append(f"location_ids[]={location_id}")
+
+        # Add item_types if provided
+        if item_types:
+            item_type_strs = [t.value if isinstance(t, HemnetItemType) else t for t in item_types]
+            for item_type in item_type_strs:
+                params.append(f"item_types[]={item_type}")
+
+        # Add sorting parameters
+        if url_type == 'listings':
+            params.extend(["by=creation", "order=desc"])
+        else:  # sold
+            params.extend(["by=sale_date", "order=desc"])
+
+        # Build final URL
+        if params:
+            return f"{base_url}?{'&'.join(params)}"
+        return base_url
+
+    def _make_request(self, url: str) -> dict:
+        """Fetch and parse JSON data from Hemnet page (internal)
+
+        Args:
+            url: URL to scrape
+
+        Returns:
+            Parsed JSON data from page
+
+        Raises:
+            ValueError: If JSON data cannot be found or parsed
+        """
+        response = self.scraper.get(url)
+        response.raise_for_status()
+
+        soup = BeautifulSoup(response.text, "html.parser")
+        script_tag = soup.find("script", id="__NEXT_DATA__")
+
+        if not script_tag or not script_tag.string:
+            raise ValueError(f"Could not find JSON data in page: {url}")
+
+        try:
+            return json.loads(script_tag.string)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse JSON data from {url}: {e}")
+
+    @staticmethod
+    def _extract_int(value: str | None, default: int = 0) -> int:
+        """Extract integer from string by removing non-digits (internal helper)"""
+        if not value:
+            return default
+        cleaned = re.sub(r"[^\d]", "", str(value))
+        return int(cleaned) if cleaned else default
+
+    @staticmethod
+    def _extract_housing_type(data: dict) -> str | None:
+        """Extract housing type from housing form data (internal helper)"""
+        housing_form = data.get("housingForm")
+        return housing_form.get("name") if isinstance(housing_form, dict) else None
+
+    @staticmethod
+    def _extract_labels(data: dict) -> list[str]:
+        """Extract text labels from label data (internal helper)"""
+        return [
+            label["text"]
+            for label in data.get("labels", [])
+            if isinstance(label, dict) and "text" in label
+        ]
+
+    @staticmethod
+    def _format_timestamp(timestamp: int | None) -> str | None:
+        """Format Unix timestamp to YYYY-MM-DD string (internal helper)"""
+        if not timestamp:
+            return None
+        return dt.datetime.fromtimestamp(float(timestamp)).strftime("%Y-%m-%d")
+
+    @staticmethod
+    def _clean_area_string(value: str | None) -> str:
+        """Clean area string by replacing non-breaking spaces (internal helper)"""
+        return re.sub(r"\xa0", " ", str(value or "0"))
+
+    def _parse_summary(self, json_data: dict) -> tuple[int, int]:
+        """Extract total listings and sold homes from JSON data (internal)
+
+        Args:
+            json_data: Parsed JSON data from page
+
+        Returns:
+            Tuple of (total_listings, total_sold)
+
+        Raises:
+            ValueError: If required data is missing or invalid
+        """
+        try:
+            summary = json_data["props"]["pageProps"]["__APOLLO_STATE__"]["ROOT_QUERY"]
+
+            # Find listing data
+            listing_data = next(
+                (v for k, v in summary.items() if k.startswith("searchForSaleListings")),
+                None
+            )
+            if listing_data is None or "total" not in listing_data:
+                raise ValueError("Missing searchForSaleListings data")
+
+            # Find sold data
+            sold_data = next(
+                (v for k, v in summary.items() if k.startswith("searchSales")),
+                None
+            )
+            if sold_data is None or "total" not in sold_data:
+                raise ValueError("Missing searchSales data")
+
+            listing = int(listing_data["total"])
+            sold = int(sold_data["total"])
+
+            return listing, sold
+
+        except (KeyError, TypeError) as e:
+            raise ValueError(f"Invalid JSON structure: {e}")
+        except ValueError as e:
+            if "invalid literal" in str(e):
+                raise ValueError(f"Non-numeric total value: {e}")
+            raise
+
+    def _parse_listing_details(self, json_data: dict) -> list[dict]:
+        """Extract details of active listings from JSON data (internal)
+
+        Args:
+            json_data: Parsed JSON data from page
+
+        Returns:
+            List of dictionaries containing home details
+
+        Raises:
+            ValueError: If required data structure is missing or invalid
+        """
+        try:
+            details = json_data["props"]["pageProps"]["__APOLLO_STATE__"]
+        except (KeyError, TypeError) as e:
+            raise ValueError(f"Invalid JSON structure for details: {e}")
+
+        # Use list comprehension instead of dict comprehension + .values()
+        listing_cards = [
+            value for key, value in details.items()
+            if key.startswith("ListingCard:") and isinstance(value, dict) and value.get("__typename") == "ListingCard"
+        ]
+
+        homes = []
+        for data in listing_cards:
+            try:
+                homes.append({
+                    "id": data.get("id"),
+                    "address": data.get("streetAddress"),
+                    "location": data.get("locationDescription"),
+                    "housing_type": self._extract_housing_type(data),
+                    "rooms": self._extract_int(data.get("rooms")),
+                    "living_area": self._clean_area_string(data.get("livingAndSupplementalAreas")),
+                    "land_area": self._clean_area_string(data.get("landArea")),
+                    "asking_price": self._extract_int(data.get("askingPrice")),
+                    "published_at": self._format_timestamp(data.get("publishedAt")),
+                    "removed_before_showing": data.get("removedBeforeShowing"),
+                    "new_construction": data.get("newConstruction"),
+                    "broker_name": data.get("brokerName"),
+                    "broker_agent": data.get("brokerAgencyName"),
+                    "labels": self._extract_labels(data),
+                    "description": data.get("description"),
+                })
+            except (ValueError, TypeError, AttributeError) as e:
+                # Skip individual listings with bad data rather than failing entire parse
+                logger.debug(f"Skipping listing {data.get('id', 'unknown')}: {e}")
+                continue
+
+        return homes
+
+    def _parse_sold_details(self, json_data: dict) -> list[dict]:
+        """Extract details of sold homes from JSON data (internal)
+
+        Args:
+            json_data: Parsed JSON data from page
+
+        Returns:
+            List of dictionaries containing home details
+
+        Raises:
+            ValueError: If required data structure is missing or invalid
+        """
+        try:
+            details = json_data["props"]["pageProps"]["__APOLLO_STATE__"]
+        except (KeyError, TypeError) as e:
+            raise ValueError(f"Invalid JSON structure for details: {e}")
+
+        # Use list comprehension instead of dict comprehension + .values()
+        sale_cards = [
+            value for key, value in details.items()
+            if key.startswith("SaleCard:") and isinstance(value, dict) and value.get("__typename") == "SaleCard"
+        ]
+
+        homes = []
+        for data in sale_cards:
+            try:
+                homes.append({
+                    "id": data.get("id"),
+                    "listing_id": data.get("listingId"),
+                    "address": data.get("streetAddress"),
+                    "location": data.get("locationDescription"),
+                    "housing_type": self._extract_housing_type(data),
+                    "rooms": self._extract_int(data.get("rooms")),
+                    "living_area": self._clean_area_string(data.get("livingArea")),
+                    "land_area": self._clean_area_string(data.get("landArea")),
+                    "asking_price": self._extract_int(data.get("askingPrice")),
+                    "final_price": self._extract_int(data.get("finalPrice")),
+                    "price_change": self._clean_area_string(data.get("priceChange")),
+                    "sold_at": self._format_timestamp(data.get("soldAt")),
+                    "broker": data.get("brokerAgencyName"),
+                    "labels": self._extract_labels(data),
+                })
+            except (ValueError, TypeError, AttributeError) as e:
+                # Skip individual listings with bad data rather than failing entire parse
+                logger.debug(f"Skipping sold home {data.get('id', 'unknown')}: {e}")
+                continue
+
+        return homes
+
+    def get_summary(
+        self,
+        location_id: str | None = None,
+        item_types: list[HemnetItemType | str] | None = None
+    ) -> tuple[int, int]:
+        """Get summary statistics for all properties
+
+        Args:
+            location_id: Hemnet location ID (optional)
+            item_types: List of property types (optional)
+
+        Returns:
+            Tuple of (total_listings, total_sold)
+
+        Raises:
+            ValueError: If the page structure is invalid or data cannot be parsed
+            requests.exceptions.HTTPError: If the HTTP request fails
+        """
+        try:
+            url = self._build_url('listings', location_id, item_types)
+            json_data = self._make_request(url)
+            listing, sold = self._parse_summary(json_data)
+            return listing, sold
+        except ValueError as e:
+            raise ValueError(f"Failed to get summary statistics: {e}")
+
+    def get_listings(
+        self,
+        location_id: str | None = None,
+        item_types: list[HemnetItemType | str] | None = None
+    ) -> list[dict]:
+        """Get detailed listings for properties currently for sale
+
+        Args:
+            location_id: Hemnet location ID (optional)
+            item_types: List of property types (optional)
+        Returns:
+            List of dictionaries containing property details
+        Raises:
+            ValueError: If the page structure is invalid or data cannot be parsed
+            requests.exceptions.HTTPError: If the HTTP request fails
+        """
+        try:
+            url = self._build_url('listings', location_id, item_types)
+            json_data = self._make_request(url)
+            listings = self._parse_listing_details(json_data)
+            return listings
+        except ValueError as e:
+            raise ValueError(f"Failed to get property listings: {e}")
+
+    def get_sold(
+        self,
+        location_id: str | None = None,
+        item_types: list[HemnetItemType | str] | None = None
+    ) -> list[dict]:
+        """Get detailed listings for sold homes
+
+        Args:
+            location_id: Hemnet location ID (optional)
+            item_types: List of property types (optional)
+
+        Returns:
+            List of dictionaries containing sold home details, where each dict has:
+                - id: Hemnet ID
+                - listing_id: Listing identifier
+                - address: Street address
+                - location: Location description
+                - housing_type: Type of housing (villa, apartment, etc.)
+                - rooms: Number of rooms
+                - living_area: Living area with units
+                - land_area: Land area with units
+                - asking_price: Initial asking price (int)
+                - final_price: Final sold price (int)
+                - price_change: Price change information
+                - sold_at: Sale date (YYYY-MM-DD format or None)
+                - broker: Broker agency name
+                - labels: List of property labels/tags
+
+        Raises:
+            ValueError: If the page structure is invalid or data cannot be parsed
+            requests.exceptions.HTTPError: If the HTTP request fails
+        """
+        try:
+            url = self._build_url('sold', location_id, item_types)
+            json_data = self._make_request(url)
+            homes = self._parse_sold_details(json_data)
+            return homes
+        except ValueError as e:
+            raise ValueError(f"Failed to get sold homes listings: {e}")

pyhemnet-0.1.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: pyhemnet
+Version: 0.1.0
+Summary: A Python library for accessing Hemnet.se property data
+Author-email: ningdp2012 <ningdp2012@example.com>
+License: MIT
+Project-URL: Repository, https://github.com/ningdp2012/pyhemnet
+Keywords: hemnet,real estate,sweden,property,housing,data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cloudscraper>=1.2.71
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# PyHemnet
+
+A Python library for accessing Hemnet.se property data. Extract property sales information including prices, locations, sizes, and detailed property characteristics.
+
+## Features
+
+- 🏠 **Hemnet Data Access**: Access property sales data from Hemnet.se
+  - Get summary statistics on properties for sale and sold properties
+  - Extract detailed information including prices, location, size, broker, and more
+  - Filter by location and property types
+  - Support for multiple property types (villa, radhus, bostadsrätt, etc.)
+
+- 🚀 Easy-to-use Python API
+- 💻 Object-oriented design with clean interfaces
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install pyhemnet
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/ningdp2012/pyhemnet.git
+cd pyhemnet
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from pyhemnet import HemnetScraper, HemnetItemType
+
+# Create a scraper instance
+scraper = HemnetScraper()
+
+# Get summary statistics
+listing_count, sold_count = scraper.get_summary(location_id="17744")
+print(f"Properties for sale: {listing_count}")
+print(f"Sold properties: {sold_count}")
+
+# Get detailed sold properties
+homes = scraper.get_sold(
+    location_id="17744",
+    item_types=[HemnetItemType.VILLA, HemnetItemType.RADHUS]
+)
+
+for home in homes:
+    print(f"{home['address']} - {home['final_price']} SEK")
+```
+
+## Usage
+
+### Initialize the Scraper
+
+```python
+from pyhemnet import HemnetScraper, HemnetItemType
+
+scraper = HemnetScraper()
+```
+
+### Get Summary Statistics
+
+Get counts of properties for sale and sold:
+
+```python
+# Get summary for a specific location
+listing_count, sold_count = scraper.get_summary(location_id="17744")
+print(f"For sale: {listing_count}, Sold: {sold_count}")
+
+# Filter by property types
+listing_count, sold_count = scraper.get_summary(
+    location_id="17744",
+    item_types=[HemnetItemType.VILLA]
+)
+```
+
+### Get Sold Properties
+
+Retrieve detailed information about sold properties:
+
+```python
+homes = scraper.get_sold(
+    location_id="17744",
+    item_types=[HemnetItemType.VILLA, HemnetItemType.RADHUS]
+)
+
+for home in homes:
+    print(f"Address: {home['address']}")
+    print(f"Final price: {home['final_price']} SEK")
+    print(f"Asking price: {home['asking_price']} SEK")
+    print(f"Living area: {home['living_area']}")
+    print(f"Sold date: {home['sold_at']}")
+    print("---")
+```
+
+### Get Current Listings
+
+Get properties currently for sale:
+
+```python
+listings = scraper.get_listings(
+    location_id="17744",
+    item_types=[HemnetItemType.BOSTADSRATT]
+)
+
+for listing in listings:
+    print(f"Address: {listing['address']}")
+    print(f"Price: {listing['asking_price']} SEK")
+    print(f"Published: {listing['published_at']}")
+```
+
+### Property Types
+
+Use the `HemnetItemType` enum or strings:
+
+```python
+# Using enum (recommended)
+item_types = [HemnetItemType.VILLA, HemnetItemType.RADHUS]
+
+# Using strings
+item_types = ["villa", "radhus"]
+```
+
+Available types:
+- `VILLA` - Detached houses
+- `RADHUS` - Townhouses
+- `BOSTADSRATT` - Condominiums
+- `FRITIDSHUS` - Vacation homes
+- `TOMT` - Land plots
+- `GARD` - Farms
+- `OTHER` - Other property types
+
+## Data Structure
+
+### Sold Property Data
+
+Each sold property dictionary contains:
+
+```python
+{
+    'id': str,              # Hemnet ID
+    'listing_id': str,      # Listing identifier
+    'address': str,         # Street address
+    'location': str,        # Location description
+    'housing_type': str,    # Type of housing (Villa, Radhus, etc.)
+    'rooms': int,           # Number of rooms
+    'living_area': str,     # Living area with units
+    'land_area': str,       # Land area with units
+    'asking_price': int,    # Initial asking price in SEK
+    'final_price': int,     # Final sold price in SEK
+    'price_change': str,    # Price change information
+    'sold_at': str,         # Sale date (YYYY-MM-DD format)
+    'broker': str,          # Broker agency name
+    'labels': list,         # List of property labels/tags
+}
+```
+
+### Current Listing Data
+
+Each listing dictionary contains:
+
+```python
+{
+    'id': str,                      # Hemnet ID
+    'address': str,                 # Street address
+    'location': str,                # Location description
+    'housing_type': str,            # Type of housing
+    'rooms': int,                   # Number of rooms
+    'living_area': str,             # Living area with units
+    'land_area': str,               # Land area with units
+    'asking_price': int,            # Asking price in SEK
+    'published_at': str,            # Publication date (YYYY-MM-DD)
+    'removed_before_showing': bool, # Removed before showing
+    'new_construction': bool,       # New construction flag
+    'broker_name': str,             # Broker name
+    'broker_agent': str,            # Broker agency name
+    'labels': list,                 # List of property labels/tags
+    'description': str,             # Property description
+}
+```
+
+## Finding Location IDs
+
+To find Hemnet location IDs:
+
+1. Go to [Hemnet.se](https://www.hemnet.se)
+2. Search for your desired location
+3. Look at the URL - it contains `location_ids[]=XXXXX`
+4. Use that ID in your code
+
+Example: For Stockholm `https://www.hemnet.se/bostader?location_ids[]=17744`, use `location_id="17744"`
+
+## Requirements
+
+- Python 3.10+
+- cloudscraper >= 1.2.71
+- beautifulsoup4 >= 4.12.0
+- requests >= 2.31.0
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Disclaimer
+
+This package is created for exploring python and web technologies and learning purposes only. It is **not intended for production use** or commercial applications.
+
+- This is an unofficial package and is not affiliated with or endorsed by Hemnet AB
+- Always respect website terms of service and robots.txt directives
+- Web scraping may be subject to legal restrictions in your jurisdiction
+- Use at your own risk and responsibility

pyhemnet-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyhemnet/__init__.py,sha256=-hgN9WjtWMIUYjao_srqn6xktng-51QjTbWhjQl1tdQ,284
+pyhemnet/constants.py,sha256=3v7G619txdvZ-q1Zxd98kMc4bufnG4m9-5hfCuZJxeA,433
+pyhemnet/hemnet.py,sha256=qmvvLVz4h9W2GqHj4EvpESDrBieCbPmzQP0nOqo1CKs,14127
+pyhemnet-0.1.0.dist-info/licenses/LICENSE,sha256=jioEY5W5ia2JjY7G4XxApk1kQzME4_VzF7-loVgmxdk,1067
+pyhemnet-0.1.0.dist-info/METADATA,sha256=0Ku68TDH1sDkmxZccgzJorXcqHRc28UQGFYeg5OIymo,7026
+pyhemnet-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyhemnet-0.1.0.dist-info/top_level.txt,sha256=mYcB9sSjBU_pBJ-XRjSbxlW76JUS0g6F265MSHUD8jY,9
+pyhemnet-0.1.0.dist-info/RECORD,,

pyhemnet-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyhemnet-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ningdp2012
+
+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.

pyhemnet-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyhemnet