The Pinterest SDK currently offers a Python library that supports campaign management and simplifies authentication and error handling. We will be adding functionality supporting organic Pins, shopping, analytics, and more over time. If you have specific feedback about the SDK or requests for additional functionality, please let us know.
- Python 3.7+
- a registered application (see below)
- an access token (see below)
In order to use the SDK, you must have registered an app on developers.pinterest.com
The steps to create an app can be found in the Set up app section of the docs on the Developers' Site.
Follow the instructions outlined on the Pinterest Developer Platform's Authentication Section to retreive an Access Token and Refresh Token
NOTE: For Python3, use python3 and pip3 instead.
NOTE: If the commands below result in a permissions error (which may happen if you are using a system-installed Python), use sudo.
To install pip, please refer to pip installation guide.
[Recommended] Create a virtual environment:
# Create environment
$ python -m venv .venv
# Activate environment
$ source .venv/bin/activate
Install SDK:
$ pip install pinterest-api-sdkAlternatively, you can check out the repository from GitHub. Once the package is downloaded and unzipped, install it:
$ python setup.py installYou can now use the SDK.
For use the client you need set basic variables for that you have two option setup environment variables (using a .env file or set in your OS) or create a config.json.
To configure the client using environment variables, you must create a .env file using .env.example as a template. For basic configuration and usage you need to set the following environment variables in the .env file:
PINTEREST_APP_ID=<app id>
PINTEREST_APP_SECRET=<app secret>
PINTEREST_REFRESH_ACCESS_TOKEN='<refresh token>'
**or**
PINTEREST_ACCESS_TOKEN='<access token>'
Once you have established the environment variables, the client will be instantiated for you automatically.
NOTE:
- Setting the
PINTEREST_ACCESS_TOKEN(which is valid for thirty days) will require the token value to be replaced when it expires. You will need to manually reinsantiate the client when the access_token expires. - Setting the
PINTEREST_REFRESH_ACCESS_TOKEN(which is valid for a year) will allow the SDK to regenerate the new access token whenever it is required.
To configure the client using config.json, you must create a config.json file using config.json.example as a template. For basic configuration and usage you need to set the following key in the config.json file:
{
"app_id": "<app id>",
"app_secret": "<app secret>",
"refresh_access_token": "<refresh token>"
}or
{
"access_token": "<access token>"
}Once you have established the keys, the client will be instantiated for you automatically.
NOTE:
- Setting up environment variables and config.json will result in the environment variables overriding the keys in config.json
- Setting the
access_token(which is valid for thirty days) will require the token value to be replaced when it expires. You will need to manually reinsantiate the client when the access_token expires. - Setting the
refresh_access_token(which is valid for a year) will allow the SDK to regenerate the new access token whenever it is required.
For more information visit the Authentication page.
Use Case:
- Initialize a Campaign object using an existing Ad Account ID and Campaign ID.
from pinterest.ads.campaigns import Campaign
campaign = Campaign(
ad_account_id="123456789",
campaign_id="987654321",
)Use Case:
- Create a new Ad
- Assign the Ad to an existing Ad Group
- Activate the Ad Group's parent Campaign
- Change the Campaign's budget
from pinterest.ads.campaigns import Campaign
from pinterest.ads.ad_groups import AdGroup
from pinterest.ads.ads import Ad
## Create a new Ad
new_ad = Ad.create(
ad_account_id="123456789",
ad_group_id="999999999",
creative_type="REGULAR",
pin_id="111111111",
name="SDK Example Ad",
status="ACTIVE",
is_pin_deleted=False,
is_removable=False,
)
## Initialize existing paused Campaign
campaign = Campaign(
ad_account_id="123456789",
campaign_id="987654321",
)
## Activate campaign
getattr(campaign, '_status')
>>> 'PAUSED'
campaign.activate()
>>> True
getattr(campaign, '_status')
>>> 'ACTIVE'
## Change campaign's lifetime budget
campaign.set_lifetime_budget(
new_spend_cap=250000000
)
>>> TrueNote: More examples of usage are located in the examples/ folder.
- Documentation is hosted on Developer Site.
See pinterest.utils.sdk_exceptions for a list of exceptions which may be thrown by the SDK.
If the SDK is not working as expected there might be an issue with the SDK or the Pinterest API server itself. In order to debug and identify the issue, the environment variables for debugging and logging can be enabled.
PINTEREST_DEBUG = True
PINTEREST_LOG_FILE = /tmp/log.txt
PINTEREST_LOGGER_FORMAT = '%(asctime)s %(levelname)s %(message)s'When PINTEREST_DEBUG is enabled, all the API raw requests and responses will be printed to the console and to the log file in the requested format.
For any issues or questions related to the SDK you are welcome to submit them through GitHub Issues using the following templates:
Note: There is no guaranteed SLA for responding to or resolving issues.
For any general issues related to the Pinterest API (or other Pinterest products) you can contact support at help.pinterest.com
Additional information on the Pinterest SDK can be found here. Additional information about campaigns and campaign management can be found in:
- The ads management section of the API documentation
- The campaign structure help article
- The create and edit a campaign help article
- The campaign objectives help article
- The campaign budgets help article
In order to access or use the client you can import the PinterestSDKClient and call the create_default_client() classmethod:
from pinterest.client import PinterestSDKClient
default_client = PinterestSDKClient.create_default_client()This will allow you to use the SDK Models without passing a PinterestSDKClient Object.
In order to create an object of the PinterestSDKClient you need to pass the access token inside the python code every time you wish to create a client or a combination of the refresh token, app id and app secret. This option is more useful if you wish to work with multiple accounts or clients at the same time.
from pinterest.client import PinterestSDKClient
# Access Token for Client 1
pinterest_access_token_1 = <access token 1>
# Refresh Token for Client 2
pinterest_refresh_token_2 = <refresh token 2>
pinterest_app_id_2 = <app id 2>
pinterest_app_secret_2 = <app secret 2>
client_1 = PinterestSDKClient.create_client_with_token(
access_token=pinterest_access_token_1,
)
client_2 = PinterestSDKClient.create_client_with_refresh_token(
refresh_token=pinterest_access_token_2,
app_id=pinterest_app_id_2,
app_secret=pinterest_app_secret_2,
)Pinterest Python SDK is licensed under the LICENSE file in the root directory of this source tree.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent