Use Media Planner with the Pinterest API
Pinterest's Media Planner helps you streamline media planning by testing various campaign configurations before creating your actual campaign.
Media Planner is available for campaigns with brand awareness, consideration, web conversion, and catalog sales objectives.
As part of objective simplification, the and are being deprecated, to be replaced by and objectives respectively. See the details and timeline for objective simplification.
WEB_CONVERSIONCATALOG_SALESLEADSALESAs part of objective simplification, the and are being deprecated, to be replaced by and objectives respectively. See the details and timeline for objective simplification.
WEB_CONVERSIONCATALOG_SALESLEADSALESWith Media Planner, you can create future campaign media plans using the same campaign configuration you would use in Ads Manager. You can see estimates and forecasts of campaigns' predicted performance and discover areas of opportunity.
See this guide for using the API to generate and review campaign projections to determine the right budget and media needed to accomplish your goals.
Generate estimates
Descriptions of relevant request parameters
These parameters mirror the structure of campaign and ad group creation endpoints, and you can use them to simulate a campaign with child ad groups.
As you start to generate delivery estimates, you can adjust your targeting, budget, or bid and then generate new estimates to see how they change.
Some parameters are optional for the API call to succeed but, as noted in the tables, other parameters may depend on them being enabled.
For media planner purposes, disregard endpoint parameters not listed here.
| Parameter | Description |
|---|---|
objective_typestring Required | Campaign objective. Set to one of the following currently supported objectives:
|
daily_spend_capinteger Either this parameter or lifetime_spend_cap | Set the amount in microcurrency. Example: For $10 USD, set the value as 10000000Do not use this parameter if you are using lifetime_spend_cap |
lifetime_spend_capinteger Either this parameter or daily_spend_cap | Set the amount in microcurrency. Example: For $10 USD, set the value as 10000000Do not use this parameter if you are using daily_spend_cap |
start_datestring Required | Set the campaign start date for the time period you want to include in the estimate. Format: YYYY-MM-DD |
end_datestring Required | Set the campaign end date for the time period you want to include in the estimate. Format: YYYY-MM-DD |
ad_groupsobject Required | Container for child ad groups of the campaign for which you want to generate an estimate. You can include a maximum of 10 ad groups with this current release. |
ad_groups.creative_typesarray of strings Optional | Set the creative types that you want to include in the estimate: REGULARVIDEOSHOPPINGCAROUSELMAX_VIDEOCOLLECTIONIDEA |
ad_groups.creative_typesarray of strings Optional | Set the creative types that you want to include in the estimate: REGULARVIDEOSHOPPINGCAROUSELMAX_VIDEOCOLLECTIONIDEA |
ad_groups.keywordsarray of objects Optional | To generate estimates for campaigns that are keyword-targeted, set a list of search keywords that you want your ads to target. See following two child parameters. |
ad_groups.keywords.match_typeobject Requried for keywords | Indicate how strictly the keywords should be matched to user searches or content. BROAD
PHRASE
EXACT
EXACT_NEGATIVE
PHRASE_NEGATIVE
|
ad_groups.keywords.valuestring Required for keywords | Set the keyword that you want your ads to target. Maximum 250 characters. To include multiple keywords in your estimate, use multiple keyword |
targeting_speccobject Optional | Define the audience in the child ad group of the campaign for which you want to generate an estimate. |
Example request payload for objective type AWARENESS with lifetime budget
See the response for this request.
Example request payload for objective type CONSIDERATION with lifetime budget
See the response for this request.
Descriptions of response fields
| Field | Description |
|---|---|
curvesarray of objects | Each object in the array represents a reporting event and shows how the estimated outcome for that event changes as your bid changes. |
curves.pointsarray of objects | Array of data points, each corresponding to a specific bid value and the estimated minimum and maximum outcome (such as impressions or clicks) at that bid. |
curves.points.budgetinteger | Budget value in cents associated with the estimate pointmin_ymax_yydouble_y |
curves.points.budget.min_yinteger | Minimum estimated value for the reporting event at this bid/budget. |
curves.points.budget.max_yinteger | Maximum estimated value for the reporting event at this bid/budget. |
curves.points.budget.yinteger | Expected (average or median) value for the reporting event at this bid/budget. |
curves.points.budget.double_yinteger | Floating-point version of y |
curves.estimation_typestring | Method or approach Pinterest used to generate the delivery estimate: IMPRESSIONCLICKCONVERSIONWEEKLY_FREQUENCYWEEKLY_REACHLIFETIME_FREQUENCYLIFETIME_REACHCPMCPCCPA |
max_potential_spendinteger | Estimated maximum potential spend. |
derived_metricsobject | Container for all estimated metrics for an ad campaign. |
derived_metrics.cpcfloat | Estimated cost per click in microdollars (µUSD). |
derived_metrics.cpc_upperfloat | High-end cost-per-click estimate in microdollars (µUSD). |
derived_metrics.cpc_lowerfloat | Low-end cost-per-click estimate in microdollars (µUSD). |
derived_metrics.weekly_clickfloat | Estimated weekly clicks. |
derived_metrics.weekly_click_upperfloat | High-end estimate of weekly clicks. |
derived_metrics.weekly_click_lowerfloat | Low-end estimate of weekly clicks. |
derived_metrics.cpmfloat | Estimated cost per thousand impressions in microdollars (µUSD). |
derived_metrics.cpm_upperfloat | High-end cost per thousand impressions in microdollars (µUSD). |
derived_metrics.cpm_lowerfloat | Low-end cost per thousand impressions in microdollars (µUSD). |
derived_metrics.weekly_frequencyfloat | Estimated number of times a unique user will see your ad in a week. |
derived_metrics.weekly_frequency_upperfloat | High-end estimate of number of times a unique user will see your ad in a week. |
derived_metrics.weekly_frequency_lowerfloat | Low-end estimate of number of times a unique user will see your ad in a week. |
derived_metrics.weekly_reachfloat | Estimated number of unique users who will see your ad at least once during a one-week period. |
derived_metrics.weekly_reach_upperfloat | Upper estimate of number of unique users who will see your ad at least once during a one-week period. |
derived_metrics.weekly_reach_lowerfloat | Low-end estimate of number of unique users who will see your ad at least once during a one-week period. |
derived_metrics.weekly_impressionfloat | Estimated number of times your ad will be shown (served) to users during a one-week period—whether they are the same or different users. |
derived_metrics.weekly_impression_upperfloat | Upper estimate of number of times your ad will be shown (served) to users during a one-week period—whether they are the same or different users. |
derived_metrics.weekly_impression_lowerfloat | Low-end estimate of number of times your ad will be shown (served) to users during a one-week period—whether they are the same or different users. |
derived_metrics.lifetime_reachfloat | Estimated number of unique users who will see your ad at least once over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_reach_upperfloat | Upper estimate of number of unique users who will see your ad at least once over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_reach_lowerfloat | Low-end estimate of number of unique users who will see your ad at least once over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_impressionfloat | Estimated number of times your ad will be shown (served) to users over the lifetime of the campaign—whether they are the same or different users. Only applicable to AWARENESS |
derived_metrics.lifetime_impression_upperfloat | Upper estimate of number of times your ad will be shown (served) to users over the lifetime of the campaign—whether they are the same or different users. Only applicable to AWARENESS |
derived_metrics.lifetime_impression_lowerfloat | Low-end estimate of number of times your ad will be shown (served) to users over the lifetime of the campaign—whether they are the same or different users. Only applicable to AWARENESS |
derived_metrics.lifetime_frequencyfloat | Estimated number of times a unique user will see your ad over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_frequency_upperfloat | Upper estimate of number of times a unique user will see your ad over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_frequency_lowerfloat | Low-end estimate of number of times a unique user will see your ad over the lifetime of the campaign. Only applicable to AWARENESS |
Example response for objective type AWARENESS with lifetime budget
See also an example of UI output for this use case.
Example response for objective type CONSIDERATION with lifetime budget
See also an example of UI output for this use case.
Example UI output of estimates
This screenshot shows an estimate for the objective type with a lifetime budget.
AWARENESS
This screenshot shows an estimate the objective type with a lifetime budget.
CONSIDERATION
Was this page helpful?