Pinterest Autocomplete Idea & Trend Research

Mine Pinterest's search suggestions for idea and trend research — and get every suggestion classified by category, aesthetic style, season and occasion.

Pinterest is a planning surface, not a search engine. People arrive with a project in mind: a coffee bar for the kitchen, a boho wedding, a cottagecore bedroom. Its typeahead is therefore one of the best free signals of what people intend to make and buy — if you can get at it.

---

Key features

1. It actually returns data

Pinterest's typeahead endpoint answers a plain request with HTTP 403. Verified repeatedly: a bare request to the resource URL is rejected every single time, and adding a user agent, a Referer or X-Requested-With individually does not help — all still 403.

Only the complete browser-accurate header set gets through, including Pinterest's own X-Pinterest-AppState and X-Pinterest-PWS-Handler. This Actor sends that set, and additionally bootstraps a real session against Pinterest's /ideas/ page first to pick up the csrftoken and _pinterest_sess cookies, forwarding the CSRF token on every subsequent call.

The test suite includes a permanent regression guard asserting that a headerless request still receives 403 while the configured client returns results, so this cannot silently rot.

2. Idea-category classification built for Pinterest

Every suggestion is assigned an ideaCategory from eighteen Pinterest-native categories:

home_decor · diy_craft · recipe_food · wedding · outfit_fashion · nail_art · hair · makeup_beauty · tattoo · garden_outdoor · party_event · travel · fitness_health · quotes_inspiration · art_design · photography · kids_parenting · organization · general

matchedCategories lists every category a phrase touches, since "diy coffee bar wedding decor" legitimately belongs to several.

3. Aesthetic, season and occasion extraction

Pinterest searches carry style and timing signals that generic keyword tools throw away:

• aestheticTokens / hasAestheticStyle — boho, minimalist, cottagecore, y2k, dark academia, coastal, rustic, vintage and more
• seasonTokens / isSeasonal — spring, summer, autumn/fall, winter
• occasionTokens / isOccasionBased — christmas, halloween, wedding, baby shower, graduation
• isIdeaFormatQuery — whether the searcher asked for "ideas", "inspiration", "inspo" or a tutorial

Seeds are also expanded with Pinterest-native modifier families — inspiration, aesthetics and occasions — rather than web-search modifiers that find little here.

4. Three result scopes

resultScopes selects what Pinterest suggests: pins (idea and search phrases), boards (board suggestions) or users (accounts). Query several at once; deduplication is per scope so the comparison stays intact.

---

Input

Field	Type	Default	Description
seedKeywords (required)	array	—	Topics to expand
resultScopes	array	["pins"]	pins, boards and/or users
expansionModes	array	inspiration	Modifier families to apply
modifierPlacement	string	suffix	suffix, prefix or both
resultsPerQuery	integer	10	Suggestions requested per query
maxSuggestionsPerQuery	integer	0	Cap kept per query; 0 = keep all
deduplicateSuggestions	boolean	true	Deduplicate within each scope
emitRunSummary	boolean	true	Append the summary row
concurrentRequests	integer	3	Queries sent in parallel
requestDelayMs	integer	200	Pause after each request
proxyConfig	object	disabled	Optional Apify Proxy settings

Example input

{
  "seedKeywords": ["coffee bar"],
  "resultScopes": ["pins"],
  "expansionModes": ["inspiration", "aesthetics"],
  "modifierPlacement": "suffix",
  "requestDelayMs": 250
}

---

Output

Suggestion record

{
  "recordType": "suggestion",
  "seedKeyword": "coffee bar",
  "expandedQuery": "coffee bar ideas",
  "modifier": "ideas",
  "modifierType": "inspiration",
  "modifierPlacement": "suffix",
  "suggestion": "coffee bar ideas kitchen counter",
  "suggestionRank": 5,
  "resultScope": "pins",
  "ideaCategory": "home_decor",
  "matchedCategories": ["home_decor"],
  "aestheticTokens": [],
  "hasAestheticStyle": false,
  "seasonTokens": [],
  "isSeasonal": false,
  "occasionTokens": [],
  "isOccasionBased": false,
  "isIdeaFormatQuery": true,
  "wordCount": 5,
  "characterLength": 32,
  "isLongTail": true,
  "isQuestion": false,
  "containsSeedKeyword": true,
  "searchIntent": "informational",
  "collectedAt": "2026-08-11T11:44:52.310000+00:00"
}

Summary record

{
  "recordType": "summary",
  "seedKeywords": ["coffee bar"],
  "queriesIssued": 9,
  "suggestionsCollected": 108,
  "uniqueSuggestions": 84,
  "duplicatesRemoved": 24,
  "failedQueryCount": 0,
  "failedQueries": [],
  "searchIntentBreakdown": { "informational": 51, "unclassified": 33 },
  "modifierTypeBreakdown": { "inspiration": 72, "seed": 12 },
  "mostRepeatedSuggestions": [
    { "suggestion": "coffee bar ideas", "appearances": 4 }
  ],
  "scopesQueried": ["pins"],
  "ideaCategoryBreakdown": { "general": 9, "home_decor": 2, "party_event": 1 },
  "finishedAt": "2026-08-11T11:45:06.884000+00:00"
}

---

Common use cases

• Content and pin planning — ideaCategory plus isIdeaFormatQuery shows which idea formats people want in your niche.
• Seasonal campaign timing — isSeasonal and occasionTokens reveal how far ahead demand builds for each occasion.
• Aesthetic trend tracking — run the same seeds monthly and watch aestheticTokens shift as styles rise and fade.
• Ecommerce product research — Pinterest demand often leads purchase demand, especially in decor, craft and wedding categories.
• Blog and SEO topics — long-tail suggestions map directly onto article and pin titles.
• Competitor board discovery — the boards and users scopes surface accounts already serving a topic.

---

Notes and limits

• Autocomplete reflects what people type, not how many do. It is a demand-shape signal, not a volume metric.
• Pinterest rate limits by IP and is more sensitive to bursts than the search engines. concurrentRequests defaults to 3 and requestDelayMs to 200 for that reason; enable proxyConfig for larger runs.
• If Pinterest changes its header requirements the endpoint may begin returning 403 again. The run fails loudly with a clear message rather than silently producing an empty dataset.
• Category and aesthetic classification is keyword-pattern based on English vocabulary. Phrases with no explicit cue are returned as general, which is honest rather than guessed.
• The users and boards scopes return account and board names, so the idea-classification fields are less meaningful there than for pins.
• No login is performed and no private or personalised data is accessed; only Pinterest's public typeahead is queried.

---

Local development

pip install -r requirements.txt
python -m tests.test_core      # 45 checks: header regression guard, parsing, categories, live endpoint
apify run