# chrono24
<p align="center">
<img src="https://static.chrono24.com/images/default/logo-positive-reduced.svg" width="50%" />
</p>
<br>
[Chrono24](https://www.chrono24.com/) API wrapper
[](https://pypi.python.org/pypi/chrono24)
[](https://www.python.org/downloads/)
[](https://github.com/irahorecka/chrono24/actions)
[](https://raw.githubusercontent.com/irahorecka/chrono24/main/LICENSE)
## Installation
```bash
pip install chrono24
```
## Quick Start
Perform a standard search for Rolex DateJust watches:
```python
import chrono24
for listing in chrono24.query("Rolex DateJust").search():
print(listing)
```
Example output:
```python
>>> {'id': '32322343',
'url': 'https://chrono24.com/rolex/datejust-41mm-blue-diamond-dial-2022---126334--id32322343.htm',
'manufacturer': 'Rolex',
'certification_status': 'Basic',
'title': 'Rolex Datejust 41',
'description': '41mm Blue Diamond Dial 2022 - 126334',
'price': '$16,553',
'shipping_price': '$396',
'location': 'Düsseldorf, Germany.',
'merchant_name': 'Dealer',
'badge': 'Professional',
'image_urls': ['https://cdn2.chrono24.com/images/uhren/32322343-gp8hzm4ppkzsbhzc7s7bl2vh-ExtraLarge.jpg',
'https://cdn2.chrono24.com/images/uhren/32322343-u7wq78hxqoalnfrlag1gkt8d-ExtraLarge.jpg',
'https://cdn2.chrono24.com/images/uhren/32322343-93ykurb99s654x7aysnh8ljs-ExtraLarge.jpg',
'https://cdn2.chrono24.com/images/uhren/32322343-gxd85po61ynmoictprm1gvfq-ExtraLarge.jpg',
'https://cdn2.chrono24.com/images/uhren/32322343-den0sntpacmucq5zdktzul70-ExtraLarge.jpg']}
# ...
```
## Usage
Search for standard or detailed watch listings for any query, limiting results to, for example, 25 listings. All results will be retrieved if no limit is provided, and they'll be sorted by new listings first.
```python
import chrono24
rolex_dj = chrono24.query("Rolex DateJust")
# Search for standard listings
for listing in rolex_dj.search(limit=25):
print(listing)
# Search for detailed listings
for detailed_listing in rolex_dj.detailed_search(limit=25):
print(detailed_listing)
```
**Note:** When using these functions, be cautious not to overwhelm Chrono24 with excessive requests. The `standard_search` method consumes 1 request per 120 posts retrieved, while `detailed_search` utilizes 1 request per individual post. Avoid flooding requests to maintain a balanced usage of the Chrono24 service and prevent any potential access limitations.
## API Outputs
Example output from `.search`:
```python
{
'id': '32322343',
'url': 'https://chrono24.com/rolex/datejust-41mm-blue-diamond-dial-2022---126334--id32322343.htm',
'manufacturer': 'Rolex',
'certification_status': 'Basic',
'title': 'Rolex Datejust 41',
'description': '41mm Blue Diamond Dial 2022 - 126334',
'price': '$16,553',
'shipping_price': '$396',
'location': 'Düsseldorf, Germany.',
'merchant_name': 'Dealer',
'badge': 'Professional',
'image_urls': [...], # List of image URLs
}
```
Example output from `.detailed_search`, which extends results from `.search`:
```python
{
'id': '32322343',
'url': 'https://chrono24.com/rolex/datejust-41mm-blue-diamond-dial-2022---126334--id32322343.htm',
'manufacturer': 'Rolex',
'certification_status': 'Basic',
'title': 'Rolex Datejust 41',
'description': '41mm Blue Diamond Dial 2022 - 126334',
'price': '$16,553',
'shipping_price': '$396',
'location': 'Düsseldorf, Germany.',
'merchant_name': 'Dealer',
'badge': 'Professional',
'image_urls': [...], # List of image URLs
'listing_code': 'J8S2V6',
'brand': 'Rolex',
'model': 'Datejust 41',
'reference_number': '126334',
'dealer_product_code': '8675310109006',
'case_material': 'Steel',
'bracelet_material': 'Steel',
'year_of_production': '2022',
'condition': 'Very good (Worn with little to no signs of wear)',
'scope_of_delivery': 'Original box, original papers',
'availability': 'Item needs to be procured',
'case_diameter': '41 mm',
'bracelet_color': 'Steel',
'availabe_payments': [...], # List of available payment methods
'anticipated_delivery': 'Latest anticipated delivery on 1/22',
'merchant_rating': '4.4',
'merchant_reviews': '196',
'merchant_badges': [...], # List of merchant badges
}
```
**Note:** Output keys in `.search` will always be constant, but `.detailed_search` can vary based on information provided by the listing page, expanding on the details retrieved by `.search`.
## Filters
You can refine your watch searches using various filter criteria, as well as define year ranges using `min_year` and `max_year`. Pre-defined filters include options such as case material, bracelet type, movement type, and more. These filters and year constraints can be applied when creating a query object.
### How to Use Filters
To use filters, specify them when creating a query using the `filters` argument. You can pass a single string, a list/tuple of filter keys, or include year constraints using the `min_year` and `max_year` parameters:
```python
import chrono24
# Initialize a query with a single filter
steel_rolex_dj = chrono24.query("Rolex DateJust", filters="steel")
# Initialize a query with multiple filters
steel_auto_rolex_dj = chrono24.query("Rolex DateJust", filters=["steel", "automatic"])
# Initialize a query with year constraints
new_rolex_dj = chrono24.query("Rolex DateJust", min_year=2010, max_year=2020)
# Combine filters and year constraints
new_steel_auto_rolex_dj = chrono24.query("Rolex DateJust", filters=["steel", "automatic"], min_year=2010, max_year=2020)
```
### Available Filter Categories
The available filter categories are:
- **Case Filters**: Material, diameter, and more.
- **Clasp Filters**: Clasp type, material, etc.
- **Condition and Delivery Contents**: Item condition, delivery options, included papers/box.
- **Dial Filters**: Dial color, numerals, etc.
- **Location Filters**: Country-specific filters.
- **Movement and Functions**: Manual, automatic, complications.
- **Other Filters**: Miscellaneous filters such as water resistance, glass type.
- **Seller and Listing Type**: Dealer, private seller, new/used.
- **Sort By**: Sorting options like 'Newest listings first', 'Price ascending', etc.
- **Strap and Bracelet**: Bracelet material, color, strap type.
- **Watch Type**: Sports, dress, luxury, and more.
### Finding Filters
You can view all available filters using the `chrono24.filters.show()` method:
```python
import chrono24
# Display all available filter categories and keys
chrono24.filters.show()
```
This will print a categorized list of all possible filters, helping you decide which ones to apply to your query. If you're not sure which filter to use, you can also search for filter keys using the `chrono24.filters.search(query)` method:
```python
import chrono24
# Search for filters related to 'steel'
chrono24.filters.search("steel")
```
Example output:
```text
Search results for query 'steel':
Direct matches:
- gold_steel_band
- steel_band
- gold_steel_color
- steel_band_color
- gold_steel_clasp
- steel_clasp
- gold_steel
- steel
- gold_steel_bezel
- steel_bezel
Fuzzy matches:
- steel
- steel_band
- gold_steel
- steel_clasp
- steel_bezel
```
This output shows the best filter keys matching the query 'steel', divided into **Direct matches** (exact or close matches) and **Fuzzy matches** (similar but not exact matches). Use these filter keys to refine your watch search in `chrono24`.
## Attributes
The `chrono24` instance offers public attributes:
- `count`: Total number of listings found.
- `url`: URL of listings page.
```python
import chrono24
rolex_dj = chrono24.query("Rolex DateJust")
rolex_dj.count
# >>> 35582
rolex_dj.url
# >>> 'https://www.chrono24.com/rolex/datejust--mod45.htm?dosearch=true&query=Rolex+DateJust'
```
## Exceptions
The `chrono24` package handles specific exceptions that might occur during its use:
- `NoListingsFoundException`: Raised when no listings are found.
- `RequestException`: Raised when a request error occurs or repeated requests fail.
```python
import chrono24
from chrono24.exceptions import NoListingsFoundException, RequestException
try:
invalid_query = chrono24.query("Invalid Query")
except NoListingsFoundException:
# In cases where no listings match the provided query
print("No listings were found.")
except RequestException:
# In cases where a request error occurs or repeated requests fail
print("Request error or repeated requests failed.")
```
## Contribute
- [Issues Tracker](https://github.com/irahorecka/chrono24/issues)
- [Source Code](https://github.com/irahorecka/chrono24/tree/main/chrono24)
## Support
If you are having issues or would like to propose a new feature, please use the [issues tracker](https://github.com/irahorecka/chrono24/issues).
## License
This project is licensed under the MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/irahorecka/chrono24",
"name": "chrono24",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Ira Horecka",
"author_email": "ira89@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/6b/64/4b1f79d490d212cda7240654fd6c8a7048ba3f1bf751237aee059afe1ca8/chrono24-0.3.2.tar.gz",
"platform": null,
"description": "# chrono24\n\n<p align=\"center\">\n <img src=\"https://static.chrono24.com/images/default/logo-positive-reduced.svg\" width=\"50%\" />\n</p>\n\n<br>\n\n[Chrono24](https://www.chrono24.com/) API wrapper\n\n[](https://pypi.python.org/pypi/chrono24)\n[](https://www.python.org/downloads/)\n[](https://github.com/irahorecka/chrono24/actions)\n[](https://raw.githubusercontent.com/irahorecka/chrono24/main/LICENSE)\n\n## Installation\n\n```bash\npip install chrono24\n```\n\n## Quick Start\n\nPerform a standard search for Rolex DateJust watches:\n\n```python\nimport chrono24\n\nfor listing in chrono24.query(\"Rolex DateJust\").search():\n print(listing)\n```\n\nExample output:\n\n```python\n>>> {'id': '32322343',\n 'url': 'https://chrono24.com/rolex/datejust-41mm-blue-diamond-dial-2022---126334--id32322343.htm',\n 'manufacturer': 'Rolex',\n 'certification_status': 'Basic',\n 'title': 'Rolex Datejust 41',\n 'description': '41mm Blue Diamond Dial 2022 - 126334',\n 'price': '$16,553',\n 'shipping_price': '$396',\n 'location': 'D\u00fcsseldorf, Germany.',\n 'merchant_name': 'Dealer',\n 'badge': 'Professional',\n 'image_urls': ['https://cdn2.chrono24.com/images/uhren/32322343-gp8hzm4ppkzsbhzc7s7bl2vh-ExtraLarge.jpg',\n 'https://cdn2.chrono24.com/images/uhren/32322343-u7wq78hxqoalnfrlag1gkt8d-ExtraLarge.jpg',\n 'https://cdn2.chrono24.com/images/uhren/32322343-93ykurb99s654x7aysnh8ljs-ExtraLarge.jpg',\n 'https://cdn2.chrono24.com/images/uhren/32322343-gxd85po61ynmoictprm1gvfq-ExtraLarge.jpg',\n 'https://cdn2.chrono24.com/images/uhren/32322343-den0sntpacmucq5zdktzul70-ExtraLarge.jpg']}\n # ...\n```\n\n## Usage\n\nSearch for standard or detailed watch listings for any query, limiting results to, for example, 25 listings. All results will be retrieved if no limit is provided, and they'll be sorted by new listings first.\n\n```python\nimport chrono24\n\nrolex_dj = chrono24.query(\"Rolex DateJust\")\n\n# Search for standard listings\nfor listing in rolex_dj.search(limit=25):\n print(listing)\n\n# Search for detailed listings\nfor detailed_listing in rolex_dj.detailed_search(limit=25):\n print(detailed_listing)\n```\n\n**Note:** When using these functions, be cautious not to overwhelm Chrono24 with excessive requests. The `standard_search` method consumes 1 request per 120 posts retrieved, while `detailed_search` utilizes 1 request per individual post. Avoid flooding requests to maintain a balanced usage of the Chrono24 service and prevent any potential access limitations.\n\n## API Outputs\n\nExample output from `.search`:\n\n```python\n{\n 'id': '32322343',\n 'url': 'https://chrono24.com/rolex/datejust-41mm-blue-diamond-dial-2022---126334--id32322343.htm',\n 'manufacturer': 'Rolex',\n 'certification_status': 'Basic',\n 'title': 'Rolex Datejust 41',\n 'description': '41mm Blue Diamond Dial 2022 - 126334',\n 'price': '$16,553',\n 'shipping_price': '$396',\n 'location': 'D\u00fcsseldorf, Germany.',\n 'merchant_name': 'Dealer',\n 'badge': 'Professional',\n 'image_urls': [...], # List of image URLs\n}\n```\n\nExample output from `.detailed_search`, which extends results from `.search`:\n\n```python\n{\n 'id': '32322343',\n 'url': 'https://chrono24.com/rolex/datejust-41mm-blue-diamond-dial-2022---126334--id32322343.htm',\n 'manufacturer': 'Rolex',\n 'certification_status': 'Basic',\n 'title': 'Rolex Datejust 41',\n 'description': '41mm Blue Diamond Dial 2022 - 126334',\n 'price': '$16,553',\n 'shipping_price': '$396',\n 'location': 'D\u00fcsseldorf, Germany.',\n 'merchant_name': 'Dealer',\n 'badge': 'Professional',\n 'image_urls': [...], # List of image URLs\n 'listing_code': 'J8S2V6',\n 'brand': 'Rolex',\n 'model': 'Datejust 41',\n 'reference_number': '126334',\n 'dealer_product_code': '8675310109006',\n 'case_material': 'Steel',\n 'bracelet_material': 'Steel',\n 'year_of_production': '2022',\n 'condition': 'Very good (Worn with little to no signs of wear)',\n 'scope_of_delivery': 'Original box, original papers',\n 'availability': 'Item needs to be procured',\n 'case_diameter': '41 mm',\n 'bracelet_color': 'Steel',\n 'availabe_payments': [...], # List of available payment methods\n 'anticipated_delivery': 'Latest anticipated delivery on 1/22',\n 'merchant_rating': '4.4',\n 'merchant_reviews': '196',\n 'merchant_badges': [...], # List of merchant badges\n}\n```\n\n**Note:** Output keys in `.search` will always be constant, but `.detailed_search` can vary based on information provided by the listing page, expanding on the details retrieved by `.search`.\n\n## Filters\n\nYou can refine your watch searches using various filter criteria, as well as define year ranges using `min_year` and `max_year`. Pre-defined filters include options such as case material, bracelet type, movement type, and more. These filters and year constraints can be applied when creating a query object.\n\n### How to Use Filters\n\nTo use filters, specify them when creating a query using the `filters` argument. You can pass a single string, a list/tuple of filter keys, or include year constraints using the `min_year` and `max_year` parameters:\n\n```python\nimport chrono24\n\n# Initialize a query with a single filter\nsteel_rolex_dj = chrono24.query(\"Rolex DateJust\", filters=\"steel\")\n# Initialize a query with multiple filters\nsteel_auto_rolex_dj = chrono24.query(\"Rolex DateJust\", filters=[\"steel\", \"automatic\"])\n# Initialize a query with year constraints\nnew_rolex_dj = chrono24.query(\"Rolex DateJust\", min_year=2010, max_year=2020)\n# Combine filters and year constraints\nnew_steel_auto_rolex_dj = chrono24.query(\"Rolex DateJust\", filters=[\"steel\", \"automatic\"], min_year=2010, max_year=2020)\n```\n\n### Available Filter Categories\n\nThe available filter categories are:\n\n- **Case Filters**: Material, diameter, and more.\n- **Clasp Filters**: Clasp type, material, etc.\n- **Condition and Delivery Contents**: Item condition, delivery options, included papers/box.\n- **Dial Filters**: Dial color, numerals, etc.\n- **Location Filters**: Country-specific filters.\n- **Movement and Functions**: Manual, automatic, complications.\n- **Other Filters**: Miscellaneous filters such as water resistance, glass type.\n- **Seller and Listing Type**: Dealer, private seller, new/used.\n- **Sort By**: Sorting options like 'Newest listings first', 'Price ascending', etc.\n- **Strap and Bracelet**: Bracelet material, color, strap type.\n- **Watch Type**: Sports, dress, luxury, and more.\n\n### Finding Filters\n\nYou can view all available filters using the `chrono24.filters.show()` method:\n\n```python\nimport chrono24\n\n# Display all available filter categories and keys\nchrono24.filters.show()\n```\n\nThis will print a categorized list of all possible filters, helping you decide which ones to apply to your query. If you're not sure which filter to use, you can also search for filter keys using the `chrono24.filters.search(query)` method:\n\n```python\nimport chrono24\n\n# Search for filters related to 'steel'\nchrono24.filters.search(\"steel\")\n```\n\nExample output:\n\n```text\nSearch results for query 'steel':\n\nDirect matches:\n - gold_steel_band\n - steel_band\n - gold_steel_color\n - steel_band_color\n - gold_steel_clasp\n - steel_clasp\n - gold_steel\n - steel\n - gold_steel_bezel\n - steel_bezel\n\nFuzzy matches:\n - steel\n - steel_band\n - gold_steel\n - steel_clasp\n - steel_bezel\n```\n\nThis output shows the best filter keys matching the query 'steel', divided into **Direct matches** (exact or close matches) and **Fuzzy matches** (similar but not exact matches). Use these filter keys to refine your watch search in `chrono24`.\n\n## Attributes\n\nThe `chrono24` instance offers public attributes:\n\n- `count`: Total number of listings found.\n- `url`: URL of listings page.\n\n```python\nimport chrono24\n\nrolex_dj = chrono24.query(\"Rolex DateJust\")\n\nrolex_dj.count\n# >>> 35582\nrolex_dj.url\n# >>> 'https://www.chrono24.com/rolex/datejust--mod45.htm?dosearch=true&query=Rolex+DateJust'\n```\n\n## Exceptions\n\nThe `chrono24` package handles specific exceptions that might occur during its use:\n\n- `NoListingsFoundException`: Raised when no listings are found.\n- `RequestException`: Raised when a request error occurs or repeated requests fail.\n\n```python\nimport chrono24\nfrom chrono24.exceptions import NoListingsFoundException, RequestException\n\ntry:\n invalid_query = chrono24.query(\"Invalid Query\")\nexcept NoListingsFoundException:\n # In cases where no listings match the provided query\n print(\"No listings were found.\")\nexcept RequestException:\n # In cases where a request error occurs or repeated requests fail\n print(\"Request error or repeated requests failed.\")\n```\n\n## Contribute\n\n- [Issues Tracker](https://github.com/irahorecka/chrono24/issues)\n- [Source Code](https://github.com/irahorecka/chrono24/tree/main/chrono24)\n\n## Support\n\nIf you are having issues or would like to propose a new feature, please use the [issues tracker](https://github.com/irahorecka/chrono24/issues).\n\n## License\n\nThis project is licensed under the MIT license.\n",
"bugtrack_url": null,
"license": null,
"summary": "chrono24",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/irahorecka/chrono24"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dc2a633f5c559928f0bd2c2014cb274ed6932ec528bbdf2c7e87fa8a43b4853e",
"md5": "df78f9ba0cb10b3e5a0b8ec2c1bd28d6",
"sha256": "9522ed9880b69c3322f563217b22b220d6cac4803dbcb4bf898fbc410faffdf9"
},
"downloads": -1,
"filename": "chrono24-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df78f9ba0cb10b3e5a0b8ec2c1bd28d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19392,
"upload_time": "2024-10-01T00:59:13",
"upload_time_iso_8601": "2024-10-01T00:59:13.657457Z",
"url": "https://files.pythonhosted.org/packages/dc/2a/633f5c559928f0bd2c2014cb274ed6932ec528bbdf2c7e87fa8a43b4853e/chrono24-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6b644b1f79d490d212cda7240654fd6c8a7048ba3f1bf751237aee059afe1ca8",
"md5": "c0e1f2ebed2b1580a26a886be1338ef5",
"sha256": "3fac0b38e98e4764504bfbeab90bf9c0c2874055f4b3561f4ad3854a04e414c9"
},
"downloads": -1,
"filename": "chrono24-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "c0e1f2ebed2b1580a26a886be1338ef5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26601,
"upload_time": "2024-10-01T00:59:15",
"upload_time_iso_8601": "2024-10-01T00:59:15.247197Z",
"url": "https://files.pythonhosted.org/packages/6b/64/4b1f79d490d212cda7240654fd6c8a7048ba3f1bf751237aee059afe1ca8/chrono24-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-01 00:59:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "irahorecka",
"github_project": "chrono24",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "beautifulsoup4",
"specs": []
},
{
"name": "faker",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "tenacity",
"specs": []
}
],
"lcname": "chrono24"
}
JSON
