API documentation

All endpoints are under https://api.keywordtopin.com/v1 and return JSON.

Authentication

Create a key in the portal and send it in the x-api-key header. A key works only while its owner has an active plan.

Prefer to send real requests? The API explorer lists every endpoint below with full schemas and lets you run them against your own key. The playground is the quicker option: it runs a request as your signed-in account.

curl "https://api.keywordtopin.com/v1/explore/interests" \
  -H "x-api-key: sk_your_key"

Plans

Basic includes Explore, competition analysis and competitor analysis. Pro includes everything in Basic plus keyword research (search, volume, analytics and trending). Calling an endpoint your plan does not include returns 403.

Explore (Basic and Pro)

GET /v1/explore/interests

The interest categories Pinterest groups topics under. Pass values from this list as the interests parameter below.

{ "success": true, "data": { "interests": [ /* as returned by Pinterest */ ] } }

GET /v1/explore/trending

Trending keywords. Optional parameters: region (e.g. US), interests, query (narrow by a term), limit (default 20, maximum 100) and page.

{
  "success": true,
  "data": { "results": [{ "keyword": "boho wedding", "volume": 1630 }] }
}

Competition analysis (Basic and Pro)

GET /v1/analysis/competition

The top pins for a keyword with save and share counts, to show how crowded it is. Parameters: term (required), limit (maximum 20), sort and bookmark (continue from a previous response). Each pin is returned as Pinterest provides it, with save_count and share_count added. A term with no pins returns an empty pins list.

{
  "success": true,
  "data": { "pins": [ /* pins */ ], "limit": 6, "bookmark": "…", "total": 6 }
}

Competitor analysis (Basic and Pro)

Parameters for all three endpoints: username (required, a leading @ is accepted), limit (maximum 50) and bookmark when a response gives one. An unknown account returns 404.

GET /v1/analysis/competitors

The account's profile with its first pins and boards.

{ "success": true, "data": { "user": { /* profile */ }, "pins": [ ], "boards": [ ] } }

GET /v1/analysis/competitors/boards

The account's boards.

GET /v1/analysis/competitors/pins

The account's pins.

Keyword research (Pro)

GET /v1/keywords/search

Parameters: query, type (basic, analytics or trending; default basic), limit (default 20, maximum 100) and sort (ASC or DESC; default DESC). query is required for basic and analytics.

type=basic

{
  "success": true,
  "data": {
    "keyword": "boho wedding",
    "volume": 1630,
    "results": [{ "keyword": "boho wedding hair down", "volume": 1630 }]
  }
}

type=analytics

The main keyword's volume plus related keywords. A volume of 0 means none was reported.

{
  "success": true,
  "data": {
    "keyword": "boho wedding",
    "volume": 1630,
    "relatedKeywords": [{ "keyword": "boho wedding decor", "volume": 880 }]
  }
}

type=trending

query is optional and narrows the list.

{
  "success": true,
  "data": { "results": [{ "keyword": "boho wedding", "volume": 1630 }] }
}

GET /v1/keywords/volume

?keyword=… returns the live Pinterest volume for one keyword. blocked is true when Pinterest refused the lookup; in that case volume is not a real zero.

{
  "success": true,
  "data": { "keyword": "boho wedding", "volume": 1630, "blocked": false }
}

Rate limits

Per key: 600 keyword searches a minute, and 60 a minute for each of volume lookups, Explore requests and analysis requests. There is no monthly quota. Exceeding a limit returns 429.

Errors