# Vinted Product Description (`pintostudio/vinted-product-description`) Actor

A powerful Apify actor for scraping detailed product information from Vinted listings across multiple countries and domains.

- **URL**: https://apify.com/pintostudio/vinted-product-description.md
- **Developed by:** [Pinto Studio](https://apify.com/pintostudio) (community)
- **Categories:** E-commerce, Developer tools, Other
- **Stats:** 14 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: 1.00 out of 5 stars

## Pricing

from $4.10 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Vinted Product Description Actor

A powerful Apify actor for scraping detailed product information from Vinted listings across multiple countries and domains.

### Overview

The Vinted Product Description Actor extracts comprehensive product data from Vinted marketplace listings, including product details, pricing, seller information, images, and metadata. It supports all major Vinted domains and provides structured JSON output for easy integration.

### Features

- ✅ **Multi-country support** - Works with 22 Vinted domains
- ✅ **Comprehensive data extraction** - Product details, pricing, seller info, images
- ✅ **Error handling** - Robust error handling and logging
- ✅ **Structured output** - Clean JSON format with timestamps
- ✅ **Data storage** - Automatic dataset and key-value store integration

### Supported Countries

The actor supports the following Vinted domains:

| Country | Domain | Code |
|---------|--------|------|
| International | vinted.com | `com` |
| France | vinted.fr | `fr` |
| Germany | vinted.de | `de` |
| Spain | vinted.es | `es` |
| Italy | vinted.it | `it` |
| Belgium | vinted.be | `be` |
| Netherlands | vinted.nl | `nl` |
| Austria | vinted.at | `at` |
| Switzerland | vinted.ch | `ch` |
| Czech Republic | vinted.cz | `cz` |
| Denmark | vinted.dk | `dk` |
| Finland | vinted.fi | `fi` |
| Hungary | vinted.hu | `hu` |
| Lithuania | vinted.lt | `lt` |
| Latvia | vinted.lv | `lv` |
| Luxembourg | vinted.lu | `lu` |
| Poland | vinted.pl | `pl` |
| Portugal | vinted.pt | `pt` |
| Romania | vinted.ro | `ro` |
| Sweden | vinted.se | `se` |
| Slovakia | vinted.sk | `sk` |
| Slovenia | vinted.si | `si` |

### Input Configuration

#### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `productUrl` | String | Complete Vinted product URL to scrape |

#### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `country` | String | `com` | Country domain code for Vinted |

#### Input Schema

```json
{
  "productUrl": "https://www.vinted.pt/items/6770233619-saia-forrada-florida-tam-m-cintura-33cm-comprimento-81cm",
  "country": "pt"
}
```

#### URL Format Requirements

Product URLs must follow this pattern:

```
https://www.vinted.[domain]/items/[product-id]-[product-slug]
```

Example valid URLs:

- `https://www.vinted.com/items/1234567890-blue-dress-size-m`
- `https://www.vinted.fr/items/9876543210-chemise-homme-taille-l`
- `https://www.vinted.pt/items/6770233619-saia-forrada-florida-tam-m-cintura-33cm-comprimento-81cm`

### Output Format

The actor returns comprehensive product data in the following structure:

```json
{
  "productUrl": "https://www.vinted.pt/items/6770233619-saia-forrada-florida-tam-m-cintura-33cm-comprimento-81cm",
  "country": "pt",
  "timestamp": "2025-07-29T07:45:43.672Z",
  "product": {
    "id": 6770233619,
    "title": "Saia forrada, florida. Tam M. Cintura 33cm. Comprimento 81cm.",
    "description": "Novo sem etiqueta. Há várias peças a preços incríveis, fazendo conjunto recebe um desconto 🤗",
    "status_id": 1,
    "disposal_conditions": 4,
    "catalog_id": 199,
    "currency": "EUR",
    "price": {
      "amount": "7.5",
      "currency_code": "EUR"
    },
    "brand_dto": {
      "id": 226316,
      "title": "Local",
      "slug": "local"
    },
    "color1": "White",
    "status": "New without tags",
    "favourite_count": 16,
    "is_favourite": false,
    "is_sold": true,
    "photos": [
      {
        "id": 27536090505,
        "image_no": 1,
        "width": 590,
        "height": 800,
        "url": "https://images1.vinted.net/t/01_0033f_eoHbJxPUsuJaT9Zwvkno1yTL/f800/1753770337.jpeg",
        "is_main": true,
        "thumbnails": [...]
      }
    ],
    "user": {
      "id": 74292334,
      "login": "acvs80",
      "country_id": 21,
      "feedback_count": 270,
      "feedback_reputation": 1,
      "city": "Guimarães",
      "item_count": 61,
      "followers_count": 138,
      "following_count": 4
    }
  }
}
```

#### Key Data Fields

##### Product Information

- `id` - Unique product identifier
- `title` - Product title/name
- `description` - Seller's product description
- `status` - Condition (e.g., "New without tags", "Used - Good")
- `color1` - Primary color
- `brand_dto` - Brand information
- `is_sold` - Whether item has been sold

##### Pricing

- `price.amount` - Item price
- `price.currency_code` - Currency (EUR, USD, etc.)
- `service_fee` - Platform service fee
- `total_item_price` - Total price including fees

##### Images

- `photos` - Array of product images
- `url` - High-resolution image URL
- `thumbnails` - Various sized thumbnails
- `is_main` - Indicates main product image

##### Seller Information

- `user.login` - Seller username
- `user.feedback_count` - Number of reviews
- `user.feedback_reputation` - Seller rating
- `user.city` - Seller location
- `user.item_count` - Total items for sale

### Usage Examples

#### Basic Usage

```javascript
// Input
{
  "productUrl": "https://www.vinted.com/items/1234567890-blue-summer-dress"
}
```

#### Multi-country Usage

```javascript
// Scrape from French Vinted
{
  "productUrl": "https://www.vinted.fr/items/9876543210-robe-ete-bleue",
  "country": "fr"
}

// Scrape from German Vinted
{
  "productUrl": "https://www.vinted.de/items/5555555555-blaues-sommerkleid",
  "country": "de"
}
```

### Data Storage

The actor automatically stores data in two locations:

#### Dataset

All scraped products are pushed to the default dataset with the following structure:

- `productUrl` - Original product URL
- `country` - Country domain used
- `product` - Complete product data
- `timestamp` - ISO timestamp of scraping
- `error` - Error message (if applicable)

#### Key-Value Store

The latest product data is saved to the key-value store under the key `product_description`.

### Error Handling

The actor includes comprehensive error handling:

#### Common Error Scenarios

- **Invalid URL format** - Returns validation error
- **Product not found** - Returns null product data
- **Network issues** - Retries with exponential backoff
- **Rate limiting** - Handles API rate limits gracefully

#### Error Output Format

```json
{
  "productUrl": "https://www.vinted.com/items/invalid-url",
  "country": "com",
  "error": "Product not found or URL invalid",
  "timestamp": "2025-07-29T08:00:00.000Z",
  "product": null
}
```

### Rate Limits and Best Practices

#### Recommended Settings

- **Memory**: 1024 MB minimum
- **Timeout**: 300 seconds for single products
- **Concurrent runs**: Limited by Vinted's rate limits

#### Best Practices

1. **URL validation** - Ensure URLs match the required format
2. **Country matching** - Use the correct country code for the domain
3. **Batch processing** - For multiple products, add delays between requests
4. **Error monitoring** - Check the dataset for failed scrapes

### Integration Examples

#### Using the Data

```javascript
// Access scraped data from dataset
const dataset = await Actor.openDataset();
const items = await dataset.getData();

items.items.forEach(item => {
  if (item.product) {
    console.log(`Product: ${item.product.title}`);
    console.log(`Price: ${item.product.price.amount} ${item.product.price.currency_code}`);
    console.log(`Seller: ${item.product.user.login}`);
  }
});
```

#### API Integration

```javascript
// Use with Apify API
const client = new ApifyClient({ token: 'your-token' });

const run = await client.actor('the-actor-id').call({
  productUrl: 'https://www.vinted.com/items/1234567890-product-name',
  country: 'com'
});

const dataset = await client.dataset(run.defaultDatasetId).listItems();
console.log(dataset.items[0]);
```

### Troubleshooting

#### Common Issues

##### "Product not found"

- Verify the URL is correct and accessible
- Check if the product is still available (not deleted)
- Ensure the country code matches the domain

##### "Invalid URL format"

- URL must include the complete path with product ID
- Remove any query parameters or fragments
- Ensure the domain matches supported countries

##### "Rate limit exceeded"

- Reduce concurrent requests
- Add delays between scraping sessions
- Consider upgrading your Apify plan

#### Debug Information

The actor provides detailed logging:

- Input validation results
- HTTP request/response details
- Data extraction progress
- Error stack traces

### Support

If you have any questions or encounter any issues, please consult the Apify documentation or reach out to us through one of the following channels:

- **Telegram**: [@pintoflow](https://t.me/pintoflow)
- **Email**: <pintoflowpt@gmail.com>
- **Apify Platform**: You can also contact us directly through this platform.

***

# Actor input Schema

## `productUrl` (type: `string`):

The complete Vinted product URL to scrape

## `country` (type: `string`):

The country domain for Vinted (e.g., 'com' for vinted.com, 'fr' for vinted.fr)

## Actor input object example

```json
{
  "productUrl": "https://www.vinted.com/items/8340472195-floaty-play-suit",
  "country": "com"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "productUrl": "https://www.vinted.com/items/8340472195-floaty-play-suit",
    "country": "com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("pintostudio/vinted-product-description").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "productUrl": "https://www.vinted.com/items/8340472195-floaty-play-suit",
    "country": "com",
}

# Run the Actor and wait for it to finish
run = client.actor("pintostudio/vinted-product-description").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "productUrl": "https://www.vinted.com/items/8340472195-floaty-play-suit",
  "country": "com"
}' |
apify call pintostudio/vinted-product-description --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,pintostudio/vinted-product-description"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/qd9lQEybSQVau2CS7/builds/bdNcNa0fGczLDAEcg/openapi.json