# Pinterest Trends (`crawlerbros/pinterest-trends`) Actor

Collect Pinterest public featured trends, editorial trends, shopping categories, and trend time series by region.

- **URL**: https://apify.com/crawlerbros/pinterest-trends.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

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

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## Pinterest Trends

Collect **public Pinterest trend topics, editorial stories, shopping categories, and shopping trend metrics**. Use region and time-window inputs to receive values from Pinterest's public Trends data; the actor never invents search volume, forecasts, rankings, or private account analytics.

### What this actor does

- **Four public modes:** featured topics, editorial stories, shopping categories, and shopping metrics.
- **Regional results:** supports the public `US`, `GB+IE`, and `CA` choices.
- **Time windows:** requests published historical and forecast periods for shopping metrics.
- **Rich trend context:** includes public examples, related searches, category hierarchy, and time-series values when supplied.
- **Truthful output:** preserves published zeroes and `false` values and omits unavailable data.

### Output per record

Every row includes `sourceUrl` and `recordType`. Depending on the selected mode, rows are `trendFeatured`, `trendEditorial`, `shoppingCategory`, or `shoppingMetric`.

#### Featured topic fields

`trendId`, `name`, `description`, `region`, `isPublished`, `growthPercentMonth`, `interestIds`, `relatedSearches`, `examplePins`, `timeSeries`, and `sourceUrl`.

Each `examplePins` item can contain `pinId`, `pinUrl`, `imageUrl`, `width`, `height`, `color`, and `verticalOffset`. Each `timeSeries` item can contain `date`, `count`, `normalizedCount`, `normalizedPredictedLowerBound`, and `normalizedPredictedUpperBound`.

#### Editorial story fields

`trendId`, `title`, `body`, `trendType`, `region`, `regions`, `interestIds`, `keywordsByRegion`, `startDate`, `endDate`, `isPublished`, `isReadyForTranslation`, `examplePins`, and `sourceUrl`.

#### Shopping category fields

`categoryId`, `name`, `level`, `parentCategoryId`, `childCategoryIds`, and `sourceUrl`.

#### Shopping metric fields

`categoryId`, `name`, `region`, `event`, `dailyValues`, `growthRates`, and `sourceUrl`.

Missing values are omitted. Pinterest-published zero counts, dates, and boolean `false` values are retained. Metric arrays and category names are copied from Pinterest and are not transformed into estimates.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | choice | `featured` | `featured`, `editorial`, `shoppingCategories`, or `shoppingMetrics`. |
| `region` | choice | `US` | Public Trends region: `US`, `GB+IE`, or `CA`. |
| `event` | choice | `OUTBOUND_CLICK` | Shopping event currently exposed by Pinterest. |
| `categoryNames` | array of text | — | Public shopping category names for metrics, such as `Sofas`. |
| `maxItems` | integer | `50` | Maximum records to return. |
| `days` | integer | `60` | Historical metric window, from 7 to 90 days. |
| `predictedDays` | integer | `0` | Optional Pinterest forecast window, from 0 to 28 days. |
| `cookies` / `cookiesJson` | array/string | — | Optional Cookie-Editor export; public Trends does not require it. |
| `proxyConfiguration` | object | — | Optional Apify proxy configuration. |

#### Example: featured topics

```json
{
  "mode": "featured",
  "region": "US",
  "maxItems": 25
}
```

#### Example: editorial stories

```json
{
  "mode": "editorial",
  "region": "GB+IE",
  "maxItems": 25
}
```

#### Example: shopping taxonomy

```json
{
  "mode": "shoppingCategories",
  "maxItems": 1000
}
```

#### Example: shopping history and forecast

```json
{
  "mode": "shoppingMetrics",
  "region": "US",
  "categoryNames": ["Sofas", "Wedding dress"],
  "days": 60,
  "predictedDays": 14,
  "maxItems": 50
}
```

### Use cases

- Discover emerging public Pinterest topics by region.
- Build editorial trend calendars from Pinterest story content.
- Map Pinterest's public product-category hierarchy.
- Compare public shopping interest over a selected historical window.
- Feed real Pinterest examples and time series into planning or reporting workflows.

### FAQ

#### Is this Pinterest Ads analytics?

