# Listing SEO Auditor for Etsy sellers (`wheaten_steelpan/listing-seo-auditor`) Actor

Audit one Etsy listing, a batch, or up to 100 authorized shop listings using official Etsy API data: readiness scoring, prioritized fixes, Gemini-powered title/tag/description suggestions, and a printable HTML report. Search rank and page-one competitors via your own authorized browser capture.

- **URL**: https://apify.com/wheaten\_steelpan/listing-seo-auditor.md
- **Developed by:** [Vanja V](https://apify.com/wheaten_steelpan) (community)
- **Categories:** AI, E-commerce, SEO tools
- **Stats:** 2 total users, 1 monthly users, 33.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $75.00 / 1,000 completed listing audits

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Listing SEO Auditor for Etsy sellers

Audit one listing—or a whole portfolio—without paying for another monthly SEO subscription.

This Actor audits **one listing, an explicit batch, or up to 100 active listings from an authorized shop** using official Etsy Open API listing data. It never opens a result/ad link, requests an Etsy login, or edits a listing.

**Search rank and page-one competitors are an optional add-on, not part of the default audit.** Etsy challenges automated browsers, so a live cloud capture usually returns no rank data. To get rank, autocomplete and competitors reliably, capture the search in your own authorized browser and pass it via `marketSnapshots`. Everything listed under "What each completed listing audit includes" below runs without it.

### What each completed listing audit includes

- A deterministic **listing-readiness score out of 100**, with the scored checks shown
- Prioritized title, description, image, video, tag, and digital-product findings
- A suggested title, 13 Etsy-length-checked tags, and a description opener
- A clear kept/added/dropped tag plan
- Supply-index evidence for the buyer phrase you provide
- Mechanical validation that rejects unsupported keywords and malformed AI output
- One structured dataset item, a machine-readable `SUMMARY` record, and a self-contained `REPORT.html`

#### Only when you supply an authorized browser capture

- Timestamped observed rank across one or two Etsy result pages
- Page-one organic competitors enriched through the official API
- Autocomplete wording, live demand badges, visible basket activity, ad share, discounting, and price range
- Competitor photo/video/description/tag gaps and relative public traffic context

Without a capture, `marketIntelligence.status` is `unavailable` and the report's `notMeasured`
list says so explicitly. The audit price is the same either way — it pays for the listing
audit, scoring and copy work, which do not depend on a storefront snapshot.

The score measures listing completeness and copy readiness. Observed rank is specific to the run's time, locale, proxy, and session. It is **not** a universal rank or a prediction of traffic, sales, conversion rate, revenue, or profit.

### Pricing

| Mode | Price per completed audit | AI cost |
| --- | ---: | --- |
| Managed Gemini | **$0.075** | Included |
| Bring your own Gemini key | **$0.015** | Charged by Google to your account |
| Deterministic-only or partial result | No completed-audit event | No model call when AI is off |

The Actor charges a completed-audit event only after a valid result has been stored. A failed model call or deterministic-only result is returned as `partial` and is not charged as a completed listing audit. Apify may apply its own platform discounts or account-specific billing rules.

### Input

```json
{
  "listingUrl": "https://www.etsy.com/listing/YOUR_LISTING_ID/your-listing",
  "targetKeyword": "the buyer phrase you want to assess",
  "confirmAuthorizedListing": true,
  "acceptTerms": true,
  "useAi": true
}
```

Use a listing you own, manage, or are otherwise authorized to audit. A bare numeric listing ID also works.

For a batch, provide `audits: [{ "listingUrl": "...", "targetKeyword": "..." }]`. For a shop sweep, provide the exact `shopName` and `maxListings` (1–100). Shop phrases are derived from each listing's first multi-word tag or title and clearly labeled for review. `marketIntelligenceLimit` controls how many listings receive the slower browser snapshot (maximum 25); every selected listing still receives the official-API readiness audit.

If Etsy returns an anti-bot challenge to the cloud browser, the audit continues with market fields marked unavailable—never zero. An authorized seller can optionally pass `marketSnapshots` captured in their own browser; the Actor validates the Etsy search URL and exact keyword before using that evidence. It does not spoof a device fingerprint or bypass the challenge.

#### Optional BYOK

Add `geminiApiKey` as a secret input to use your own Google Gemini API account. The key overrides the managed key, is used only for that run, and is never returned in the dataset or printed in logs.

#### No-AI mode

Set `useAi` to `false` to receive the deterministic score and findings without sending listing content to Gemini. Because no generated rewrite is produced, the result is labelled `partial` and no completed-audit event is charged.

### Output

The default dataset contains one item per listing. Important fields include:

- `status`: `completed` or `partial`
- `score`: readiness total, band, rubric version, dimensions, and checks
- `summary` and `priorities`: the main diagnosis and ordered actions
- `rewrite`: suggested title, 13 tags, and description opener
- `tagChanges`: tags to keep, add, and drop
- `evidence`: supply-index coverage and phrase-pool counts
- `marketIntelligence`: observed ranks, page-one market, autocomplete, demand badges, competitor gaps, keyword opportunities, traffic context, and explicit scope
- `validation`: whether every mechanical output rule passed
- `ai`: provider mode, model, repair status, errors, and token usage when reported
- `etsyDataRetrievedAt` and `retention`: retrieval and content-expiry timestamps

The run output schema links to the dataset, `SUMMARY`, and printable `REPORT`. A multi-listing run stores a portfolio dashboard in `REPORT` and an individual `REPORT_<listing-id>` plus `SUMMARY_<listing-id>` for every successful listing. A shop run also stores `SHOP_SNAPSHOT`.

### Explicit limits

- No universal rank claim—only the exact timestamped search snapshot captured in the run
- No keyword search volume—autocomplete proves related wording, not popularity
- No clicking/opening of result cards or ads; competitor details come from the Open API
- No Etsy account login, OAuth order data, buyer data, or automatic listing edits
- No guarantee that applying a recommendation changes marketplace performance

The Etsy API keyword endpoint is used as a **supply index**, not presented as Etsy search ranking.

### Data handling and collection boundary

- Listing content, tags, images, public counters, shop data, and competitor details use the official Etsy Open API
- The authorized market browser opens only internally constructed `/search?q=...` pages and Etsy's same-origin autocomplete endpoint
- Result and ad destinations are never opened; Etsy credentials, orders, buyers, and private account data are never requested
- One listing, a seller-defined batch, or an authorized whole-shop sweep per run
- AI is optional and disclosed in the input form
- Customer API keys are secret inputs and are never logged or stored in output
- Web search and grounding are disabled for the model
- Suggested keywords are constrained to evidence collected for the audit and mechanically validated

Read the [Privacy Policy](https://listing-seo-auditor.netlify.app/privacy/) and [Terms of Use](https://listing-seo-auditor.netlify.app/terms/) before running the Actor. The input requires affirmative acceptance.

### Support

Questions or reproducible problems: <digitasfortuna@gmail.com>

When reporting an issue, include the Apify run ID and remove any API keys or other secrets.

***

The term “Etsy” is a trademark of Etsy, Inc. This application uses the Etsy API but is not endorsed or certified by Etsy, Inc.

Listing SEO Auditor is independently provided by FortunaDigitas3D.

# Actor input Schema

## `confirmAuthorizedListing` (type: `boolean`):

Confirm that you own, manage, or are otherwise authorized to audit every submitted listing and shop.

## `acceptTerms` (type: `boolean`):

Required before the audit runs. Terms: https://listing-seo-auditor.netlify.app/terms/ · Privacy: https://listing-seo-auditor.netlify.app/privacy/

## `listingUrl` (type: `string`):

One Etsy listing to audit. Paste the full listing URL (https://www.etsy.com/listing/1234567890/my-product) or just the listing ID (1234567890). Shop or search URLs are not accepted. Leave blank when using the batch or whole-shop fields below.

## `targetKeyword` (type: `string`):

The buyer phrase for the single listing above. The market snapshot observes this phrase's current search results and autocomplete wording.

## `audits` (type: `array`):

Audit several authorized listings in one run. Each item needs listingUrl and targetKeyword. Duplicate listing IDs are removed. Up to 100 listings total per run.

## `shopName` (type: `string`):

Loads the shop's active listings through the Etsy API and audits up to Max listings. A buyer phrase is derived from each listing's first multi-word tag or title and clearly labeled for seller review.

## `maxListings` (type: `integer`):

How many active shop listings to audit. Each completed listing is charged as one audit.

## `includeMarketIntelligence` (type: `boolean`):

Off by default: Etsy challenges the cloud browser, so this usually returns no rank data and adds about a minute to the run. To get rank, page-one competitors and autocomplete reliably, capture them in your own authorized browser and paste them into "Authorized browser captures" below. Turn this on only to attempt a live capture anyway.

## `marketIntelligenceLimit` (type: `integer`):

Browser snapshots are slower than API audits. Capture them for the first 1–25 listings; remaining listings still receive the full API readiness audit.

## `searchPages` (type: `integer`):

One page is enough for rank and page-one competition; two pages improve keyword-language evidence.

## `proxyConfiguration` (type: `object`):

Apify Proxy is recommended for stable storefront snapshots. Your chosen proxy/session affects observed rank and is recorded as context.

## `marketSnapshots` (type: `array`):

The reliable route to rank, autocomplete and page-one competitors. Capture a search snapshot in your own authorized browser and paste it here; it feeds the same report without bypassing Etsy's challenge. Each item needs listingUrl, targetKeyword (matching the audit phrase exactly) and snapshotJson.

## `useAi` (type: `boolean`):

When on, the listing's own API content is sent to Google's Gemini API, which writes the wording of the recommendations. Turn it off to receive the deterministic score and findings with no model call and no third-party processing.

## `geminiApiKey` (type: `string`):

Supply your own key to run generation on your Google account under your own terms. It overrides the managed key, is never logged or stored, and lowers the per-audit charge.

## Actor input object example

```json
{
  "confirmAuthorizedListing": false,
  "acceptTerms": false,
  "maxListings": 10,
  "includeMarketIntelligence": false,
  "marketIntelligenceLimit": 10,
  "searchPages": 2,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "useAi": true
}
```

# Actor output Schema

## `audit` (type: `string`):

One dataset row per completed/partial/failed listing, including score, market snapshot, competitor evidence, rewrite, and retention metadata.

## `summary` (type: `string`):

A single audit for one-listing runs, or a portfolio index for batch/shop runs. Per-listing records are SUMMARY\_<listing-id>.

## `report` (type: `string`):

A self-contained printable report. Batch/shop runs receive a portfolio index; individual reports are REPORT\_<listing-id>.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("wheaten_steelpan/listing-seo-auditor").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("wheaten_steelpan/listing-seo-auditor").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 '{}' |
apify call wheaten_steelpan/listing-seo-auditor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,wheaten_steelpan/listing-seo-auditor"
        }
    }
}

```

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/mkFSJgr8imLboffho/builds/n5cN7NmoW1vndTAUS/openapi.json