blocket-api 0.2.8__tar.gz → 0.3.0__tar.gz

{blocket_api-0.2.8 → blocket_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blocket_api
-Version: 0.2.8
+Version: 0.3.0
 Summary: A python API wrapper for blocket.se
 Author-email: dunderrrrrr <emil.bjorkroth@gmail.com>
 Requires-Python: >=3.10
@@ -11,14 +11,15 @@ 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.4
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: ruff>=0.13.1
 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.
+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 or as cleaned pydantic objects.
 
 > 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.
 
@@ -33,12 +34,14 @@ BlocketAPI allows users to query saved searches, known as "Bevakningar", on [blo
 
 ## 🧑‍💻️ Install
 
-BlocketAPI is available on PyPI.
+Install BlocketAPI via PyPI...
 
 ```sh
 pip install blocket-api
 ```
 
+or use [blocket-api.se](https://blocket-api.se) without installing anything!
+
 ## 💁‍♀️ Usage
 
 ```py
@@ -55,20 +58,22 @@ Some calls require a `bearerToken`. However, some calls are public and don't req
 [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.
-| [`api.store_search()`](#store_searchsearch_query-page)  | 👏 No | Search for a store.
-| [`api.get_store_listings()`](#get_store_listingsstore_id-page)  | 👏 No | Get listings from a specific store.
+| 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 | Yes | Query home listings.
+| [`api.store_search()`](#store_search)  | 👏 No | Yes | Search for a store.
+| [`api.get_store_listings()`](#get_store_listings)  | 👏 No | Yes | Get listings from a specific store.
+| [`api.get_ad_by_id()`](#get_ad_by_id)  | 👏 No | Yes | Get ad data from id.
+
 
 ## 🤓 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.
 
@@ -87,7 +92,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:
@@ -121,7 +126,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:
@@ -129,9 +134,10 @@ 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
+>>> from blocket_api.blocket import Region, Category
 >>> api.custom_search("saab", Region.blekinge) # search for term "saab" in region of "Blekinge"
 {
    "data":[
@@ -162,7 +168,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.
@@ -173,6 +179,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"],
@@ -184,7 +192,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.
@@ -203,7 +211,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. 
@@ -211,6 +219,7 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 - `order_by` (`OrderBy`, optional) - Sorting order, ex. `OrderBy.price`.
 - `ordering` (`HOME_SEARCH_ORDERING`, optional) - Sorting order, ex. `"descending"`.
 - `offset` (`int`, optional) - Offset for results, ex. `60`.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is False.
 
 ```py
 >>> from blocket_api.qasa import HomeType, OrderBy
@@ -223,11 +232,13 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 ...
 ```
 
-### store_search(search_query, page)
+### 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")
@@ -243,11 +254,13 @@ Search for a store in Blocket stores from [blocket.se/butiker](https://www.block
 }
 ```
 
-### get_store_listings(store_id, page)
+### 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.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
 
 ```py
 >>> api.get_store_listings(1234)
@@ -265,6 +278,30 @@ Get listings from a specific store.
 }
 ```
 
+### get_ad_by_id
+Get ad data from a specific ad id.
+
+- `ad_id` (`int`, required) - The ad id. Can be found by calling any other method or from ad url.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
+
+```py
+>>> api.get_ad_by_id(1234)
+{
+   "data": {
+      "ad_id": "1234",
+      "ad_status": "active",
+      "advertiser": {...},
+      "body": "A nice ad.",
+      "category": [
+            {"id": "4000", "name": "Personligt"},
+            {"id": "4080", "name": "Kläder & skor"},
+      ],
+      ...
+   }
+}
+```
+
 ## 🔐 Blocket API token
 
 There are two ways to acquire your token:
@@ -289,5 +326,6 @@ My token has never expired or changed during this project. However, if your're m
 
 ## 📝 Notes
 
+- REST API: https://blocket-api.se
 - Source repo: https://github.com/dunderrrrrr/blocket_api
 - PyPI: https://pypi.org/project/blocket-api/

{blocket_api-0.2.8 → blocket_api-0.3.0}/README.md

@@ -1,8 +1,8 @@
 # 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.
+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 or as cleaned pydantic objects.
 
 > 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.
 
@@ -17,12 +17,14 @@ BlocketAPI allows users to query saved searches, known as "Bevakningar", on [blo
 
 ## 🧑‍💻️ Install
 
-BlocketAPI is available on PyPI.
+Install BlocketAPI via PyPI...
 
 ```sh
 pip install blocket-api
 ```
 
+or use [blocket-api.se](https://blocket-api.se) without installing anything!
+
 ## 💁‍♀️ Usage
 
 ```py
@@ -39,20 +41,22 @@ Some calls require a `bearerToken`. However, some calls are public and don't req
 [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.
-| [`api.store_search()`](#store_searchsearch_query-page)  | 👏 No | Search for a store.
-| [`api.get_store_listings()`](#get_store_listingsstore_id-page)  | 👏 No | Get listings from a specific store.
+| 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 | Yes | Query home listings.
+| [`api.store_search()`](#store_search)  | 👏 No | Yes | Search for a store.
+| [`api.get_store_listings()`](#get_store_listings)  | 👏 No | Yes | Get listings from a specific store.
+| [`api.get_ad_by_id()`](#get_ad_by_id)  | 👏 No | Yes | Get ad data from id.
+
 
 ## 🤓 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.
 
@@ -71,7 +75,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:
@@ -105,7 +109,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:
@@ -113,9 +117,10 @@ 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
+>>> from blocket_api.blocket import Region, Category
 >>> api.custom_search("saab", Region.blekinge) # search for term "saab" in region of "Blekinge"
 {
    "data":[
@@ -146,7 +151,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.
@@ -157,6 +162,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"],
@@ -168,7 +175,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.
@@ -187,7 +194,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. 
@@ -195,6 +202,7 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 - `order_by` (`OrderBy`, optional) - Sorting order, ex. `OrderBy.price`.
 - `ordering` (`HOME_SEARCH_ORDERING`, optional) - Sorting order, ex. `"descending"`.
 - `offset` (`int`, optional) - Offset for results, ex. `60`.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is False.
 
 ```py
 >>> from blocket_api.qasa import HomeType, OrderBy
@@ -207,11 +215,13 @@ Query home listings from [bostad.blocket.se](https://bostad.blocket.se/).
 ...
 ```
 
-### store_search(search_query, page)
+### 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")
@@ -227,11 +237,13 @@ Search for a store in Blocket stores from [blocket.se/butiker](https://www.block
 }
 ```
 
-### get_store_listings(store_id, page)
+### 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.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
 
 ```py
 >>> api.get_store_listings(1234)
@@ -249,6 +261,30 @@ Get listings from a specific store.
 }
 ```
 
+### get_ad_by_id
+Get ad data from a specific ad id.
+
+- `ad_id` (`int`, required) - The ad id. Can be found by calling any other method or from ad url.
+- `as_objects` (`bool`, optional) - Return results as pydantic models, default is `False`.
+
+
+```py
+>>> api.get_ad_by_id(1234)
+{
+   "data": {
+      "ad_id": "1234",
+      "ad_status": "active",
+      "advertiser": {...},
+      "body": "A nice ad.",
+      "category": [
+            {"id": "4000", "name": "Personligt"},
+            {"id": "4080", "name": "Kläder & skor"},
+      ],
+      ...
+   }
+}
+```
+
 ## 🔐 Blocket API token
 
 There are two ways to acquire your token:
@@ -273,5 +309,6 @@ My token has never expired or changed during this project. However, if your're m
 
 ## 📝 Notes
 
+- REST API: https://blocket-api.se
 - Source repo: https://github.com/dunderrrrrr/blocket_api
 - PyPI: https://pypi.org/project/blocket-api/