# Etsy Product Description (`pintostudio/etsy-product-description`) Actor Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more. - **URL**: https://apify.com/pintostudio/etsy-product-description.md - **Developed by:** [Pinto Studio](https://apify.com/pintostudio) (community) - **Categories:** E-commerce, SEO tools - **Stats:** 28 total users, 1 monthly users, 0.0% runs succeeded, 1 bookmarks - **User rating**: 3.00 out of 5 stars ## Pricing $27.99/month + usage To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README #### Etsy Product Description API Documentation Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more. This API is perfect for integrating Etsy product data into your applications, improving marketing campaigns, or powering ecommerce tools. ##### **Parameters** | Name | Type | Description | Required | Default | |------------|--------|--------------------------------------|----------|---------| | `listingId` | String | Unique identifier for the Etsy product listing. | Yes | N/A | | `currency` | String | The currency for the product's price (e.g., USD). | No | `USD` | | `language` | String | Language code for the product description (e.g., `en-GB`). | No | `en-GB` | | `country` | String | The country code (e.g., `US`). | No | `US` | --- ##### **Example Response** ```json { "title": "14K Solid Gold Family Birthstone Necklace, Birthstone Gift, Christmas Gift, Bridesmaid Gift, Gift for Mom, Birthday Gift, Birthstone Jewelry", "productId": "1301638116", "gtin": "n/a", "description": "Silver Birthstone Necklace, Personalized Gifts, 14k Solid Gold Birthstone Jewelry, Family Necklace For Grandmothers, Christmas Gift, Best Gifts for Mothers, Personalized Birthstone Necklace, Family Birthstone Necklace, Birthstone Gift, Dainty Necklace, Gift For Her, Birthday Gift\n\n☆ Back to my store for more options: https://www.etsy.com/shop/aceelegance\n\n☆ All the pieces you purchased from AceElegance come with a Certificate of Authenticity (925 Sterling Silver, 8k Solid Gold, 14k Solid Gold, 18k Solid Gold)\n\n☆ www.aceelegance.com ☆\n\n[...truncated for brevity...]", "images": [ "https://i.etsystatic.com/27808603/r/il/17eff8/4476872409/il_fullxfull.4476872409_hru6.jpg", "https://i.etsystatic.com/27808603/r/il/dd8d66/4292154829/il_fullxfull.4292154829_7ikv.jpg", "https://i.etsystatic.com/27808603/r/il/0ba591/4244514176/il_fullxfull.4244514176_fm31.jpg", "https://i.etsystatic.com/27808603/r/il/abc9bc/4292145011/il_fullxfull.4292145011_thdf.jpg" ], "price": { "salePrice": "14.67", "originalPrice": "26.67", "currency": "$", "discount": "45% off" }, "variations": [ { "options1": [ { "value": "2922229031", "text": "Silver-1 Birthstone ($18.33)" }, { "value": "2922229041", "text": "Silver-2 Birthstones ($21.99)" } ] }, { "options2": [ { "value": "2922229033", "text": "14 Inches" }, { "value": "2922229035", "text": "15 Inches" } ] } ], "category": [ "Jewellery", "Necklaces", "Charm Necklaces" ], "brand": { "name": "AceElegance", "logo": "https://i.etsystatic.com/isla/e9d72e/60194815/isla_500x500.60194815_ndw6wt55.jpg?version=0" }, "url": "https://www.etsy.com/listing/1301638116/14k-solid-gold-family-birthstone", "ratingSummary": { "ratingValue": "4.8", "reviewCount": 15678 }, "review": [ { "@type": "Review", "reviewRating": { "@type": "Rating", "ratingValue": 5, "bestRating": 5 }, "datePublished": "2024-11-22", "reviewBody": "The necklace came in the cutest little packaging and was absolutely perfect. My grandmother is gonna love it", "author": { "@type": "Person", "name": "Raven Nellenback" } }, { "@type": "Review", "reviewRating": { "@type": "Rating", "ratingValue": 5, "bestRating": 5 }, "datePublished": "2024-11-21", "reviewBody": "Cannot wait to give this to my mother in law for Christmas :)", "author": { "@type": "Person", "name": "Megan Marchase" } } ] } ```` *** ##### **Description of Response** | Field | Type | Description | |----------------|------------|--------------------------------------------------------------------------------------------------| | `title` | String | The product's name or title. | | `productId` | String | Unique identifier for the product. | | `gtin` | String | Global Trade Item Number if available. | | `description` | String | Detailed description of the product. | | `images` | Array | List of URLs for product images. | | `price` | Object | Pricing information including sale and original prices, currency, and discount. | | `variations` | Array | Available variations such as colors, sizes, or styles. | | `category` | Array | Hierarchical category for the product. | | `brand` | Object | Brand details including name and logo. | | `url` | String | Direct URL to the product page on Etsy. | | `ratingSummary`| Object | Summary of product ratings and total review count. | | `review` | Array | List of recent reviews with rating, date, content, and reviewer details. | *** Here's an enhanced example of the Etsy Product Description API documentation, including a detailed description and FAQs with 10 questions and answers. *** #### **Etsy Product Description API** Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more. This API is perfect for integrating Etsy product data into your applications, improving marketing campaigns, or powering ecommerce tools. *** #### **Endpoint** `GET /etsy-product-description` *** #### **Parameters** | Parameter | Type | Required | Default Value | Description | |-------------|--------|----------|---------------|--------------------------------------------------------------------------| | `listingId` | String | Yes | N/A | The unique ID of the Etsy product listing to retrieve information about. | | `currency` | String | No | `USD` | The currency format for the pricing information. | | `language` | String | No | `en-GB` | The language format for the returned data. | | `country` | String | No | `US` | The country format for the returned data. | *** #### **Example Response** ```json { "title": "14K Solid Gold Family Birthstone Necklace, Birthstone Gift, Christmas Gift, Bridesmaid Gift, Gift for Mom, Birthday Gift, Birthstone Jewelry", "productId": "1301638116", "gtin": "n/a", "description": "Silver Birthstone Necklace, Personalized Gifts, ...", "images": [ "https://i.etsystatic.com/27808603/r/il/17eff8/4476872409/il_fullxfull.4476872409_hru6.jpg", "https://i.etsystatic.com/27808603/r/il/dd8d66/4292154829/il_fullxfull.4292154829_7ikv.jpg" ], "price": { "salePrice": "14.67", "originalPrice": "26.67", "currency": "$", "discount": "45% off" }, "variations": [ { "options1": [ { "value": "2922229031", "text": "Silver-1 Birthstone ($18.33)" } ] } ], "category": ["Jewellery", "Necklaces", "Charm Necklaces"], "brand": { "name": "AceElegance", "logo": "https://i.etsystatic.com/isla/e9d72e/60194815/isla_500x500.60194815_ndw6wt55.jpg?version=0" }, "url": "https://www.etsy.com/listing/1301638116/14k-solid-gold-family-birthstone", "ratingSummary": { "ratingValue": "4.8", "reviewCount": 15678 }, "review": [ { "reviewRating": { "ratingValue": 5, "bestRating": 5 }, "datePublished": "2024-11-22", "reviewBody": "The necklace came in the cutest little packaging...", "author": { "name": "Raven Nellenback" } } ] } ``` *** This API provides detailed information about a specific Etsy product listing. With the listing ID as input, the API returns: - Product title, description, and category hierarchy. - High-quality images for the listing. - Pricing details, including sale price, original price, currency, and discounts. - Available variations, such as material, color, and size. - Brand details, including name and logo. - Reviews and ratings from customers. - Product URL for direct navigation. This API is suitable for building ecommerce aggregators, powering marketing tools, or enhancing customer engagement with accurate product details. *** #### **FAQs** 1. **What is the purpose of the `listingId` parameter?**\ The `listingId` identifies the specific Etsy product you want information about. It’s mandatory to ensure the API fetches the correct listing. 2. **Can I retrieve information in a different currency?**\ Yes, use the `currency` parameter to specify the desired currency. For example, use `EUR` for Euros or `GBP` for British Pounds. 3. **What languages are supported?**\ The API supports multiple languages. By default, it returns data in English (`en-GB`). Use the `language` parameter to set your preferred language. 4. **What happens if the `country` parameter is not specified?**\ If not provided, the API defaults to `US`. This affects shipping information and localized data. 5. **Are the reviews limited in the response?**\ The API typically returns the top 5 reviews. For more reviews, additional queries may be required. 6. **How are discounts calculated in the `price` object?**\ Discounts are calculated based on the difference between `salePrice` and `originalPrice`. The `discount` field shows the percentage reduction. 7. **Can I use this API to list multiple Etsy products?**\ Currently, the API supports fetching details for one product per request. Batch requests require individual calls. 8. **What happens if the listing ID is invalid or not found?**\ The API returns an error message indicating the issue. Ensure the listing ID is correct and active. 9. **Are images returned in specific resolutions?**\ Yes, the images are provided in high resolution, ideal for use in ecommerce platforms or marketing materials. 10. **How often is the data updated?**\ The data reflects Etsy’s most recent updates. If changes occur on Etsy (e.g., price updates), they will appear in API responses shortly after. *** # Actor input Schema ## `listingId` (type: `string`): The listingId to retrieve the description of. ## `currency` (type: `string`): The currency code. ## `language` (type: `string`): The language. ## `country` (type: `string`): The country. ## Actor input object example ```json { "listingId": "1301638116", "currency": "USD", "language": "en-US", "country": "US" } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "listingId": "1301638116", "currency": "USD", "language": "en-US", "country": "US" }; // Run the Actor and wait for it to finish const run = await client.actor("pintostudio/etsy-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "listingId": "1301638116", "currency": "USD", "language": "en-US", "country": "US", } # Run the Actor and wait for it to finish run = client.actor("pintostudio/etsy-product-description").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "listingId": "1301638116", "currency": "USD", "language": "en-US", "country": "US" }' | apify call pintostudio/etsy-product-description --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=pintostudio/etsy-product-description", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Etsy Product Description", "description": "Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more.", "version": "1.0", "x-build-id": "gGl1k0Sgc2moMwdtJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/pintostudio~etsy-product-description/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-pintostudio-etsy-product-description", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/pintostudio~etsy-product-description/runs": { "post": { "operationId": "runs-sync-pintostudio-etsy-product-description", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/pintostudio~etsy-product-description/run-sync": { "post": { "operationId": "run-sync-pintostudio-etsy-product-description", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "listingId" ], "properties": { "listingId": { "title": "listingId", "type": "string", "description": "The listingId to retrieve the description of." }, "currency": { "title": "currency", "type": "string", "description": "The currency code." }, "language": { "title": "language", "type": "string", "description": "The language." }, "country": { "title": "country", "type": "string", "description": "The country." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```