# Etsy Trend Gap Finder - Pinterest Signals (`leopoldsaint/pinterest-etsy-trend-gap-finder`) Actor

Find Etsy keyword opportunities with rising Pinterest demand, live Etsy evidence, and transparent scoring.

- **URL**: https://apify.com/leopoldsaint/pinterest-etsy-trend-gap-finder.md
- **Developed by:** [Leopold saint](https://apify.com/leopoldsaint) (community)
- **Categories:** E-commerce, SEO tools, AI
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $21.00 / 1,000 opportunity results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

### What Does Etsy Trend Gap Finder Do?

Find **trending Etsy keywords and products to sell** where Pinterest interest is rising before Etsy competition becomes entrenched - and know exactly **when to list** thanks to seasonal launch timing derived from a year of Pinterest history.

Enter broad product ideas such as `pet portrait`, `nursery wall art`, or `wedding invitation`. The Actor expands each idea with Pinterest's public trend data, checks live Etsy demand and competition evidence, and returns ranked opportunities with every component of the score exposed.

Run it on the Apify platform through the Console, API, schedules, integrations, or MCP clients. Results are stored in a structured dataset that you can download as JSON, CSV, Excel, XML, or RSS.

### Why Use Etsy Trend Gap Finder?

- Research Etsy product niches before committing inventory or ad spend.
- Compare rising Pinterest interest with current Etsy demand and competition.
- Get a per-keyword **seasonal window and list-by date** instead of guessing launch timing.
- Replace opaque keyword scores with inspectable evidence and source links.
- Feed ranked opportunities into spreadsheets, dashboards, AI agents, or scheduled research workflows.

### What You Get

Each result includes:

- 53 weeks of Pinterest search-interest history
- Pinterest current, average, and peak interest on a relative 0-100 scale
- week-over-week, month-over-month, and year-over-year change when available
- Etsy listing count, current carts, recent sales, badges, ads, pricing, and seller trust-wall signals
- separate 0-100 scores for Pinterest demand, Pinterest momentum, Etsy demand, Etsy competition, margin potential, and evidence confidence
- a final 0-100 opportunity score, grade, verdict, and source links
- **seasonal launch timing**: a `seasonalWindow` (`surging-now`, `list-now`, `upcoming`, `off-season`, or `evergreen`), the projected peak date, a `seasonalListByDate` with an 8-week Etsy SEO lead built in, and a 0-100 `seasonalityStrength`
- `evidenceMode: live` or `evidenceMode: demo` on every row

The Actor does not invent search volume. Pinterest values are relative interest indices, and Etsy demand is measured from visible marketplace signals.

### How It Works

1. Fetch related terms and a trailing year of history (typically 53 weekly points) from Pinterest's public Trends endpoints.
2. Rank candidates by Pinterest demand and momentum before spending on Etsy evidence.
3. Run the limited-permission [`yumitori/etsy-keyword-tool`](https://apify.com/yumitori/etsy-keyword-tool) Actor for one evidence row per shortlisted candidate.
4. Re-query Pinterest for the exact Etsy keyword returned by the evidence Actor.
5. Drop rows without an exact Pinterest match.
6. Calculate a deterministic score, sort descending, and emit only the requested number of results.

This two-stage design shortlists at most 50 Pinterest candidate terms. The upstream Etsy Actor returns at least five keyword rows per candidate, so the absolute ceiling is 250 upstream evidence rows. Before collecting evidence, this Actor also reduces the candidate count to what the parent run's pay-per-event budget can emit.

### Quick Start

```json
{
    "seeds": ["pet portrait"],
    "maxOpportunities": 3,
    "minOpportunityScore": 0,
    "candidatesPerSeed": 4
}
```

#### Inputs

| Field                 |  Default |     Limits | Description                                                                                                                 |
| --------------------- | -------: | ---------: | --------------------------------------------------------------------------------------------------------------------------- |
| `seeds`               | required |       1-10 | Broad product or niche keywords.                                                                                            |
| `maxOpportunities`    |      `3` |       1-25 | Maximum ranked rows returned.                                                                                               |
| `minOpportunityScore` |      `0` |      0-100 | Suppress results below this score.                                                                                          |
| `candidatesPerSeed`   |      `4` |       2-20 | Pinterest terms inspected per seed before shortlisting.                                                                     |
| `country`             |     `US` | 11 markets | Pinterest market for demand signals (US, GB, CA, DE, FR, IT, ES, BR, MX, AR, IN). Etsy evidence is always marketplace-wide. |
| `demoMode`            |  `false` |    boolean | Hidden development option. Uses synthetic Etsy evidence and marks every row `demo`.                                         |

### Score Formula

The component scores are deterministic and constrained to 0-100.

```text
raw opportunity =
    30% Pinterest momentum
  + 15% Pinterest demand
  + 20% Etsy demand
  + 25% Etsy headroom (100 - competition)
  + 10% margin potential

final opportunity = raw opportunity - unproven Etsy-demand penalty
```

Pinterest momentum combines recent four-week growth, the trailing-year regression slope, and reported WoW/MoM/YoY changes. Etsy competition combines log-scaled listing count, bestseller and Star Seller density, seller review and sales trust walls, and ad density, with relief when recent listings still rank.

Grades are `A` (80+), `B` (65-79), `C` (50-64), `D` (35-49), and `F` (below 35).

Scores are prioritization heuristics, not sales or profit guarantees.

### How Much Does It Cost?

This Actor charges **$0.03 per opportunity result** only when a visible row is written to the default dataset. Apify's standard `$0.00005` Actor-start event also applies. This Actor's platform usage is included in those prices.

Live runs also invoke `yumitori/etsy-keyword-tool` under the current user's limited-permission run token. Its Store charges are separate from this Actor's `opportunity-result` charge. At the time this README was written, that Actor listed $0.005 per keyword result plus its own start event and required at least five keyword results per candidate. Always check its current Store pricing before a large run.

Every nested run receives a hard `maxTotalChargeUsd` ceiling of `$0.02 + $0.006 x candidate count x 5`. The default four-candidate run is capped at $0.14 upstream, and the largest permitted 50-candidate call is capped at $1.52, even if upstream pricing changes unexpectedly. A cap is a maximum, not a guaranteed charge.

Demo mode does not invoke the upstream Etsy Actor. Demo rows are synthetic and must not be used for product decisions.

### Output

The default dataset provides two views:

- **Top opportunities**: compact ranking and decision fields
- **Evidence**: raw Pinterest and Etsy signals with source URLs

The default key-value store contains `SUMMARY`, including candidate counts, exact-match counts, emitted results, charged results, evidence mode, billing mode, and whether the user charge limit stopped output. `billingMode` is `demo`, `unconfigured`, or `pay-per-event`, so development runs cannot be mistaken for charged Store usage.

```json
{
    "evidenceMode": "live",
    "keyword": "personalized dog portrait",
    "candidateTerm": "custom dog art",
    "pinterestTerm": "personalized dog portrait",
    "opportunity": 76,
    "grade": "B",
    "pinterestMomentum": 84,
    "etsyDemand": 71,
    "etsyCompetition": 38,
    "confidence": 92,
    "verdict": "Promising: validate the product angle and production economics."
}
```

### API

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('leopoldsaint/pinterest-etsy-trend-gap-finder').call({
    seeds: ['pet portrait', 'nursery wall art'],
    maxOpportunities: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

The Actor is also available to AI clients through the Apify MCP server and supports agentic payments.

### Limitations

- Version 0.1 supports the US market only.
- Pinterest interest is relative, not absolute monthly search volume.
- Etsy evidence depends on a community Actor and its current schema, availability, permissions, and pricing.
- Emerging Pinterest terms with no exact Etsy keyword or exact Pinterest re-check are omitted instead of estimated.
- Marketplace data changes continuously; rerun before making a material inventory or advertising decision.
- This project is independent and is not affiliated with, endorsed by, or sponsored by Pinterest or Etsy.
- Use the data responsibly and comply with applicable laws and marketplace terms.

### Tips

- Start with the default one-seed input, then expand only the niches worth deeper research.
- Increase `candidatesPerSeed` to improve coverage; this also increases the separate upstream Etsy charge.
- Raise `minOpportunityScore` to keep only stronger candidates in recurring workflows.
- Schedule repeat runs because Pinterest momentum and Etsy competition change over time.

### FAQ And Support

#### Why did the Actor return fewer results than requested?

The Actor drops keywords that lack exact evidence in both sources or fall below `minOpportunityScore`. You are charged only for opportunity rows actually emitted.

#### Does a high score guarantee Etsy sales?

No. Scores prioritize research candidates using current marketplace evidence; they are not sales, margin, or profit guarantees.

#### Where can I get help?

Open the Actor's **Issues** tab and include the failed run URL, expected behavior, and non-sensitive input. Custom data or workflow requirements can be discussed there as well.

# Actor input Schema

## `seeds` (type: `array`):

Enter 1-10 broad Etsy product ideas. Each seed is expanded with Pinterest trend data before Etsy evidence is collected.

## `maxOpportunities` (type: `integer`):

Maximum number of ranked opportunity rows to return.

## `minOpportunityScore` (type: `integer`):

Only return rows at or above this transparent 0-100 score. Use 0 to inspect all evidence.

## `candidatesPerSeed` (type: `integer`):

How many related Pinterest terms to inspect per seed before shortlisting. Higher values increase upstream Etsy evidence cost.

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

Country used for Pinterest demand and momentum signals. Etsy evidence is always marketplace-wide (etsy.com).

## `demoMode` (type: `boolean`):

Development-only mode that uses synthetic Etsy evidence and marks every row as demo.

## Actor input object example

```json
{
  "seeds": [
    "pet portrait"
  ],
  "maxOpportunities": 3,
  "minOpportunityScore": 0,
  "candidatesPerSeed": 4,
  "country": "US",
  "demoMode": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

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

No description

# 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 = {
    "seeds": [
        "pet portrait"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("leopoldsaint/pinterest-etsy-trend-gap-finder").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 = { "seeds": ["pet portrait"] }

# Run the Actor and wait for it to finish
run = client.actor("leopoldsaint/pinterest-etsy-trend-gap-finder").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 '{
  "seeds": [
    "pet portrait"
  ]
}' |
apify call leopoldsaint/pinterest-etsy-trend-gap-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=leopoldsaint/pinterest-etsy-trend-gap-finder",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/Z6uWlkt2zV6YYJo7C/builds/JZLfvoSbgRIb6gweb/openapi.json