# Pinterest SDK for Python
[](https://github.com/pinterest/pinterest-python-sdk/actions/workflows/build.yml)
### Introduction
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](https://docs.google.com/forms/d/e/1FAIpQLSf2bA8gyC7kCp_Mgt1jCOvgp22K2EQWg3SEcMxyVRVzddYeMw/viewform?usp=sf_link).
## Pre-requisites
* Python 3.7+
* a registered application (see below)
* an access token (see below)
### Register an App
In order to use the SDK, you must have registered an app on [developers.pinterest.com](https://developers.pinterest.com)
The steps to create an app can be found in the [Set up app](https://developers.pinterest.com/docs/getting-started/set-up-app/) section of the [docs](https://developers.pinterest.com/docs/) on the [Developers' Site](https://developers.pinterest.com/).
### Get Access Token
Follow the instructions outlined on the Pinterest Developer Platform's [Authentication](https://developers.pinterest.com/docs/getting-started/authentication/) Section to retreive an **Access Token** and **Refresh Token**
## Install package
**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](https://pip.pypa.io/en/stable/installation/).
[_Recommended_] Create a virtual environment:
```bash
# Create environment
$ python -m venv .venv
# Activate environment
$ source .venv/bin/activate
```
Install SDK:
```bash
$ pip install pinterest-api-sdk
```
Alternatively, you can check out the repository from GitHub. Once the package is downloaded and unzipped, install it:
```bash
$ python setup.py install
```
You can now use the SDK.
## Getting Started
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.
### Setting up environment variables
To configure the client using environment variables, you must create a **.env** file using [.env.example](.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.
### Setting up config.json
To configure the client using config.json, you must create a **config.json** file using [config.json.example](config.json.example)
as a template. For basic configuration and usage you need to set the following key in the **config.json** file:
```json
{
"app_id": "<app id>",
"app_secret": "<app secret>",
"refresh_access_token": "<refresh token>"
}
```
**or**
```json
{
"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](https://developers.pinterest.com/docs/getting-started/authentication/#Refreshing%20an%20access%20token) page.
## Samples
### Initializing Models
**Use Case**:
* Initialize a Campaign object using an existing Ad Account ID and Campaign ID.
```python
from pinterest.ads.campaigns import Campaign
campaign = Campaign(
ad_account_id="123456789",
campaign_id="987654321",
)
```
### Examples of Campaign Management using SDK
**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
```python
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
)
>>> True
```
**Note**: More examples of usage are located in the ``examples/`` folder.
## Documentation
* Documentation is hosted on [Developer Site](https://developers.pinterest.com/docs/sdk/).
## Exceptions
See `pinterest.utils.sdk_exceptions` for a list of exceptions which may be thrown by the SDK.
## Debugging
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.
```bash
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.
## Issues
For any issues or questions related to the SDK you are welcome to submit them through [GitHub Issues](https://github.com/pinterest/pinterest-python-sdk/issues) using the following templates:
* [Bug Report Template](https://github.com/pinterest/pinterest-python-sdk/blob/main/.github/ISSUE_TEMPLATE/bug_report.md)
* [Feature Request Template](https://github.com/pinterest/pinterest-python-sdk/blob/main/.github/ISSUE_TEMPLATE/feature_request.md)
**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](https://help.pinterest.com)
## Other Resources
Additional information on the Pinterest SDK can be found [here](https://developers.pinterest.com/docs/sdk/intro/).
Additional information about campaigns and campaign management can be found in:
* The [ads management](https://developers.pinterest.com/docs/features/ads-management/) section of the API documentation
* The [campaign structure](https://help.pinterest.com/en/business/article/campaign-structure) help article
* The [create and edit a campaign](https://help.pinterest.com/en/business/article/set-up-your-campaign) help article
* The [campaign objectives](https://help.pinterest.com/en/business/article/campaign-objectives) help article
* The [campaign budgets](https://help.pinterest.com/en/business/article/set-up-campaign-budgets) help article
## Advanced Options
### Importing the PinterestSDKClient
In order to access or use the client you can import the *PinterestSDKClient* and call the `create_default_client()` classmethod:
```python
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.
### Creating custom Pinterest SDK Clients
In order to create an object of the [**PinterestSDKClient**](./pinterest/client/__init__.py) 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.
```python
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,
)
```
## License
Pinterest Python SDK is licensed under the [LICENSE](https://github.com/pinterest/pinterest-python-sdk/blob/main/LICENSE) file in the root directory of this source tree.
Raw data
{
"_id": null,
"home_page": "https://github.com/pinterest/pinterest-python-sdk",
"name": "pinterest-api-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Pinterest, Inc.",
"author_email": "sdk@pinterest.com",
"download_url": "https://files.pythonhosted.org/packages/f0/1a/9241f85b2eeaf866fe29c0efa6a47f48c3928426ba0757772fd0def08f23/pinterest_api_sdk-0.2.4.tar.gz",
"platform": null,
"description": "# Pinterest SDK for Python\n[](https://github.com/pinterest/pinterest-python-sdk/actions/workflows/build.yml)\n\n### Introduction\n\nThe 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](https://docs.google.com/forms/d/e/1FAIpQLSf2bA8gyC7kCp_Mgt1jCOvgp22K2EQWg3SEcMxyVRVzddYeMw/viewform?usp=sf_link).\n\n## Pre-requisites\n * Python 3.7+\n * a registered application (see below)\n * an access token (see below)\n\n### Register an App\n\nIn order to use the SDK, you must have registered an app on [developers.pinterest.com](https://developers.pinterest.com)\n\nThe steps to create an app can be found in the [Set up app](https://developers.pinterest.com/docs/getting-started/set-up-app/) section of the [docs](https://developers.pinterest.com/docs/) on the [Developers' Site](https://developers.pinterest.com/).\n\n### Get Access Token\n\nFollow the instructions outlined on the Pinterest Developer Platform's [Authentication](https://developers.pinterest.com/docs/getting-started/authentication/) Section to retreive an **Access Token** and **Refresh Token**\n\n## Install package\n\n**NOTE**: For Python3, use ``python3`` and ``pip3`` instead.\n\n**NOTE**: If the commands below result in a permissions error (which may happen if you are using a system-installed Python), use ``sudo``.\n\nTo install pip, please refer to [pip installation guide](https://pip.pypa.io/en/stable/installation/).\n\n[_Recommended_] Create a virtual environment:\n\n```bash\n# Create environment\n$ python -m venv .venv\n\n# Activate environment\n$ source .venv/bin/activate\n\n```\n\nInstall SDK:\n\n```bash\n$ pip install pinterest-api-sdk\n```\n\nAlternatively, you can check out the repository from GitHub. Once the package is downloaded and unzipped, install it:\n\n```bash\n$ python setup.py install\n```\n\nYou can now use the SDK.\n\n## Getting Started\n\nFor use the client you need set basic variables for that you have two option setup environment variables (using a \n.env file or set in your OS) or create a config.json.\n\n### Setting up environment variables\n\nTo configure the client using environment variables, you must create a **.env** file using [.env.example](.env.example)\nas a template. For basic configuration and usage you need to set the following environment variables in the **.env** file:\n\n```\nPINTEREST_APP_ID=<app id>\nPINTEREST_APP_SECRET=<app secret>\nPINTEREST_REFRESH_ACCESS_TOKEN='<refresh token>'\n\n**or**\n\nPINTEREST_ACCESS_TOKEN='<access token>'\n```\n\nOnce you have established the environment variables, the client will be instantiated for you automatically.\n\n**NOTE**: \n * 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. \n * 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. \n\n### Setting up config.json\n\nTo configure the client using config.json, you must create a **config.json** file using [config.json.example](config.json.example)\nas a template. For basic configuration and usage you need to set the following key in the **config.json** file:\n\n```json\n{\n \"app_id\": \"<app id>\",\n \"app_secret\": \"<app secret>\",\n \"refresh_access_token\": \"<refresh token>\"\n}\n```\n\n**or**\n\n```json\n{\n \"access_token\": \"<access token>\"\n}\n```\n\nOnce you have established the keys, the client will be instantiated for you automatically. \n\n**NOTE**: \n * Setting up environment variables and config.json will result in the environment variables overriding the keys in config.json\n * 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. \n * 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. \n\nFor more information visit the [Authentication](https://developers.pinterest.com/docs/getting-started/authentication/#Refreshing%20an%20access%20token) page.\n\n## Samples\n\n### Initializing Models\n\n**Use Case**: \n\n* Initialize a Campaign object using an existing Ad Account ID and Campaign ID.\n\n```python\nfrom pinterest.ads.campaigns import Campaign\n\ncampaign = Campaign(\n ad_account_id=\"123456789\",\n campaign_id=\"987654321\",\n)\n```\n\n### Examples of Campaign Management using SDK\n\n**Use Case**:\n\n* Create a new Ad\n* Assign the Ad to an existing Ad Group\n* Activate the Ad Group's parent Campaign\n* Change the Campaign's budget\n\n```python\nfrom pinterest.ads.campaigns import Campaign\nfrom pinterest.ads.ad_groups import AdGroup\nfrom pinterest.ads.ads import Ad\n\n## Create a new Ad\nnew_ad = Ad.create(\n ad_account_id=\"123456789\",\n ad_group_id=\"999999999\",\n creative_type=\"REGULAR\",\n pin_id=\"111111111\",\n name=\"SDK Example Ad\",\n status=\"ACTIVE\",\n is_pin_deleted=False,\n is_removable=False,\n)\n\n## Initialize existing paused Campaign\ncampaign = Campaign(\n ad_account_id=\"123456789\",\n campaign_id=\"987654321\",\n)\n\n## Activate campaign\ngetattr(campaign, '_status')\n>>> 'PAUSED'\n\ncampaign.activate()\n>>> True\n\ngetattr(campaign, '_status')\n>>> 'ACTIVE'\n\n## Change campaign's lifetime budget\ncampaign.set_lifetime_budget(\n new_spend_cap=250000000\n)\n>>> True\n```\n\n**Note**: More examples of usage are located in the ``examples/`` folder.\n\n## Documentation\n\n* Documentation is hosted on [Developer Site](https://developers.pinterest.com/docs/sdk/).\n\n\n## Exceptions\n\nSee `pinterest.utils.sdk_exceptions` for a list of exceptions which may be thrown by the SDK.\n\n## Debugging\n\nIf 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.\n\n```bash\nPINTEREST_DEBUG = True\nPINTEREST_LOG_FILE = /tmp/log.txt\nPINTEREST_LOGGER_FORMAT = '%(asctime)s %(levelname)s %(message)s'\n```\n\nWhen `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.\n\n## Issues\n\nFor any issues or questions related to the SDK you are welcome to submit them through [GitHub Issues](https://github.com/pinterest/pinterest-python-sdk/issues) using the following templates:\n * [Bug Report Template](https://github.com/pinterest/pinterest-python-sdk/blob/main/.github/ISSUE_TEMPLATE/bug_report.md)\n * [Feature Request Template](https://github.com/pinterest/pinterest-python-sdk/blob/main/.github/ISSUE_TEMPLATE/feature_request.md)\n\n**Note**: There is no guaranteed SLA for responding to or resolving issues.\n\nFor any general issues related to the Pinterest API (or other Pinterest products) you can contact support at [help.pinterest.com](https://help.pinterest.com)\n\n## Other Resources\n\nAdditional information on the Pinterest SDK can be found [here](https://developers.pinterest.com/docs/sdk/intro/).\nAdditional information about campaigns and campaign management can be found in:\n * The [ads management](https://developers.pinterest.com/docs/features/ads-management/) section of the API documentation\n * The [campaign structure](https://help.pinterest.com/en/business/article/campaign-structure) help article\n * The [create and edit a campaign](https://help.pinterest.com/en/business/article/set-up-your-campaign) help article\n * The [campaign objectives](https://help.pinterest.com/en/business/article/campaign-objectives) help article\n * The [campaign budgets](https://help.pinterest.com/en/business/article/set-up-campaign-budgets) help article\n\n## Advanced Options\n\n### Importing the PinterestSDKClient\n\nIn order to access or use the client you can import the *PinterestSDKClient* and call the `create_default_client()` classmethod:\n\n```python\nfrom pinterest.client import PinterestSDKClient\ndefault_client = PinterestSDKClient.create_default_client()\n```\n\nThis will allow you to use the SDK Models without passing a **PinterestSDKClient** Object.\n\n### Creating custom Pinterest SDK Clients\n\nIn order to create an object of the [**PinterestSDKClient**](./pinterest/client/__init__.py) 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.\n\n```python\nfrom pinterest.client import PinterestSDKClient\n\n# Access Token for Client 1\npinterest_access_token_1 = <access token 1>\n\n# Refresh Token for Client 2\npinterest_refresh_token_2 = <refresh token 2>\npinterest_app_id_2 = <app id 2>\npinterest_app_secret_2 = <app secret 2>\n\nclient_1 = PinterestSDKClient.create_client_with_token(\n access_token=pinterest_access_token_1,\n)\nclient_2 = PinterestSDKClient.create_client_with_refresh_token(\n refresh_token=pinterest_access_token_2,\n app_id=pinterest_app_id_2,\n app_secret=pinterest_app_secret_2,\n)\n```\n\n## License\n\nPinterest Python SDK is licensed under the [LICENSE](https://github.com/pinterest/pinterest-python-sdk/blob/main/LICENSE) file in the root directory of this source tree.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Pinterest API SDK",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/pinterest/pinterest-python-sdk"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b492e3f8387be6c3977a3c22f04bed8209269f4387a1e2aae570c606f2a2980f",
"md5": "8cf2278031570991629c53ea54b48c9d",
"sha256": "753beacf7c103d47cfd4ebb9fb34e3f8bd2de109ee997a00fafb993bbd8ef44d"
},
"downloads": -1,
"filename": "pinterest_api_sdk-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cf2278031570991629c53ea54b48c9d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 52893,
"upload_time": "2024-10-30T17:06:34",
"upload_time_iso_8601": "2024-10-30T17:06:34.909029Z",
"url": "https://files.pythonhosted.org/packages/b4/92/e3f8387be6c3977a3c22f04bed8209269f4387a1e2aae570c606f2a2980f/pinterest_api_sdk-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f01a9241f85b2eeaf866fe29c0efa6a47f48c3928426ba0757772fd0def08f23",
"md5": "5b4e3a800ef2efbde3e0fe134f169942",
"sha256": "da0d4b8303df58a36f4922f2b00149b1d7a59b86d55491ae7bde8c168f20d690"
},
"downloads": -1,
"filename": "pinterest_api_sdk-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "5b4e3a800ef2efbde3e0fe134f169942",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 41200,
"upload_time": "2024-10-30T17:06:36",
"upload_time_iso_8601": "2024-10-30T17:06:36.459527Z",
"url": "https://files.pythonhosted.org/packages/f0/1a/9241f85b2eeaf866fe29c0efa6a47f48c3928426ba0757772fd0def08f23/pinterest_api_sdk-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 17:06:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pinterest",
"github_project": "pinterest-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Pinterest-Generated-Client",
"specs": [
[
"==",
"0.1.9"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"1.26.12"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"0.20.0"
]
]
}
],
"lcname": "pinterest-api-sdk"
}
JSON
