blocket-api 0.2.7__tar.gz → 0.2.9__tar.gz

{blocket_api-0.2.7 → blocket_api-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blocket_api
-Version: 0.2.7
+Version: 0.2.9
 Summary: A python API wrapper for blocket.se
 Author-email: dunderrrrrr <emil.bjorkroth@gmail.com>
 Requires-Python: >=3.10
@@ -11,12 +11,13 @@ Requires-Dist: pre-commit>=3.7.1
 Requires-Dist: pytest>=8.2.2
 Requires-Dist: respx>=0.21.1
 Requires-Dist: mypy>=1.15.0
-Requires-Dist: ruff>=0.12.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: ruff>=0.13.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)
+[![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](https://img.shields.io/badge/Python-3.10-blue?style=for-the-badge) ![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.
 
@@ -27,9 +28,9 @@ BlocketAPI allows users to query saved searches, known as "Bevakningar", on [blo
 - List saved searches, called "Bevakningar".
 - Get listings from all or a specific saved search.
 - Search for anything on Blocket with filters for region and category.
-- Advanced search for vehicles with multiple filters.
-- Get vehicle information and price evaluation.
+- Get vehicle information, price evaluation and search for vehicles with multiple filters.
 - Search for homes with filters for city, home type and more.
+- Search for stores and get a specific store's listings.
 
 ## 🧑‍💻️ Install
 
@@ -50,23 +51,25 @@ pip install blocket-api
 ...
 ```
 
-Some calls require a bearerToken. However, some calls are public and don't require a token.
+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. | 
-| [`api.home_search()`](#home_searchcity-type-order_by-ordering-offset)  | 👏 No | Query home listings.
+| Function  | Token required | `as_objects` | Description  |
+|---|---|---|---|
+| [`api.saved_searches()`](#saved_searches) | 🔐 Yes | - | List your saved searches (bevakningar)  |
+| [`api.get_listings()`](#get_listings) | 🔐 Yes | - | List items related to a saved search |
+| [`api.custom_search()`](#custom_search)  | 👏 No | Yes | Search for everything on Blocket and filter by region |
+| [`api.motor_search()`](#motor_search)  | 👏 No | Yes | Advanced search for car-listings. |
+| [`api.price_eval()`](#price_eval)  | 👏 No | - | Vehicle purchase valuation and details. | 
+| [`api.home_search()`](#home_search)  | 👏 No | - | Query home listings.
+| [`api.store_search()`](#store_search)  | 👏 No | Yes | Search for a store.
+| [`api.get_store_listings()`](#get_store_listings)  | 👏 No | - | Get listings from a specific store.
 
 ## 🤓 Detailed usage
 
-### saved_searches()
+### 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.
 
@@ -85,7 +88,7 @@ Saved searches are your so called "Bevakningar" and can be found [here](https://
 ]
 ```
 
-### get_listings(search_id, limit)
+### get_listings
 Returns all listings related to a saved search.
 
 Parameters:
@@ -119,7 +122,7 @@ Parameters:
 }
 ```
 
-### custom_search(search_query, region, limit)
+### custom_search
 Make a custom search through out all of blocked. A region can be passed in as parameter for filtering.
 
 Parameters:
@@ -127,6 +130,7 @@ Parameters:
 - `region` (`enum`, optional) - Filter results on a region, default is all of Sweden.
 - `category` (`enum`, optional) - Filter for a specific category, ex. `Category.for_hemmet`.
 - `limit` (`int`, optional) - Limit number of results returned, max is 99.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
 
 ```py
 >>> from blocket_api import Region
@@ -160,7 +164,7 @@ Parameters:
 }
 ```
 
-### motor_search(page, make, fuel, chassi, price, modelYear, milage, gearbox)
+### motor_search
 To query listings related to a specific car, supply the following parameters:
 
 - `page` (`int`, required) - Results are split in pages, set page number here.
@@ -171,6 +175,8 @@ To query listings related to a specific car, supply the following parameters:
 - `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`.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
 ```py
 >>> api.motor_search(
     make=["Audi", "Ford"],
@@ -182,7 +188,7 @@ To query listings related to a specific car, supply the following parameters:
 ...
 ```
 
-### price_eval(registration_number)
+### price_eval
 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.
@@ -201,7 +207,7 @@ Query price evaluation for a specific vehicle by using cars registration number
 }
 ```
 
-### home_search(city, type, order_by, ordering, offset)
+### home_search
 Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 
 - `city` (`str`, required) - City name, ex. Stockholm. 
@@ -221,6 +227,50 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 ...
 ```
 
+### store_search
+Search for a store in Blocket stores from [blocket.se/butiker](https://www.blocket.se/butiker).
+
+- `search_query` (`str`, required) - The name of the store. 
+- `page` (`int`, optional) - The page number to return.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
+
+```py
+>>> api.store_search("Jannes Car and Kebab")
+{
+  "data": [
+    {
+      "store_id": "1234",
+      "store_name": "Jannes Car and Kebab",
+      ...
+    },
+    ...
+  ]
+}
+```
+
+### get_store_listings
+Get listings from a specific store.
+
+- `store_id` (`int`, required) - The store id. Can be obtained by calling `store_search()`.
+- `page` (`int`, optional) - The page number to return.
+
+```py
+>>> api.get_store_listings(1234)
+{
+  "data": [
+    {
+      "ad_id": "1234",
+      "price": 316000,
+      "body": "A very nice car.",
+      "images": [],
+      ...
+    },
+    ...
+  ]
+}
+```
+
 ## 🔐 Blocket API token
 
 There are two ways to acquire your token:

{blocket_api-0.2.7 → blocket_api-0.2.9}/README.md

@@ -1,6 +1,6 @@
 # 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)
+[![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](https://img.shields.io/badge/Python-3.10-blue?style=for-the-badge) ![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.
 
@@ -11,9 +11,9 @@ BlocketAPI allows users to query saved searches, known as "Bevakningar", on [blo
 - List saved searches, called "Bevakningar".
 - Get listings from all or a specific saved search.
 - Search for anything on Blocket with filters for region and category.
-- Advanced search for vehicles with multiple filters.
-- Get vehicle information and price evaluation.
+- Get vehicle information, price evaluation and search for vehicles with multiple filters.
 - Search for homes with filters for city, home type and more.
+- Search for stores and get a specific store's listings.
 
 ## 🧑‍💻️ Install
 
@@ -34,23 +34,25 @@ pip install blocket-api
 ...
 ```
 
-Some calls require a bearerToken. However, some calls are public and don't require a token.
+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. | 
-| [`api.home_search()`](#home_searchcity-type-order_by-ordering-offset)  | 👏 No | Query home listings.
+| Function  | Token required | `as_objects` | Description  |
+|---|---|---|---|
+| [`api.saved_searches()`](#saved_searches) | 🔐 Yes | - | List your saved searches (bevakningar)  |
+| [`api.get_listings()`](#get_listings) | 🔐 Yes | - | List items related to a saved search |
+| [`api.custom_search()`](#custom_search)  | 👏 No | Yes | Search for everything on Blocket and filter by region |
+| [`api.motor_search()`](#motor_search)  | 👏 No | Yes | Advanced search for car-listings. |
+| [`api.price_eval()`](#price_eval)  | 👏 No | - | Vehicle purchase valuation and details. | 
+| [`api.home_search()`](#home_search)  | 👏 No | - | Query home listings.
+| [`api.store_search()`](#store_search)  | 👏 No | Yes | Search for a store.
+| [`api.get_store_listings()`](#get_store_listings)  | 👏 No | - | Get listings from a specific store.
 
 ## 🤓 Detailed usage
 
-### saved_searches()
+### 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.
 
@@ -69,7 +71,7 @@ Saved searches are your so called "Bevakningar" and can be found [here](https://
 ]
 ```
 
-### get_listings(search_id, limit)
+### get_listings
 Returns all listings related to a saved search.
 
 Parameters:
@@ -103,7 +105,7 @@ Parameters:
 }
 ```
 
-### custom_search(search_query, region, limit)
+### custom_search
 Make a custom search through out all of blocked. A region can be passed in as parameter for filtering.
 
 Parameters:
@@ -111,6 +113,7 @@ Parameters:
 - `region` (`enum`, optional) - Filter results on a region, default is all of Sweden.
 - `category` (`enum`, optional) - Filter for a specific category, ex. `Category.for_hemmet`.
 - `limit` (`int`, optional) - Limit number of results returned, max is 99.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
 
 ```py
 >>> from blocket_api import Region
@@ -144,7 +147,7 @@ Parameters:
 }
 ```
 
-### motor_search(page, make, fuel, chassi, price, modelYear, milage, gearbox)
+### motor_search
 To query listings related to a specific car, supply the following parameters:
 
 - `page` (`int`, required) - Results are split in pages, set page number here.
@@ -155,6 +158,8 @@ To query listings related to a specific car, supply the following parameters:
 - `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`.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
 ```py
 >>> api.motor_search(
     make=["Audi", "Ford"],
@@ -166,7 +171,7 @@ To query listings related to a specific car, supply the following parameters:
 ...
 ```
 
-### price_eval(registration_number)
+### price_eval
 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.
@@ -185,7 +190,7 @@ Query price evaluation for a specific vehicle by using cars registration number
 }
 ```
 
-### home_search(city, type, order_by, ordering, offset)
+### home_search
 Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 
 - `city` (`str`, required) - City name, ex. Stockholm. 
@@ -205,6 +210,50 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 ...
 ```
 
+### store_search
+Search for a store in Blocket stores from [blocket.se/butiker](https://www.blocket.se/butiker).
+
+- `search_query` (`str`, required) - The name of the store. 
+- `page` (`int`, optional) - The page number to return.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
+
+```py
+>>> api.store_search("Jannes Car and Kebab")
+{
+  "data": [
+    {
+      "store_id": "1234",
+      "store_name": "Jannes Car and Kebab",
+      ...
+    },
+    ...
+  ]
+}
+```
+
+### get_store_listings
+Get listings from a specific store.
+
+- `store_id` (`int`, required) - The store id. Can be obtained by calling `store_search()`.
+- `page` (`int`, optional) - The page number to return.
+
+```py
+>>> api.get_store_listings(1234)
+{
+  "data": [
+    {
+      "ad_id": "1234",
+      "price": 316000,
+      "body": "A very nice car.",
+      "images": [],
+      ...
+    },
+    ...
+  ]
+}
+```
+
 ## 🔐 Blocket API token
 
 There are two ways to acquire your token:

{blocket_api-0.2.7 → blocket_api-0.2.9}/blocket_api/blocket.py

@@ -1,14 +1,19 @@
 from __future__ import annotations
 
-from collections.abc import Callable
-from functools import wraps
 import urllib
+from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum
-from typing import TYPE_CHECKING, Any, List, Literal, Optional, Tuple
+from functools import wraps
+from typing import TYPE_CHECKING, Any, List, Literal, Optional, Tuple, Union, overload
 
 import httpx
 
+from blocket_api.models import (
+    CustomSearchResults,
+    MotorSearchResults,
+    StoreSearchResults,
+)
 from blocket_api.qasa import HOME_SEARCH_ORDERING, HomeType, OrderBy, Qasa
 
 if TYPE_CHECKING:
@@ -232,6 +237,39 @@ class BlocketAPI:
             token=self.token,
         ).json()
 
+    @overload
+    def custom_search(
+        self,
+        search_query: str,
+        region: Region = Region.hela_sverige,
+        category: Category | None = None,
+        limit: int = 99,
+        *,
+        as_objects: Literal[True],
+    ) -> CustomSearchResults: ...
+
+    @overload
+    def custom_search(
+        self,
+        search_query: str,
+        region: Region = Region.hela_sverige,
+        category: Category | None = None,
+        limit: int = 99,
+        *,
+        as_objects: Literal[False] = False,
+    ) -> dict: ...
+
+    @overload
+    def custom_search(
+        self,
+        search_query: str,
+        region: Region = Region.hela_sverige,
+        category: Category | None = None,
+        limit: int = 99,
+        *,
+        as_objects: bool = False,
+    ) -> Union[dict, CustomSearchResults]: ...
+
     @public_token
     def custom_search(
         self,
@@ -239,10 +277,11 @@ class BlocketAPI:
         region: Region = Region.hela_sverige,
         category: Category | None = None,
         limit: int = 99,
-    ) -> dict:
+        *,
+        as_objects: bool = False,
+    ) -> dict | CustomSearchResults:
         """
-        Do a custom search through out all of Blocket.
-        Supply a region for filtering. Default is all of Sweden.
+        Do a custom search throughout all of Blocket.
         """
         assert self.token
 
@@ -254,7 +293,53 @@ class BlocketAPI:
         if category:
             url += f"&cg={category.value}"
 
-        return _make_request(url=url, token=self.token).json()
+        response = _make_request(url=url, token=self.token).json()
+        return CustomSearchResults.model_validate(response) if as_objects else response
+
+    @overload
+    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,
+        *,
+        as_objects: Literal[True],
+    ) -> MotorSearchResults: ...
+
+    @overload
+    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,
+        *,
+        as_objects: Literal[False] = False,
+    ) -> dict: ...
+
+    @overload
+    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,
+        *,
+        as_objects: bool = False,
+    ) -> Union[dict, MotorSearchResults]: ...
 
     @public_token
     def motor_search(
@@ -267,7 +352,9 @@ class BlocketAPI:
         modelYear: Optional[Tuple[int, int]] = None,
         milage: Optional[Tuple[int, int]] = None,
         gearbox: Optional[GEARBOX_OPTIONS] = None,
-    ) -> dict:
+        *,
+        as_objects: bool = False,
+    ) -> dict | MotorSearchResults:
         """
         Search specifically in the car section of Blocket
         with set optional parameters for filtering.
@@ -278,7 +365,8 @@ class BlocketAPI:
         set_params = {
             key: value
             for key, value in locals().items()
-            if key not in ["self", "page", "range_params"] and value is not None
+            if key not in ["self", "page", "range_params", "as_objects"]
+            and value is not None
         }
 
         filters = []
@@ -298,7 +386,8 @@ class BlocketAPI:
         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()
+        response = _make_request(url=f"{url}", token=self.token).json()
+        return MotorSearchResults.model_validate(response) if as_objects else response
 
     @public_token
     def price_eval(
@@ -334,3 +423,68 @@ class BlocketAPI:
             ordering=ordering,
             offset=offset,
         ).search()
+
+    @overload
+    def search_store(
+        self,
+        search_query: str,
+        page: int = 0,
+        *,
+        as_objects: Literal[True],
+    ) -> StoreSearchResults: ...
+
+    @overload
+    def search_store(
+        self,
+        search_query: str,
+        page: int = 0,
+        *,
+        as_objects: Literal[False] = False,
+    ) -> dict: ...
+
+    @overload
+    def search_store(
+        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,
+        *,
+        as_objects: bool = False,
+    ) -> Union[dict, StoreSearchResults]: ...
+
+    @public_token
+    def search_store(
+        self,
+        search_query: str,
+        page: int = 0,
+        *,
+        as_objects: bool = False,
+    ) -> dict | StoreSearchResults:
+        """
+        Searching through Blocket stores from https://www.blocket.se/butiker.
+        The store_id is used for get_store_listings().
+        """
+        url = f"{BASE_URL}/search_bff/v1/stores?q={search_query}&page={page}"
+        response = _make_request(url=f"{url}", token=self.token).json()
+        return StoreSearchResults.model_validate(response) if as_objects else response
+
+    @public_token
+    def get_store_listings(
+        self,
+        store_id: int,
+        page: int = 0,
+    ) -> dict:
+        """
+        Return all listings from a specific store from https://www.blocket.se/butik/<store>.
+        The store_id can be found by searching for the store with search_store().
+        """
+        url = (
+            f"{BASE_URL}/search_bff/v2/content?lim=60&page={page}&sort=rel&store_id={store_id}"
+            "&status=active&gl=3&include=extend_with_shipping"
+        )
+        return _make_request(url=f"{url}", token=self.token).json()

blocket_api-0.2.9/blocket_api/models.py

@@ -0,0 +1,151 @@
+import datetime
+
+from pydantic import BaseModel
+
+### CustomSearch ###
+
+
+class CustomSearchPrice(BaseModel):
+    suffix: str
+    value: int
+
+
+class CustomSearchLocation(BaseModel):
+    image_url: str
+    label: str
+    query_key: str | None = None
+
+
+class CustomSearchImage(BaseModel):
+    height: int
+    type: str
+    url: str
+    width: int
+
+
+class CustomSearchCategory(BaseModel):
+    id: str
+    name: str
+
+
+class CustomSearchResult(BaseModel):
+    ad_id: str
+    ad_status: str
+    body: str
+    category: list[CustomSearchCategory]
+    images: list[CustomSearchImage] = []
+    list_id: str
+    list_time: datetime.datetime
+    map: CustomSearchLocation | None = None
+    map_url: str | None = None
+    price: CustomSearchPrice
+    share_url: str
+    state_id: str
+    subject: str
+    type: str
+    zipcode: str | None = None
+
+
+class CustomSearchResults(BaseModel):
+    data: list[CustomSearchResult]
+    total_count: int
+
+
+### MotorSearch ###
+
+
+class MotorSearchCarEquipment(BaseModel):
+    label: str
+
+
+class MotorSearchCarLocation(BaseModel):
+    region: str
+    municipality: str
+    area: str
+
+
+class MotorSearchCarImage(BaseModel):
+    height: int
+    width: int
+    image: str
+
+
+class MotorSearchCar(BaseModel):
+    images: list[MotorSearchCarImage]
+    location: MotorSearchCarLocation
+    fuel: str
+    gearbox: str
+    regDate: int
+    mileage: int
+    equipment: list[MotorSearchCarEquipment] | None = None
+
+
+class MotorSearchPrice(BaseModel):
+    amount: str
+    billingPeriod: str
+    oldPrice: str | None = None
+
+
+class MotorSearchSeller(BaseModel):
+    type: str
+    name: str
+    id: str
+
+
+class MotorSearchResult(BaseModel):
+    dealId: str
+    link: str
+    listTime: datetime.datetime
+    originalListTime: datetime.datetime
+    seller: MotorSearchSeller
+    heading: str
+    price: MotorSearchPrice
+    thumbnail: str
+    car: MotorSearchCar
+    description: str
+
+
+class MotorSearchResults(BaseModel):
+    cars: list[MotorSearchResult]
+    hits: int
+    pages: int
+
+
+### StoreSearch ###
+
+
+class StoreSearchLocation(BaseModel):
+    longitude: float
+    latitude: float
+
+
+class StoreSearchImage(BaseModel):
+    height: int
+    width: int
+    url: str
+
+
+class StoreSearchLogotype(BaseModel):
+    height: int
+    width: int
+    url: str
+
+
+class StoreSearchResult(BaseModel):
+    address: str | None = None
+    id: str
+    logotype: StoreSearchLogotype
+    image: StoreSearchImage | None = None
+    description: str
+    external_store_url: str | None = None
+    location: StoreSearchLocation | None = None
+    name: str
+    title: str
+    ad_count: int
+    category: str
+
+
+class StoreSearchResults(BaseModel):
+    data: list[StoreSearchResult]
+    total_count: int
+    total_page_count: int

{blocket_api-0.2.7 → blocket_api-0.2.9}/blocket_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blocket_api
-Version: 0.2.7
+Version: 0.2.9
 Summary: A python API wrapper for blocket.se
 Author-email: dunderrrrrr <emil.bjorkroth@gmail.com>
 Requires-Python: >=3.10
@@ -11,12 +11,13 @@ Requires-Dist: pre-commit>=3.7.1
 Requires-Dist: pytest>=8.2.2
 Requires-Dist: respx>=0.21.1
 Requires-Dist: mypy>=1.15.0
-Requires-Dist: ruff>=0.12.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: ruff>=0.13.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)
+[![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](https://img.shields.io/badge/Python-3.10-blue?style=for-the-badge) ![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.
 
@@ -27,9 +28,9 @@ BlocketAPI allows users to query saved searches, known as "Bevakningar", on [blo
 - List saved searches, called "Bevakningar".
 - Get listings from all or a specific saved search.
 - Search for anything on Blocket with filters for region and category.
-- Advanced search for vehicles with multiple filters.
-- Get vehicle information and price evaluation.
+- Get vehicle information, price evaluation and search for vehicles with multiple filters.
 - Search for homes with filters for city, home type and more.
+- Search for stores and get a specific store's listings.
 
 ## 🧑‍💻️ Install
 
@@ -50,23 +51,25 @@ pip install blocket-api
 ...
 ```
 
-Some calls require a bearerToken. However, some calls are public and don't require a token.
+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. | 
-| [`api.home_search()`](#home_searchcity-type-order_by-ordering-offset)  | 👏 No | Query home listings.
+| Function  | Token required | `as_objects` | Description  |
+|---|---|---|---|
+| [`api.saved_searches()`](#saved_searches) | 🔐 Yes | - | List your saved searches (bevakningar)  |
+| [`api.get_listings()`](#get_listings) | 🔐 Yes | - | List items related to a saved search |
+| [`api.custom_search()`](#custom_search)  | 👏 No | Yes | Search for everything on Blocket and filter by region |
+| [`api.motor_search()`](#motor_search)  | 👏 No | Yes | Advanced search for car-listings. |
+| [`api.price_eval()`](#price_eval)  | 👏 No | - | Vehicle purchase valuation and details. | 
+| [`api.home_search()`](#home_search)  | 👏 No | - | Query home listings.
+| [`api.store_search()`](#store_search)  | 👏 No | Yes | Search for a store.
+| [`api.get_store_listings()`](#get_store_listings)  | 👏 No | - | Get listings from a specific store.
 
 ## 🤓 Detailed usage
 
-### saved_searches()
+### 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.
 
@@ -85,7 +88,7 @@ Saved searches are your so called "Bevakningar" and can be found [here](https://
 ]
 ```
 
-### get_listings(search_id, limit)
+### get_listings
 Returns all listings related to a saved search.
 
 Parameters:
@@ -119,7 +122,7 @@ Parameters:
 }
 ```
 
-### custom_search(search_query, region, limit)
+### custom_search
 Make a custom search through out all of blocked. A region can be passed in as parameter for filtering.
 
 Parameters:
@@ -127,6 +130,7 @@ Parameters:
 - `region` (`enum`, optional) - Filter results on a region, default is all of Sweden.
 - `category` (`enum`, optional) - Filter for a specific category, ex. `Category.for_hemmet`.
 - `limit` (`int`, optional) - Limit number of results returned, max is 99.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
 
 ```py
 >>> from blocket_api import Region
@@ -160,7 +164,7 @@ Parameters:
 }
 ```
 
-### motor_search(page, make, fuel, chassi, price, modelYear, milage, gearbox)
+### motor_search
 To query listings related to a specific car, supply the following parameters:
 
 - `page` (`int`, required) - Results are split in pages, set page number here.
@@ -171,6 +175,8 @@ To query listings related to a specific car, supply the following parameters:
 - `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`.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
 ```py
 >>> api.motor_search(
     make=["Audi", "Ford"],
@@ -182,7 +188,7 @@ To query listings related to a specific car, supply the following parameters:
 ...
 ```
 
-### price_eval(registration_number)
+### price_eval
 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.
@@ -201,7 +207,7 @@ Query price evaluation for a specific vehicle by using cars registration number
 }
 ```
 
-### home_search(city, type, order_by, ordering, offset)
+### home_search
 Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 
 - `city` (`str`, required) - City name, ex. Stockholm. 
@@ -221,6 +227,50 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 ...
 ```
 
+### store_search
+Search for a store in Blocket stores from [blocket.se/butiker](https://www.blocket.se/butiker).
+
+- `search_query` (`str`, required) - The name of the store. 
+- `page` (`int`, optional) - The page number to return.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
+
+```py
+>>> api.store_search("Jannes Car and Kebab")
+{
+  "data": [
+    {
+      "store_id": "1234",
+      "store_name": "Jannes Car and Kebab",
+      ...
+    },
+    ...
+  ]
+}
+```
+
+### get_store_listings
+Get listings from a specific store.
+
+- `store_id` (`int`, required) - The store id. Can be obtained by calling `store_search()`.
+- `page` (`int`, optional) - The page number to return.
+
+```py
+>>> api.get_store_listings(1234)
+{
+  "data": [
+    {
+      "ad_id": "1234",
+      "price": 316000,
+      "body": "A very nice car.",
+      "images": [],
+      ...
+    },
+    ...
+  ]
+}
+```
+
 ## 🔐 Blocket API token
 
 There are two ways to acquire your token:

{blocket_api-0.2.7 → blocket_api-0.2.9}/blocket_api.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 blocket_api/__init__.py
 blocket_api/blocket.py
+blocket_api/models.py
 blocket_api/qasa.py
 blocket_api.egg-info/PKG-INFO
 blocket_api.egg-info/SOURCES.txt

{blocket_api-0.2.7 → blocket_api-0.2.9}/blocket_api.egg-info/requires.txt

@@ -3,4 +3,5 @@ pre-commit>=3.7.1
 pytest>=8.2.2
 respx>=0.21.1
 mypy>=1.15.0
-ruff>=0.12.3
+pydantic>=2.11.7
+ruff>=0.13.0

{blocket_api-0.2.7 → blocket_api-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "blocket_api"
-version = "0.2.7"
+version = "0.2.9"
 description = "A python API wrapper for blocket.se"
 authors = [{name = "dunderrrrrr", email = "emil.bjorkroth@gmail.com"}]
 readme = "README.md"
@@ -11,7 +11,8 @@ dependencies = [
     "pytest>=8.2.2",
     "respx>=0.21.1",
     "mypy>=1.15.0",
-    "ruff>=0.12.3",
+    "pydantic>=2.11.7",
+    "ruff>=0.13.0",
 ]