No. It collects public Trends responses. Private business analytics, advertiser accounts, and exact private audience volumes are not promised.

#### Is `growthPercentMonth` a calculated estimate?

No. It is emitted only when Pinterest supplies the value for a featured topic.

#### Why are there fewer rows than `maxItems`?

The public Trends source may publish fewer topics, categories, or metric terms than the requested cap. The actor does not duplicate or invent rows.

#### Why did a forecast disappear?

Some region/category combinations publish history but no forecast. The actor returns real historical values and does not substitute a prediction.

#### Can I use another region?

Use the regions exposed by the actor input. The currently verified public choices are `US`, `GB+IE`, and `CA`.

#### Do category names need an exact match?

Names are matched against Pinterest's public category dictionary. If no requested name matches, the actor uses publicly returned categories when available.

#### Do I need cookies?

No. Public Trends data is collected without login cookies. Optional cookies can be supplied for a permitted session.

#### Can this actor return 10,000 rows?

The input supports a large cap and emits progressively, but verified public Trends modes currently contain far fewer categories/topics/terms. The actor returns the complete source-bounded result.

### Related Pinterest actors

- [Pinterest Scraper Pro](https://apify.com/crawlerbros/pinterest-scraper-pro) — Pins, profiles, boards, Ideas, search, and activity.
- [Pinterest Data Extractor](https://apify.com/crawlerbros/pinterest-data-extractor) — convenient multi-mode Pinterest data.
- [Pinterest Detailed Data Extractor](https://apify.com/crawlerbros/pinterest-detailed-data-extractor) — richer Pin, creator, board, product, SEO, and Story Pin fields.
- [Pinterest Media Downloader](https://apify.com/crawlerbros/pinterest-media-downloader) — save public Pin images and videos as files.
- [Pinterest Comments](https://apify.com/crawlerbros/pinterest-comments) — public Pin summaries, comments, replies, and activity.

# Actor input Schema

## `mode` (type: `string`):

Choose a public Pinterest Trends dataset.

## `region` (type: `string`):

Pinterest Trends region. `GB+IE` is Pinterest's combined Great Britain and Ireland region.

## `event` (type: `string`):

Pinterest event used for shopping category metrics.

## `categoryNames` (type: `array`):

Friendly Pinterest shopping category names for `shoppingMetrics`, such as `Sofas` or `Wedding dress`. Leave empty to use Pinterest's currently featured shopping categories.

## `days` (type: `integer`):

Number of historical days returned for shopping metrics.

## `predictedDays` (type: `integer`):

Number of future days Pinterest supplies in shopping metrics. If a region has no forecast, real historical values are returned instead.

## `maxItems` (type: `integer`):

Maximum trend/category records returned.

## `cookies` (type: `array`):

Optional Cookie Editor JSON export for account-relative trend context. Public Trends work without cookies; never share this secret publicly.

## `cookiesJson` (type: `string`):

Compatibility alias for pasting a Cookie Editor JSON export.

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

Optional Apify proxy settings. The actor tries a free AUTO proxy fallback and then direct public access.

## Actor input object example

```json
{
  "mode": "featured",
  "region": "US",
  "event": "OUTBOUND_CLICK",
  "categoryNames": [],
  "days": 60,
  "predictedDays": 28,
  "maxItems": 10
}
```

# Actor output Schema

## `trends` (type: `string`):

Dataset containing Pinterest Trends records.

# 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 = {
    "mode": "featured",
    "region": "US",
    "event": "OUTBOUND_CLICK",
    "categoryNames": [],
    "days": 60,
    "predictedDays": 0,
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/pinterest-trends").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 = {
    "mode": "featured",
    "region": "US",
    "event": "OUTBOUND_CLICK",
    "categoryNames": [],
    "days": 60,
    "predictedDays": 0,
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/pinterest-trends").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 '{
  "mode": "featured",
  "region": "US",
  "event": "OUTBOUND_CLICK",
  "categoryNames": [],
  "days": 60,
  "predictedDays": 0,
  "maxItems": 10
}' |
apify call crawlerbros/pinterest-trends --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/pinterest-trends"
        }
    }
}
```

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/xqZ1jb6gLqjTQCr6B/builds/fuFFMdeUp7wg1bX4d/openapi.json