blocket-api 0.2.5__py3-none-any.whl

blocket_api/__init__.py

@@ -0,0 +1,2 @@
+from .blocket import BlocketAPI as BlocketAPI
+from .blocket import Region as Region

blocket_api/blocket.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+import urllib
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any, List, Literal, Optional, Tuple
+
+import httpx
+
+if TYPE_CHECKING:
+    from httpx import Response
+
+BASE_URL = "https://api.blocket.se"
+SITE_URL = "https://www.blocket.se"
+BYTBIL_URL = "https://api.bytbil.com"
+
+
+class Region(Enum):
+    hela_sverige = 0
+    östergötland = 14
+    blekinge = 22
+    dalarna = 6
+    gotland = 19
+    gävleborg = 5
+    göteborg = 15
+    halland = 20
+    jämtland = 3
+    jönköping = 17
+    kalmar = 18
+    kronoberg = 21
+    norrbotten = 1
+    skaraborg = 13
+    skåne = 23
+    stockholm = 11
+    södermanland = 12
+    uppsala = 10
+    värmland = 7
+    västerbotten = 2
+    västernorrland = 4
+    västmanland = 9
+    älvsborg = 16
+    örebro = 8
+
+
+MAKE_OPTIONS = Literal[
+    "Audi",
+    "BMW",
+    "Chevrolet",
+    "Citroën",
+    "Ford",
+    "Honda",
+    "Hyundai",
+    "Kia",
+    "Mazda",
+    "Mercedes-Benz",
+    "Nissan",
+    "Opel",
+    "Peugeot",
+    "Renault",
+    "Saab",
+    "Skoda",
+    "Subaru",
+    "Toyota",
+    "Volkswagen",
+    "Volvo",
+]
+
+FUEL_OPTIONS = Literal["Diesel", "Bensin", "El", "Miljöbränsle/Hybrid"]
+CHASSI_OPTIONS = Literal[
+    "Kombi", "SUV", "Sedan", "Halvkombi", "Coupé", "Cab", "Familjebuss", "Yrkesfordon"
+]
+GEARBOX_OPTIONS = Literal["Automat", "Manuell"]
+
+
+class APIError(Exception): ...
+
+
+class LimitError(Exception): ...
+
+
+class TokenError(Exception): ...
+
+
+def auth_token(method: Callable) -> Callable:
+    @wraps(method)
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Callable:
+        if not self.token:
+            raise TokenError("Token is required, see documentation.")
+        return method(self, *args, **kwargs)
+
+    return wrapper
+
+
+def public_token(method: Callable) -> Callable:
+    @wraps(method)
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Callable:
+        if not self.token:
+            response = httpx.get(
+                f"{SITE_URL}/api/adout-api-route/refresh-token-and-validate-session"
+            )
+            response.raise_for_status()
+            self.token = response.json()["bearerToken"]
+        return method(self, *args, **kwargs)
+
+    return wrapper
+
+
+def _make_request(
+    *, url: str, token: str | None, raise_for_status: bool = True
+) -> Response:
+    headers = {
+        "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 Firefox/128.0"
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    try:
+        response = httpx.get(url, headers=headers)
+        if raise_for_status:
+            response.raise_for_status()
+    except Exception as E:
+        raise APIError(E)
+    return response
+
+
+@dataclass
+class BlocketAPI:
+    token: str | None = None
+
+    @auth_token
+    def saved_searches(self) -> list[dict]:
+        """
+        Retrieves saved searches data, also known as "Bevakningar".
+        """
+        assert self.token
+
+        searches = (
+            _make_request(url=f"{BASE_URL}/saved/v2/searches", token=self.token)
+            .json()
+            .get("data", [])
+        )
+        mobility_searches = (
+            _make_request(
+                url=f"{BASE_URL}/mobility-saved-searches/v1/searches", token=self.token
+            )
+            .json()
+            .get("data", [])
+        )
+
+        return searches + mobility_searches
+
+    def _for_search_id(self, search_id: int, limit: int) -> dict:
+        assert self.token
+        searches = _make_request(
+            url=f"{BASE_URL}/saved/v2/searches_content/{search_id}?lim={limit}",
+            token=self.token,
+            raise_for_status=False,
+        )
+        if searches.status_code == 404:
+            mobility_searches = _make_request(
+                url=f"{BASE_URL}/mobility-saved-searches/v1/searches/{search_id}/ads?lim={limit}",
+                token=self.token,
+                raise_for_status=True,
+            )
+            return mobility_searches.json()
+        return searches.json()
+
+    @auth_token
+    def get_listings(self, search_id: int | None = None, limit: int = 99) -> dict:
+        """
+        Retrieve listings/ads based on the provided search criteria.
+        """
+        assert self.token
+
+        if limit > 99:
+            raise LimitError("Limit cannot be greater than 99.")
+
+        if search_id:
+            return self._for_search_id(search_id, limit)
+
+        return _make_request(
+            url=BASE_URL + f"/saved/v2/searches_content?lim={limit}",
+            token=self.token,
+        ).json()
+
+    @public_token
+    def custom_search(
+        self, search_query: str, region: Region = Region.hela_sverige, limit: int = 99
+    ) -> dict:
+        """
+        Do a custom search through out all of Blocket.
+        Supply a region for filtering. Default is all of Sweden.
+        """
+        assert self.token
+
+        if limit > 99:
+            raise LimitError("Limit cannot be greater than 99.")
+
+        return _make_request(
+            url=f"{BASE_URL}/search_bff/v2/content?lim={limit}&q={search_query}&r={region.value}&status=active",
+            token=self.token,
+        ).json()
+
+    @public_token
+    def motor_search(
+        self,
+        page: int,
+        make: List[MAKE_OPTIONS],
+        fuel: Optional[List[FUEL_OPTIONS]] = None,
+        chassi: Optional[List[CHASSI_OPTIONS]] = None,
+        price: Optional[Tuple[int, int]] = None,
+        modelYear: Optional[Tuple[int, int]] = None,
+        milage: Optional[Tuple[int, int]] = None,
+        gearbox: Optional[GEARBOX_OPTIONS] = None,
+    ) -> dict:
+        """
+        Search specifically in the car section of Blocket
+        with set optional parameters for filtering.
+        """
+        assert self.token
+
+        range_params = ["price", "modelYear", "milage"]
+        set_params = {
+            key: value
+            for key, value in locals().items()
+            if key not in ["self", "page", "range_params"] and value is not None
+        }
+
+        filters = []
+        for param, value in set_params.items():
+            filter = {"key": param, "values": value}
+            if param in range_params:
+                range_start, range_end = filter.pop("values")
+                filter["range"] = {
+                    "start": str(range_start),
+                    "end": str(range_end),
+                }
+            filter_str = urllib.parse.quote(str(filter).replace("'", '"'))
+            filters.append(filter_str)
+
+        motor_base_url = f"{BASE_URL}/motor-search-service/v4/search/car"
+
+        filters_str = "&".join([f"filter={f}" for f in filters])
+        url = f"{motor_base_url}?{filters_str}&page={page}"
+
+        return _make_request(url=f"{url}", token=self.token).json()
+
+    @public_token
+    def price_eval(
+        self,
+        registration_number: str,
+    ) -> dict:
+        """
+        Price evaluation for a specific vehicle by using cars
+        registration number (ABC123).
+
+        This is using same api endpoint as https://www.blocket.se/tjanster/vardera-bil.
+        """
+        url = f"{BYTBIL_URL}/blocket-basedata-api/v3/vehicle-data/{registration_number}"
+        return _make_request(url=f"{url}", token=None).json()

blocket_api-0.2.5.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: blocket_api
+Version: 0.2.5
+Summary: A python API wrapper for blocket.se
+Author-email: dunderrrrrr <emil.bjorkroth@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pre-commit>=3.7.1
+Requires-Dist: ruff>=0.5.2
+Requires-Dist: pytest>=8.2.2
+Requires-Dist: respx>=0.21.1
+Requires-Dist: mypy>=1.15.0
+Dynamic: license-file
+
+# BlocketAPI
+
+[![PyPI version](https://img.shields.io/pypi/v/blocket_api?style=for-the-badge)](https://pypi.org/project/blocket_api/) [![License](https://img.shields.io/badge/license-WTFPL-green?style=for-the-badge)](https://github.com/dunderrrrrr/blocket_api/blob/main/LICENSE) [![Python versions](https://img.shields.io/pypi/pyversions/blocket-api?style=for-the-badge)](https://pypi.org/project/blocket_api/) ![PyPI - Downloads](https://img.shields.io/pypi/dm/blocket_api?style=for-the-badge&color=%23dbce58)
+
+BlocketAPI allows users to query saved searches, known as "Bevakningar", on [blocket.se](https://blocket.se/). This means you can either retrieve results from a specific saved search or list all listings/ads across all saved searches. The results from these queries are returned in a `json` format.
+
+> Blocket is one of Sweden's largest online marketplaces. It was founded in 1996 and allows users to buy and sell a wide range of items, including cars, real estate, jobs, services, and second-hand goods. The platform is known for its extensive reach and user-friendly interface, making it a popular choice for Swedes looking to purchase or sell items quickly and efficiently.
+
+## ✨ Features
+
+- List saved searches, called "Bevakningar".
+- Query all listings/ads filtered on a region.
+- Query listings related to a saved search.
+- Use motor search to query listings related to a specific car.
+
+## 🧑‍💻️ Install
+
+BlocketAPI is available on PyPI.
+
+```sh
+pip install blocket-api
+```
+
+## 💁‍♀️ Usage
+
+```py
+>>> from blocket_api import BlocketAPI
+>>> api = BlocketAPI("YourBlocketTokenHere")
+>>> print(api.saved_searches())
+...
+>>> print(BlocketAPI().custom_search("saab")) # no token required
+...
+```
+
+Some calls require a bearerToken. However, some calls are public and don't require a token.
+
+[Where token?](#-blocket-api-token)
+
+
+| Function  | Token required | Description  |
+|---|---|---|
+| [`api.saved_searches()`](#saved_searches) | 🔐 Yes | List your saved searches (bevakningar)  |
+| [`api.get_listings()`](#get_listingssearch_id-limit) | 🔐 Yes | List items related to a saved search |
+| [`api.custom_search()`](#custom_searchsearch_query-region-limit)  | 👏 No | Search for everything on Blocket and filter by region |
+| [`api.motor_search()`](#motor_searchpage-make-fuel-chassi-price-modelyear-milage-gearbox)  | 👏 No | Advanced search for car-listings. |
+| [`api.price_eval()`](#price_evalregistration_number)  | 👏 No | Vehicle purchase valuation and details. | 
+
+## 🤓 Detailed usage
+
+### saved_searches()
+
+Saved searches are your so called "Bevakningar" and can be found [here](https://www.blocket.se/sparade/bevakningar). Each saved search has and unique `id` which can be used as a parameter to `get_listings()`, see below.
+
+```py
+>>> api.saved_searches()
+[
+   {
+      "id":"4150081",
+      "new_count":0,
+      "total_count":41,
+      "push_enabled":false,
+      "push_available":true,
+      "query":"cg=1020&q=buggy&st=s",
+      "name":"\"buggy\", Bilar säljes i hela Sverige"
+   },
+]
+```
+
+### get_listings(search_id, limit)
+Returns all listings related to a saved search.
+
+Parameters:
+- `search_id` (`int`, optional) - Get listings for a specific saved search. If not provided, all saved searches will be combined.
+- `limit` (`int`, optional) - Limit number of results returned, max is 99.
+
+```py
+>>> api.get_listings(4150081)
+{
+   "data":[
+      {
+         "ad":{
+            "ad_id":"1401053984",
+            "list_id":"1401053984",
+            "zipcode":"81290",
+            "ad_status":"active",
+            "list_time":"2024-07-15T19:07:16+02:00",
+            "subject":"Volkswagen 1500 lim 113 chassi",
+            "body":"Säljer ett chassi/bottenplatta till en volkswagen 1500 lim 113 1967, blästrat och målat.\nFinns en beach buggy kaross att få med om man vill det. \nReg nmr ABC123",
+            "price":{
+               "value":10000,
+               "suffix":"kr"
+            },
+            ...
+         },
+      },
+   ],
+   "total_count":41,
+   "timestamp":"2024-07-16T08:08:43.810828006Z",
+   "total_page_count":1
+}
+```
+
+### custom_search(search_query, region, limit)
+Make a custom search through out all of blocked. A region can be passed in as parameter for filtering.
+
+Parameters:
+- `search_query` (`str`, required) - A string to search for.
+- `region` (`str`, optional) - Filter results on a region, default is all of Sweden.
+- `limit` (`int`, optional) - Limit number of results returned, max is 99.
+
+```py
+>>> from blocket_api import Region
+>>> api.custom_search("saab", Region.blekinge) # search for term "saab" in region of "Blekinge"
+{
+   "data":[
+      {
+         "ad_id":"1401038836",
+         "ad_status":"active",
+         "advertiser":{
+            "account_id":"684279",
+            "name":"Stefan Ingves",
+            "type":"private"
+         },
+         ...
+         "location":[
+            {
+               "id":"22",
+               "name":"Blekinge",
+               "query_key":"r"
+            },
+            {
+               "id":"256",
+               "name":"Ronneby",
+               "query_key":"m"
+            }
+         ],
+         ...
+      }
+    ]
+}
+```
+
+### motor_search(page, make, fuel, chassi, price, modelYear, milage, gearbox)
+To query listings related to a specific car, supply the following parameters:
+
+- `page` (`int`, required) - Results are split in pages, set page number here.
+- `make` (`List[MAKE_OPTIONS]`) - Filter a specific make, ex. `Audi`.
+- `fuel` (`Optional[List[FUEL_OPTIONS]]`) - Filter a specific fuel, ex. `Diesel`.
+- `chassi` (`Optional[List[CHASSI_OPTIONS]]`) - Filter a specific chassi, ex. `Cab`.
+- `price` (`Optional[Tuple[int, int]]`) - Set price range, ex. `(50000, 100000)`.
+- `modelYear` (`Optional[Tuple[int, int]]`) - Set model year range, ex. `(2000, 2020)`.
+- `milage` (`Optional[Tuple[int, int]]`) - Set milage range, ex. `(1000, 2000)`.
+- `gearbox` (`Optional[GEARBOX_OPTIONS]`) - Filter a specific gearbox, ex. `Automat`.
+```py
+>>> api.motor_search(
+    make=["Audi", "Ford"],
+    fuel=["Diesel"],
+    chassi=["Cab"],
+    price=(50000, 100000),
+    page=1,
+)
+...
+```
+
+### price_eval(registration_number)
+Query price evaluation for a specific vehicle by using cars registration number (ABC123). This returns company and private estimated prices, car information, and more. The api queries same endpoint as Blockets ["värdera bil"](https://www.blocket.se/tjanster/vardera-bil) service. 
+
+- `registration_number` (`str`, required) - Registration number of the vehicle.
+```py
+>>> api.price_eval("ABC123)
+{
+   "registration_number": "ABC123",
+   "private_valuation": 108155,
+   "company_valuation": 108155,
+   "car_info": {
+      "make": "Volkswagen",
+      "model": "Polo"
+      ...
+   }
+   ...
+}
+```
+
+## 🔐 Blocket API token
+
+There are two ways to acquire your token:
+
+- Log in to Blocket.se with your credentials using any web browser.
+- Go to [this](https://www.blocket.se/api/adout-api-route/refresh-token-and-validate-session) URL and copy the value of `bearerToken`.
+
+If there's a better way of doing this, feel free to help out in [#2](https://github.com/dunderrrrrr/blocket_api/issues/2).
+
+Your token can also be found in the request headers in the "Bevakningar"-section on Blocket.
+
+- **Login to [blocket.se](https**://blocket.se/)**: Sign in with your credentials.
+- **Click "Bevakningar"**: Go to the "Bevakningar" section.
+- **Inspect the page**: Right-click the page and select "Inspect".
+- **Open the Network tab**: Switch to the Network tab in the Developer Tools.
+- **Find request headers**: Locate a request where the domain is "api.blocket.se" and the file is "searches". *Pretty much every request to api.blocket.se contains this auth-header, so any request will do.*
+- **Inspect request headers**: Look at the request headers to find your token under "Authorization".
+
+![token](https://i.imgur.com/E5ofN0e.png)
+
+My token has never expired or changed during this project. However, if your're met with a `401 Unauthorized` at some point, you may want to refresh your token by repeating the steps above.
+
+## 📝 Notes
+
+- Source repo: https://github.com/dunderrrrrr/blocket_api
+- PyPI: https://pypi.org/project/blocket-api/

blocket_api-0.2.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+blocket_api/__init__.py,sha256=I06XkzHU4zGWZ2Zk9kDZlX0OZ39IT_SXv9iBA25qofA,84
+blocket_api/blocket.py,sha256=5zTv-IhsCKHAtVI0xdu-pDrEHE5E-RQLvoG9UN8rMw4,7264
+blocket_api-0.2.5.dist-info/licenses/LICENSE,sha256=SlUIRj6AhkUmDrxKCoiYP_DPHfk_vSvtW7qxPH9aGz8,460
+blocket_api-0.2.5.dist-info/METADATA,sha256=64AHvPgUx5fTF2K9E80MBDFaZ1DJPMYZ-GiehhLoY2U,8626
+blocket_api-0.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+blocket_api-0.2.5.dist-info/top_level.txt,sha256=jbWcqpXYz4vCiWeDO9fUUzpPAtwDztvupocPkoQ9OYw,12
+blocket_api-0.2.5.dist-info/RECORD,,

blocket_api-0.2.5.dist-info/WHEEL

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

blocket_api-0.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+Copyright (C) 2018 Satwik Kansal
+
+Everyone is permitted to copy and distribute verbatim or modified
+copies of this license document, and changing it is allowed as long
+as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+  TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+0. You just DO WHAT THE FUCK YOU WANT TO.

blocket_api-0.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+blocket_api