Pinterest Keywords API
The Keywords API from Pinterest — 3 operation(s) for keywords.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Keywords API
description: This is the description of your API.
contact:
name: Pinterest, Inc.
url: https://developers.pinterest.com/
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Keywords
paths:
/ad_accounts/{ad_account_id}/keywords:
get:
summary: Get keywords
description: '<p>Get a list of keywords based on the filters provided. If no filter is provided, it will default to the ad_account_id filter, which means it will only return keywords that specifically have parent_id set to the ad_account_id. Note: Keywords can have ad_account_ids, campaign_ids, and ad_group_ids set as their parent_ids. Keywords created through Ads Manager will have their parent_id set to an ad_group_id, not ad_account_id.</p>
<p>For more information, see <a target="_blank" href="https://help.pinterest.com/en/business/article/keyword-targeting">Keyword targeting</a>.</p>
<p><b>Notes:</b></p> <ul style="list-style-type: square;"> <li>Advertisers and campaigns can only be assigned keywords with excluding (''_NEGATIVE'').</li> <li>All keyword match types are available for ad groups.</li> </ul> <p>For more information on match types, see <a target="_blank" href="/docs/ads/targeting/#Match%20type%20and%20targeting%20level">match type enums</a>.</p>
<p><b>Returns:</b></p> <ul style="list-style-type: square;"> <li><p>A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.</p></li> <li><p>An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:</p> <pre class="last literal-block"> { "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } } </pre></li> </ul>'
operationId: keywords/get
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_campaign_id'
- $ref: '#/components/parameters/query_ad_group_id'
- $ref: '#/components/parameters/query_match_types'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_bookmark'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Keyword'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Keywords
post:
summary: Create keywords
description: '<p>Create keywords for following entity types(advertiser, campaign, ad group or ad).</p> <p>For more information, see <a target="_blank" href="https://help.pinterest.com/en/business/article/keyword-targeting">Keyword targeting</a>.</p>
<p><b>Notes:</b></p> <ul style="list-style-type: square;"> <li>Advertisers and campaigns can only be assigned keywords with excluding (''_NEGATIVE'').</li> <li>All keyword match types are available for ad groups.</li> </ul> <p>For more information on match types, see <a target="_blank" href="/docs/ads/targeting/#Match%20type%20and%20targeting%20level">match type enums</a>.</p>
<p><b>Returns:</b></p> <ul style="list-style-type: square;"> <li><p>A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.</p></li> <li><p>An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:</p> <pre class="last literal-block"> { "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } } </pre></li> </ul>
<p><b>Rate limit</b>: <a href="/docs/redoc/#tag/Rate-Limits">WRITE</a>.</p>'
operationId: keywords/create
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KeywordsRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/KeywordsResponse'
description: Success
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Keywords
patch:
summary: Update keywords
description: <p>Update one or more keywords' bid and archived fields.</p> <p>Archiving a keyword effectively deletes it - keywords no longer receive metrics and no longer visible within the parent entity's keywords list.</p>
operationId: keywords/update
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/KeywordUpdateBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/KeywordsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Keywords
/ad_accounts/{ad_account_id}/keywords/metrics:
get:
summary: Get country's keyword metrics
description: 'See keyword metrics for a specified country, aggregated across all of Pinterest.
(Definitions are available from the "Get delivery metrics definitions"
<a href="/docs/api/v5/#operation/delivery_metrics/get">API endpoint</a>).'
operationId: country_keywords_metrics/get
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_country_code'
- $ref: '#/components/parameters/query_keywords'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/KeywordsMetricsArrayResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Keywords
/trends/keywords/{region}/top/{trend_type}:
get:
summary: List trending keywords
description: '<p>Get the top trending search keywords among the Pinterest user audience.</p>
<p>Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.</p>
<p>Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.</p>
<p>For an interactive way to explore this data, please visit <a href="https://trends.pinterest.com">trends.pinterest.com</a>.'
operationId: trending_keywords/list
security:
- pinterest_oauth2:
- user_accounts:read
x-ratelimit-category: trends_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_trend_region'
- $ref: '#/components/parameters/path_trend_type'
- $ref: '#/components/parameters/query_interest_list'
- $ref: '#/components/parameters/query_gender_list'
- $ref: '#/components/parameters/query_age_bucket_list'
- name: include_keywords
description: 'If set, filters the results to top trends which include at least one of the specified keywords.<br />
If unset, no keyword filtering logic is applied.'
example:
- recipes
- dessert
in: query
required: false
schema:
$ref: '#/components/schemas/KeywordList'
- $ref: '#/components/parameters/query_normalize_against_group'
- $ref: '#/components/parameters/query_trending_keyword_limit'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrendingKeywordsResponse'
description: Success
'400':
description: Invalid trending keywords request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid trending keywords request parameters
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Keywords
components:
parameters:
query_interest_list:
name: interests
description: 'If set, filters the results to trends associated with the specified interests.<br />
If unset, trends for all interests will be returned.<br />
The list of supported interests is:
- `animals` - Animals
- `architecture` - Architecture
- `art` - Art
- `beauty` - Beauty
- `childrens_fashion` - Children''s Fashion
- `design` - Design
- `diy_and_crafts` - DIY & Crafts
- `education` - Education
- `electronics` - Electronics
- `entertainment` - Entertainment
- `event_planning` - Event Planning
- `finance` - Finance
- `food_and_drinks` - Food & Drink
- `gardening` - Gardening
- `health` - Health
- `home_decor` - Home Decor
- `mens_fashion` - Men''s Fashion
- `parenting` - Parenting
- `quotes` - Quotes
- `sport` - Sports
- `travel` - Travel
- `vehicles` - Vehicles
- `wedding` - Wedding
- `womens_fashion` - Women''s Fashion'
example:
- beauty
- womens_fashion
in: query
required: false
schema:
$ref: '#/components/schemas/L1InterestList'
query_country_code:
name: country_code
description: Two letter country code (ISO 3166-1 alpha-2)
in: query
example: US
required: true
explode: true
schema:
type: string
style: form
query_keywords:
name: keywords
description: Comma-separated keywords
in: query
required: true
explode: false
schema:
items:
type: string
maxItems: 2000
minItems: 1
type: array
style: form
path_ad_account_id:
name: ad_account_id
description: Unique identifier of an ad account.
in: path
required: true
schema:
type: string
pattern: ^\d+$
maxLength: 18
query_campaign_id:
description: Campaign Id to use to filter the results.
in: query
name: campaign_id
required: false
schema:
type: string
pattern: ^\d+$
maxLength: 18
query_page_size:
name: page_size
description: Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information.
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 250
default: 25
query_bookmark:
name: bookmark
description: Cursor used to fetch the next page of items
in: query
required: false
schema:
type: string
query_normalize_against_group:
name: normalize_against_group
description: 'Governs how the resulting time series data will be normalized to a [0-100] scale.<br />
By default (`false`), the data will be normalized independently for each keyword. The peak search volume observation in *each* keyword''s time series will be represented by the value 100. This is ideal for analyzing when an individual keyword is expected to peak in interest.<br />
If set to `true`, the data will be normalized as a group. The peak search volume observation across *all* keywords in the response will be represented by the value 100, and all other values scaled accordingly. Use this option when you wish to compare relative search volume between multiple keywords.'
in: query
required: false
schema:
type: boolean
example: true
default: false
path_trend_region:
name: region
description: 'The geographic region of interest. Only top trends within the specified region will be returned.<br />
The `region` parameter is formatted as ISO 3166-2 country codes delimited by `+`, corresponding to the following geographic areas:
- `US` - United States
- `CA` - Canada
- `DE` - Germany
- `FR` - France
- `ES` - Spain
- `IT` - Italy
- `DE+AT+CH` - Germanic countries
- `GB+IE` - Great Britain & Ireland
- `IT+ES+PT+GR+MT` - Southern Europe
- `PL+RO+HU+SK+CZ` - Eastern Europe
- `SE+DK+FI+NO` - Nordic countries
- `NL+BE+LU` - Benelux
- `AR` - Argentina
- `BR` - Brazil
- `CO` - Colombia
- `MX` - Mexico
- `MX+AR+CO+CL` - Hispanic LatAm
- `AU+NZ` - Australasia'
in: path
required: true
schema:
$ref: '#/components/schemas/TrendsSupportedRegion'
path_trend_type:
name: trend_type
description: 'The methodology used to rank how trendy a keyword is.
- `growing` trends have high upward growth in search volume over the last quarter
- `monthly` trends have high search volume in the last month
- `yearly` trends have high search volume in the last year
- `seasonal` trends have high upward growth in search volume over the last month and exhibit a seasonal recurring pattern (typically annual)'
in: path
required: true
schema:
$ref: '#/components/schemas/TrendType'
query_ad_group_id:
description: Ad group Id.
in: query
name: ad_group_id
example: '123123123'
required: false
schema:
type: string
pattern: ^\d+$
maxLength: 18
query_match_types:
explode: true
description: Keyword <a target="_blank" href="/docs/ads/targeting/#Match%20type%20and%20targeting%20level">match type</a>
in: query
name: match_types
required: false
schema:
type: array
items:
$ref: '#/components/schemas/MatchType'
minItems: 1
maxItems: 5
query_trending_keyword_limit:
name: limit
description: The maximum number of trending keywords that will be returned. Keywords are returned in trend-ranked order, so a `limit` of 50 will return the top 50 trends.
example: 25
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 50
query_age_bucket_list:
name: ages
description: 'If set, filters the results to trends among users in the specified age range(s).<br />
If unset, trends among all age groups will be returned.'
example:
- 35-44
- 50-54
in: query
required: false
schema:
$ref: '#/components/schemas/AgeBucketList'
query_gender_list:
name: genders
description: 'If set, filters the results to trends among users who identify with the specified gender(s).<br />
If unset, trends among all genders will be returned.<br />
The `unknown` group includes users with unspecified or customized gender profile settings.'
example:
- female
- unknown
in: query
required: false
schema:
$ref: '#/components/schemas/GenderList'
schemas:
GenderList:
title: Gender
type: array
example:
- female
- unknown
items:
type: string
enum:
- female
- male
- unknown
KeywordUpdate:
title: KeywordUpdate
type: object
properties:
id:
type: string
description: Keyword ID.
example: '2886364308355'
pattern: ^\d+$
title: id
archived:
type: boolean
description: Is keyword archived?
example: false
title: archived
bid:
type: integer
minimum: 1
description: Keyword custom bid in microcurrency - null if inherited from parent ad group.
example: 200000
nullable: true
title: bid
required:
- id
KeywordsRequest:
type: object
properties:
keywords:
type: array
description: Keyword JSON array. Each array element has 3 fields
items:
$ref: '#/components/schemas/KeywordsCommon'
parent_id:
description: Keyword parent entity ID (advertiser, campaign, ad group).
example: '383791336903426391'
pattern: ^((AG)|C)?\d+$
title: parent_id
type: string
required:
- keywords
- parent_id
KeywordsCommon:
type: object
properties:
bid:
type: integer
description: Keyword custom bid in microcurrency - null if inherited from parent ad group.
example: 200000
nullable: true
match_type:
$ref: '#/components/schemas/MatchTypeResponse'
value:
type: string
description: Keyword value (120 chars max).
required:
- match_type
- value
AgeBucketList:
title: AgeRange
type: array
example:
- 35-44
- 50-54
items:
type: string
enum:
- 18-24
- 25-34
- 35-44
- 45-49
- 50-54
- 55-64
- 65+
Error:
title: Error
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message
KeywordsResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/KeywordError'
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
KeywordMetrics:
description: Keyword metrics JSON
title: KeywordMetrics
type: object
properties:
avg_cpc_in_micro_currency:
example: 100000
title: avg_cpc_in_micro_currency
description: Average cost per click
type: number
keyword_query_volume:
example: 5M+
title: keyword_query_volume
description: Keyword's search frequency. This value is based on keyword frequency in pepsi client response
type: string
L1InterestList:
title: Interest
type: array
example:
- beauty
- womens_fashion
items:
type: string
enum:
- animals
- architecture
- art
- beauty
- childrens_fashion
- design
- diy_and_crafts
- education
- electronics
- entertainment
- event_planning
- finance
- food_and_drinks
- gardening
- health
- home_decor
- mens_fashion
- parenting
- quotes
- sport
- travel
- vehicles
- wedding
- womens_fashion
KeywordsMetricsArrayResponse:
type: object
title: KeywordMetricsArrayResponse
properties:
data:
type: array
items:
$ref: '#/components/schemas/KeywordMetricsResponse'
Paginated:
type: object
properties:
items:
type: array
items:
type: object
bookmark:
type: string
nullable: true
required:
- items
KeywordList:
title: Keywords
type: array
example:
- recipes
- dessert
items:
type: string
minLength: 1
maxLength: 100
minItems: 1
maxItems: 50
TrendingKeywordsResponse:
type: object
properties:
trends:
description: 'The top trending keywords for the specified trend type in the requested region.<br />
Results are ordered, with the first element in the array representing the #1 top trend.'
type: array
items:
type: object
properties:
keyword:
description: The keyword that is trending.
example: couples halloween costumes
type: string
minLength: 1
pct_growth_wow:
description: 'The week-over-week percent change in search volume for this keyword.<br />
For example, a value of "50" would represent a 50% increase in searches in the last seven days compared to the week prior.<br />
**Note**: growth rates are rounded, with a maximum of +/- 10000% change. A value of 10001 indicates that this keyword experienced > 10000% week-over-week growth.'
example: 50
type: integer
pct_growth_mom:
description: 'The month-over-month percent change in search volume for this keyword.<br />
For example, a value of "400" would represent a 400% increase in searches in the last 30 days compared to the month prior.<br />
**Note**: growth rates are rounded, with a maximum of +/- 10000% change. A value of 10001 indicates that this keyword experienced > 10000% month-over-month growth.'
example: 400
type: integer
pct_growth_yoy:
description: 'The year-over-year percent change in search volume for this keyword.<br />
For example, a value of "-5" would represent a 5% decrease in searches in the last 365 days compared to the month prior.<br />
**Note**: growth rates are rounded, with a maximum of +/- 10000% change. A value of 10001 indicates that this keyword experienced > 10000% year-over-year growth.'
example: -5
type: integer
time_series:
description: 'A sequence of weekly observations of the relative search volume for this keyword over the past year.<br />
These values are normalized to a [0-100] range, and can be used to visualize the history of user interest in this keyword.
By default, normalization is applied independently to the time series of each keyword, but the `normalize_against_group` query parameter can be used in cases where you wish to compare relative volume between keywords.<br />
**Note**: The date of each observation is in ISO-8601 format and represents the *end* of the week. For example, a value of `2023-10-31` would include searches that happened between `2023-10-25` and `2023-10-31`.'
example:
'2023-10-10': 31
'2023-10-17': 54
'2023-10-24': 77
'2023-10-31': 100
type: object
properties:
date:
type: string
format: date
additionalProperties:
type: integer
MatchTypeResponse:
type: string
description: Keyword match type
nullable: true
example: BROAD
enum:
- BROAD
- PHRASE
- EXACT
- EXACT_NEGATIVE
- PHRASE_NEGATIVE
- null
MatchType:
type: string
description: Keyword match type
example: BROAD
enum:
- BROAD
- PHRASE
- EXACT
- EXACT_NEGATIVE
- PHRASE_NEGATIVE
TrendType:
title: TrendType
type: string
example: monthly
enum:
- growing
- monthly
- yearly
- seasonal
Keyword:
type: object
allOf:
- $ref: '#/components/schemas/KeywordsCommon'
- type: object
properties:
archived:
type: boolean
example: false
id:
description: Keyword ID .
example: '383791336903426391'
pattern: ^\d+$
title: id
type: string
parent_id:
description: Keyword parent entity ID (advertiser, campaign, ad group).
example: '383791336903426391'
pattern: ^\d+$
title: parent_id
type: string
parent_type:
type: string
description: Parent entity type
example: campaign
type:
type: string
description: Always keyword
example: keyword
KeywordUpdateBody:
type: object
properties:
keywords:
description: 'Keywords to update. Object array. Each object has 3 possible fields:<br>1. "id": (required) keyword ID<br>2. "archived": boolean. Should keyword be archived?<br>3. "bid": number<br>For example: [{"id":"2886610576653", "archived": false, "bid": 20000}, {"id":"2886610576654", "archived": true, "bid": 20000}, ...]'
type: array
items:
$ref: '#/components/schemas/KeywordUpdate'
title: keywords
required:
- keywords
KeywordMetricsResponse:
title: KeywordMetricsResponse
type: object
properties:
keyword:
description: Keyword name, e.g., "keyword":"fashion outfits"
example: animals
title: keyword
type: string
metrics:
$ref: '#/components/schemas/KeywordMetrics'
KeywordError:
type: object
properties:
data:
$ref: '#/components/schemas/Keyword'
error_messages:
type: array
items:
type: string
TrendsSupportedRegion:
title: Region
type: string
example: GB+IE
enum:
- US
- CA
- DE
- FR
- ES
- IT
- DE+AT+CH
- GB+IE
- IT+ES+PT+GR+MT
- PL+RO+HU+SK+CZ
- SE+DK+FI+NO
- NL+BE+LU
- AR
- BR
- CO
- MX
- MX+AR+CO+CL
- AU+NZ
securitySchemes:
pinterest_oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.pinterest.com/oauth/
tokenUrl: https://api.pinterest.com/v5/oauth/token
scopes:
ads:read: See all of your advertising data, including ads, ad groups, campaigns etc.
ads:write: Create, update, or delete ads, ad groups, campaigns etc.
billing:read: See all of your billing data, billing profile, etc.
billing:write: Create, update, or delete billing data, billing profiles, etc.
biz_access:read: See business access data
biz_access:write: Create, update, or delete business access data
boards:read: See your public boards, including group boards you join
boards:read_secret: See your secret boards
boards:write: Create, update, or delete your public boards
boards:write_secret: Create, update, or delete your secret boards
catalogs:read: See all of your catalogs data
catalogs:write: Create, update, or delete your catalogs data
pins:read: See your public Pins
pins:read_secret: See your secret Pins
pins:write: Create, update, or delete your public Pins
pins:write_secret: Create, update, or delete your secret Pins
user_accounts:read: See your user accounts and followers
user_accounts:write: Update your user accounts and followers
conversion_token:
type: http
scheme: bearer
description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com).
basic:
type: http
scheme: basic
x-tagGroups:
- name: Pin and Boards
tags:
- pins
- boards
- media
- aggregated_comments
- aggregated_pin_data
- user_account
- name: Campaign Management
tags:
- ad_accounts
- campaigns
- ad_groups
- ads
- product_group_promotions
- bulk
- name: Targeting
tags:
- audiences
- customer_lists
- keywords
- targeting_template
- audience_insights
- audience_sharing
- name: Ad Formats
tags:
- lead_forms
- lead_ads
- leads_export
- name: Billing
tags:
- billing
- order_lines
- terms_of_service
- name: Business Access
tags:
- business_access_assets
- business_access_invite
- business_access_relationships
- name: Conversions
tags:
- conversion_events
- conversion_tags
- name: Others
tags:
- integrations
- oauth
- resources
- search
- terms
- name: Shopping
tags:
- catalogs
- name: Deprecated
tags:
- product_groups