{"id":30851609,"url":"https://github.com/vlymar1/vinted-api-kit","last_synced_at":"2026-06-06T00:00:56.074Z","repository":{"id":306992485,"uuid":"1025076240","full_name":"vlymar1/vinted-api-kit","owner":"vlymar1","description":"Lightweight asynchronous Python client library for accessing Vinted API and scraping item data","archived":false,"fork":false,"pushed_at":"2026-01-07T08:51:54.000Z","size":109,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-24T08:14:48.478Z","etag":null,"topics":["api-wrapper","asyncio","python","vinted","vinted-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vlymar1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-23T17:23:11.000Z","updated_at":"2026-01-21T13:54:43.000Z","dependencies_parsed_at":"2025-07-28T22:12:10.178Z","dependency_job_id":"31cf6417-4a8c-4c68-bcc2-12a8b4f22796","html_url":"https://github.com/vlymar1/vinted-api-kit","commit_stats":null,"previous_names":["vlymar1/vinted-api-kit","vlymar-dev/vinted-api-kit"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/vlymar1/vinted-api-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Fvinted-api-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Fvinted-api-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Fvinted-api-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Fvinted-api-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlymar1","download_url":"https://codeload.github.com/vlymar1/vinted-api-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Fvinted-api-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33964367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","asyncio","python","vinted","vinted-api"],"created_at":"2025-09-07T07:18:17.202Z","updated_at":"2026-06-06T00:00:56.023Z","avatar_url":"https://github.com/vlymar1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![Vinted Api Kit logo](https://raw.githubusercontent.com/vlymar1/vinted-api-kit/main/assets/logo.png)\n\n***Lightweight asynchronous Python client library for accessing Vinted API and scraping item data.***\n\n[![Package Version](https://img.shields.io/pypi/v/vinted-api-kit.svg)](https://pypi.org/project/vinted-api-kit/)\n[![Python Version](https://img.shields.io/pypi/pyversions/vinted-api-kit.svg)](https://pypi.org/project/vinted-api-kit/)\n[![codecov](https://codecov.io/github/vlymar1/vinted-api-kit/graph/badge.svg?token=SLCFGVYDOM)](https://codecov.io/github/vlymar1/vinted-api-kit)\n[![Downloads](https://static.pepy.tech/badge/vinted-api-kit)](https://pepy.tech/project/vinted-api-kit)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Typed](https://img.shields.io/badge/typed-mypy-blue)](http://mypy-lang.org/)\n[![License](https://img.shields.io/pypi/l/vinted-api-kit.svg)](https://github.com/vlymar1/vinted-api-kit/blob/main/LICENSE)\n\u003c/div\u003e\n\n## ✨ Features\n\n- 🚀 **Asynchronous** - Built with asyncio for high performance\n- 🌍 **Auto-locale Detection** - Automatically detects locale from URL\n- 🔍 **Item Search** - Search catalog with filters, sorting and pagination\n- 📦 **Item Details** - Get complete item information with rich metadata\n- 🍪 **Cookie Persistence** - Automatic session management with multiple storage formats\n- 🔐 **Proxy Support** - Simple string-based proxy configuration\n- 📊 **Type Hints** - Full typing support with Literal types for better IDE experience\n- 🎯 **Dataclass Models** - Fast and efficient data models (15% performance boost)\n- 🛡️ **Custom Exceptions** - Detailed error hierarchy for precise error handling\n- 💾 **Flexible Storage** - Choose between pickle, JSON, or Mozilla cookie formats\n\n## 📚 Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Migration Guide](#migration-guide)\n- [Development](#development)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Installation\n\nInstall via pip:\n```bash\npip install vinted-api-kit\n```\nOr using poetry:\n```bash\npoetry add vinted-api-kit\n```\n\n## Usage\n\n### Basic Example\n```python\nimport asyncio\nfrom vinted import VintedClient\n\nasync def main():\n    async with VintedClient() as client:\n        items = await client.search_items(\n            url=\"https://www.vinted.com/catalog?search_text=nike\",\n            per_page=5\n        )\n\n        for item in items:\n            print(f\"• {item.title} - {item.price} {item.currency}\")\n\nasyncio.run(main())\n```\n\n---\n\n### Configuration\n\n#### 🔐 Proxy Support\n\n\u003e Use a proxy by passing a simple connection string:\n```python\nasync with VintedClient(\n    proxy=\"user:pass@proxy.example.com:8080\"  # Format: [user:pass@]host:port\n) as client:\n    items = await client.search_items(url)\n```\n\n#### 💾 Cookie Persistence\n\n\u003e Save cookies between sessions to avoid repeated authentication:\n```python\nfrom pathlib import Path\n\nasync with VintedClient(\n    persist_cookies=True,              # Enable persistence\n    cookies_dir=Path(\"./cookies\"),     # Storage directory\n    storage_format=\"json\"              # Format: pickle | json | mozilla\n) as client:\n    items = await client.search_items(url)\n```\n\n**Storage formats:**\n- **`\"json\"`** (default) - Human-readable, portable across platforms\n- **`\"pickle\"`** - Fastest, Python-native binary format\n- **`\"mozilla\"`** - Browser-compatible Netscape format\n\n#### 🔍 Search Options\n\n\u003e Use type-safe sorting and pagination:\n```python\nfrom vinted import SortOrder\n\nitems = await client.search_items(\n    url=\"https://www.vinted.de/catalog?brand_ids[]=53\",\n    per_page=20,                      # Items per page (1-96)\n    page=1,                           # Page number\n    order=\"price_low_to_high\"         # Sort order (IDE auto-complete)\n)\n```\n\n**Available sort orders:**\n- `newest_first` - Most recent items\n- `relevance` - Best match\n- `price_low_to_high` - Cheapest first\n- `price_high_to_low` - Most expensive first\n\n#### 📦 Raw Data\n\n\u003e Get raw JSON dictionaries instead of parsed models:\n```python\nraw_items = await client.search_items(\n    url=\"https://www.vinted.com/catalog?search_text=shoes\",\n    raw_data=True  # Returns list[dict] instead of list[CatalogItem]\n)\n```\n\n---\n\n### Item Details\n\n\u003e Fetch detailed information about a specific item:\n```python\nitem = await client.item_details(\n    url=\"https://www.vinted.com/items/1234567890\"\n)\n\nprint(f\"Title: {item.title}\")\nprint(f\"Brand: {item.brand_title}\")\nprint(f\"Size: {item.size_title}\")\nprint(f\"Price: {item.price} {item.currency}\")\nprint(f\"Total: {item.total_item_price}\")\nprint(f\"Description: {item.description}\")\n\n# Or get raw JSON\nraw_item = await client.item_details(url, raw_data=True)\n```\n\n### Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `proxy` | `str \\| None` | `None` | Proxy string: `\"user:pass@host:port\"` or `\"host:port\"` |\n| `cookies_dir` | `Path \\| None` | `Path(\".\")` | Directory for cookie storage |\n| `persist_cookies` | `bool` | `False` | Enable cookie persistence between sessions |\n| `storage_format` | `\"json\" \\| \"pickle\" \\| \"mozilla\"` | `\"json\"` | Cookie storage format |\n\n**Storage formats:** `json` (default), `pickle`, `mozilla`. See [Storage Formats](#storage-formats:) for details.\n\n\n\n### Exception Handling\n```python\nfrom vinted import (\n    VintedClient,\n    VintedError,           # Base exception\n    VintedAPIError,        # API errors (4xx, 5xx)\n    VintedAuthError,       # Authentication failures\n    VintedNetworkError,    # Network/connection errors\n    VintedConfigError,     # Invalid configuration\n    VintedValidationError, # Input validation errors\n    VintedRateLimitError,  # Rate limiting (429)\n)\n\ntry:\n    async with VintedClient(proxy=\"invalid://proxy\") as client:\n        items = await client.search_items(url)\nexcept VintedConfigError as e:\n    print(f\"Configuration error: {e}\")\nexcept VintedValidationError as e:\n    print(f\"Invalid input: {e}\")\nexcept VintedRateLimitError as e:\n    print(f\"Rate limited: {e.status_code}\")\nexcept VintedAuthError as e:\n    print(f\"Auth failed: {e}\")\nexcept VintedNetworkError as e:\n    print(f\"Network error: {e.original_error}\")\nexcept VintedAPIError as e:\n    print(f\"API error: {e.status_code}\")\n```\n\n\n---\n## Migration Guide\n### (v0.x → v1.0)\n### Breaking Changes\n\nIf you're upgrading from version 0.x, here are the key changes:\n\n#### 1. Import Path Changed\n```python\n# ❌ Old (v0.x)\nfrom vinted_api_kit import VintedApi\n\n# ✅ New (v1.0)\nfrom vinted import VintedClient\n```\n\n#### 2. Class Renamed\n```python\n# ❌ Old\nasync with VintedApi() as api:\n    pass\n\n# ✅ New\nasync with VintedClient() as client:\n    pass\n```\n\n#### 3. Locale Parameter Removed\n```python\n# ❌ Old (manual locale)\nasync with VintedApi(locale=\"fr\") as api:\n    items = await api.search_items(url)\n\n# ✅ New (auto-detected from URL)\nasync with VintedClient() as client:\n    items = await client.search_items(url)  # Locale detected from URL\n```\n\n#### 4. Proxy Configuration Changed\n```python\n# ❌ Old (dict format)\nasync with VintedApi(\n    proxies={\"http\": \"http://user:pass@proxy:8080\"}\n) as api:\n    pass\n\n# ✅ New (simple string)\nasync with VintedClient(\n    proxy=\"user:pass@proxy:8080\"  # ← Without \"http://\"\n) as client:\n    pass\n```\n\n#### 5. New Storage Format Option\n```python\n# ✅ New feature in v1.0\nasync with VintedClient(\n    persist_cookies=True,\n    storage_format=\"json\"  # Choose: \"json\", \"pickle\", \"mozilla\"\n) as client:\n    pass\n```\n\n### Quick Migration Checklist\n\n- [ ] Change import: `vinted_api_kit` → `vinted`\n- [ ] Rename class: `VintedApi` → `VintedClient`\n- [ ] Remove `locale` parameter (auto-detected)\n- [ ] Update proxy format: dict → string\n- [ ] Optional: Choose storage format\n\n### Full Example\n\n**Before (v0.x):**\n```python\nfrom vinted_api_kit import VintedApi\n\nasync with VintedApi(\n    locale=\"fr\",\n    proxies={\"http\": \"http://proxy:8080\"},\n    persist_cookies=True\n) as api:\n    items = await api.search_items(\n        url=\"https://www.vinted.fr/catalog?search_text=nike\"\n    )\n```\n\n**After (v1.0):**\n```python\nfrom vinted import VintedClient\n\nasync with VintedClient(\n    proxy=\"proxy:8080\",\n    persist_cookies=True,\n    storage_format=\"pickle\"  # New option!\n) as client:\n    items = await client.search_items(\n        url=\"https://www.vinted.fr/catalog?search_text=nike\"\n    )\n```\n\n---\n## Development\n\n### Setup\n```bash\ngit clone https://github.com/vlymar1/vinted-api-kit.git\ncd vinted-api-kit\n\npip install hatch\nhatch shell\n```\n\n### Project Structure\n```\nvinted-api-kit/\n├── vinted/             # Main package\n│   ├── api/            # API endpoint handlers\n│   ├── models/         # Data models (dataclasses)\n│   ├── storage/        # Cookie storage strategies\n│   ├── client.py       # Main client (VintedClient)\n│   ├── session.py      # HTTP session management\n│   ├── auth.py         # Authentication logic\n│   ├── constants.py    # Constants and type definitions\n│   ├── exceptions.py   # Custom exceptions\n│   └── utils.py        # Utility functions\n├── tests/              # Test suite\n└── examples/           # Usage examples\n```\n\n### Testing\n```bash\nmake test-coverage      # Run tests with coverage\nmake test-coverage-view # View coverage report in browser\n```\n\n### Code Quality\n```bash\nmake lint-check         # Check code with ruff and mypy\nmake lint-reformat      # Format and fix code with ruff\n```\n\n### Cleanup\n```bash\nmake clean              # Remove cache files and build artifacts\n```\n\n### Development Guidelines\n\n- Follow PEP 8 style guidelines\n- Use type hints for all functions\n- Write tests for new features\n- Update CHANGELOG.md for notable changes\n- Run `make lint-check` before committing\n- Contributions welcome! Open issues or pull requests\n\n---\n## Changelog\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for the list of notable changes per version.\n\n### How to create and maintain changelog?\n\n- Start a `CHANGELOG.md` file at the root of your repo.\n- Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format for consistent structure.\n- For each release version, record:\n  - Added — new features\n  - Changed — updates/improvements\n  - Fixed — bug fixes\n  - Removed — deprecated or removed features\n- Update changelog **before** tagging a new release (e.g., `v1.0.0`).\n- Automate changelog generation optionally by tools such as:\n  - [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator)\n  - [auto-changelog](https://github.com/CookPete/auto-changelog)\n  - Conventional commits combined with [semantic-release](https://semantic-release.gitbook.io/semantic-release/)\n\n---\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n_⚠ Disclaimer_\n\nThis library is intended for personal and lawful use only.\nThe author is not responsible for any misuse, including but not limited to:\n- Violations of applicable laws or regulations\n- Breaches of terms of service of third-party websites\n\n_By using this library, you agree that you are solely responsible for your actions._\n\n---\n## Maintainers / Contacts\n\n- GitHub: [https://github.com/vlymar1](https://github.com/vlymar1)\n\nFeel free to open issues or contact for support and collaborations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlymar1%2Fvinted-api-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlymar1%2Fvinted-api-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlymar1%2Fvinted-api-kit/lists"}