Package: pinterest-api-sdk
Pinterest SDK for PythonIntroductionThe 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, pleaselet us know.Pre-requisitesPython 3.7+a registered application (see below)an access token (see below)Register an AppIn order to use the SDK, you must have registered an app ondevelopers.pinterest.comThe steps to create an app can be found in theSet up appsection of thedocson theDevelopers' Site.Get Access TokenFollow the instructions outlined on the Pinterest Developer Platform'sAuthenticationSection to retreive anAccess TokenandRefresh TokenInstall packageNOTE: For Python3, usepython3andpip3instead.NOTE: If the commands below result in a permissions error (which may happen if you are using a system-installed Python), usesudo.To install pip, please refer topip installation guide.[Recommended] Create a virtual environment:# Create environment$python-mvenv.venv# Activate environment$source.venv/bin/activateInstall SDK:$pipinstallpinterest-api-sdkAlternatively, you can check out the repository from GitHub. Once the package is downloaded and unzipped, install it:$pythonsetup.pyinstallYou can now use the SDK.Getting StartedFor 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.Setting up environment variablesTo configure the client using environment variables, you must create a.envfile using.env.exampleas a template. For basic configuration and usage you need to set the following environment variables in the.envfile: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 thePINTEREST_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 theaccess_tokenexpires.Setting thePINTEREST_REFRESH_ACCESS_TOKEN(which is valid for a year) will allow the SDK to regenerate the new access token whenever it is required.Setting up config.jsonTo configure the client using config.json, you must create aconfig.jsonfile usingconfig.json.exampleas a template. For basic configuration and usage you need to set the following key in theconfig.jsonfile:{"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.jsonSetting theaccess_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 theaccess_tokenexpires.Setting therefresh_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 theAuthenticationpage.SamplesInitializing ModelsUse Case:Initialize a Campaign object using an existing Ad Account ID and Campaign ID.frompinterest.ads.campaignsimportCampaigncampaign=Campaign(ad_account_id="123456789",campaign_id="987654321",)Examples of Campaign Management using SDKUse Case:Create a new AdAssign the Ad to an existing Ad GroupActivate the Ad Group's parent CampaignChange the Campaign's budgetfrompinterest.ads.campaignsimportCampaignfrompinterest.ads.ad_groupsimportAdGroupfrompinterest.ads.adsimportAd## Create a new Adnew_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 Campaigncampaign=Campaign(ad_account_id="123456789",campaign_id="987654321",)## Activate campaigngetattr(campaign,'_status')>>>'PAUSED'campaign.activate()>>>Truegetattr(campaign,'_status')>>>'ACTIVE'## Change campaign's lifetime budgetcampaign.set_lifetime_budget(new_spend_cap=250000000)>>>TrueNote: More examples of usage are located in theexamples/folder.DocumentationDocumentation is hosted onDeveloper Site.ExceptionsSeepinterest.utils.sdk_exceptionsfor a list of exceptions which may be thrown by the SDK.DebuggingIf 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=TruePINTEREST_LOG_FILE=/tmp/log.txtPINTEREST_LOGGER_FORMAT='%(asctime)s %(levelname)s %(message)s'WhenPINTEREST_DEBUGis enabled, all the API raw requests and responses will be printed to the console and to the log file in the requested format.IssuesFor any issues or questions related to the SDK you are welcome to submit them throughGitHub Issuesusing the following templates:Bug Report TemplateFeature Request TemplateNote: 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 athelp.pinterest.comOther ResourcesAdditional information on the Pinterest SDK can be foundhere.
Additional information about campaigns and campaign management can be found in:Theads managementsection of the API documentationThecampaign structurehelp articleThecreate and edit a campaignhelp articleThecampaign objectiveshelp articleThecampaign budgetshelp articleAdvanced OptionsImporting the PinterestSDKClientIn order to access or use the client you can import thePinterestSDKClientand call thecreate_default_client()classmethod:frompinterest.clientimportPinterestSDKClientdefault_client=PinterestSDKClient.create_default_client()This will allow you to use the SDK Models without passing aPinterestSDKClientObject.Creating custom Pinterest SDK ClientsIn order to create an object of thePinterestSDKClientyou 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.frompinterest.clientimportPinterestSDKClient# Access Token for Client 1pinterest_access_token_1=<accesstoken1># Refresh Token for Client 2pinterest_refresh_token_2=<refreshtoken2>pinterest_app_id_2=<appid2>pinterest_app_secret_2=<appsecret2>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,)LicensePinterest Python SDK is licensed under theLICENSEfile in the root directory of this source tree.