Python code that makes it easy to get started with the Pinterest API.
-
Follow the directions at the top level of this repo for configuring your application ID and application secret.
-
From the top of this repo, change your working directory to this directory:
$ cd python
-
Set up your virtualenv.
$ python3 -m venv ./venv/api $ . ./venv/api/bin/activate $ pip install -r requirements.txt
-
Set up the shell environment.
$ . ../common/scripts/api_env
-
Run the simplest sample script.
$ ./scripts/get_access_token.py
Note: In every new shell, you'll need to activate the virtualenv and configure the environment.
$ cd python # from the top of this repository
$ . ./venv/api/bin/activate
$ . ../common/scripts/api_env
After running the Quick Start, you should be able to run any of the use cases in the scripts directory. Scripts that accept arguments use argparse
, which ensures that the -h
or --help
argument shows usage documentation. In addition, the code for each script has a comment that documents its intended purpose.
Here is a list of common arguments that work with all scripts:
-a <name>
or--access-token <name>
: The name of the access token for the script. This name is helpful with the-w
or--write
option toget_access_token.py
, which will store the access token in a file that can be used by other scripts.-l <level>
or--log-level <level>
: The level of logging verbosity for the script.0
is only critical output.1
generates a bit more output.2
is the default, and prints a lot of useful information for developers learning the API.3
is maximal verbosity.
Below you will find a description of each script along with an example of its help documentation.
Quick start code that demonstrates the OAuth 2.0 flow and tests the authentication by reading the user profile using the /v5/user_account
endpoint. Running this script with the -w
parameter (./scripts/get_access_token.py -w
) stores the access token in ../common/oauth_tokens/access_token.json
for future use. Use -w
parameter in combination with the -a
(access token name) parameter to store separate access tokens for different purposes. When requesting an access token without specifying scopes, the script will default to user_accounts:read
pins:read
and boards:read
. To see a complete list of scopes, refer to the Enums in ./src/oauth_scope.py
. You can also run ./scripts/get_access_token.py -s help
to see the scopes.
$ ./scripts/get_access_token.py --help
usage: get_access_token.py [-h] [-w] [-ct] [-s SCOPES] [-c] [-a ACCESS_TOKEN]
[-l LOG_LEVEL]
Get Pinterest OAuth token
options:
-h, --help show this help message and exit
-w, --write write access token to file
-ct, --cleartext print the token in clear text
-s SCOPES, --scopes SCOPES
comma separated list of scopes or 'help'
-c, --client-credentials
access the application user account
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Use --scopes help
to get a list of all possible scopes:
$ ./scripts/get_access_token.py --scopes help
Using application ID and secret from PINTEREST_APP_ID and PINTEREST_APP_SECRET.
Valid OAuth 2.0 scopes for Pinterest API version v5:
ads:read Read access to advertising data
ads:write Write access to advertising data
boards:read Read access to boards
boards:read_secret Read access to secret boards
boards:write Write access to create, update, or delete boards
boards:write_secret Write access to create, update, or delete secret boards
catalogs:read Read access to catalog information
catalogs:write Create or update catalog contents
pins:read Read access to Pins
pins:read_secret Read access to secret Pins
pins:write Write access to create, update, or delete Pins
pins:write_secret Write access to create, update, or delete secret Pins
user_accounts:read Read access to user accounts
For more information, see:
https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/#pinterest-scopes
Demonstrates how to refresh an access token. This script is just meant to be self-contained example. Use refresh_access_token if you need to refresh and to store an existing access token.
$ ./scripts/refresh_example.py --help
usage: refresh_example.py [-h] [-a ACCESS_TOKEN] [-l LOG_LEVEL]
Refresh Pinterest OAuth token
options:
-h, --help show this help message and exit
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Refreshes an access token stored by using ./scripts/get_access_token.py
with the -w
(write) argument.
$ ./scripts/refresh_access_token.py --help
usage: refresh_access_token.py [-h] [-ct] [-c] [-a ACCESS_TOKEN]
[-l LOG_LEVEL]
Refresh Pinterest OAuth token
options:
-h, --help show this help message and exit
-ct, --cleartext print the token in clear text
-c, --continuous continuous refresh token
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Retrieves the information for a specific board with the /v5/pins/{pin_id}
endpoint.
$ ./scripts/get_pin.py --help
usage: get_pin.py [-h] -p PIN_ID [-a ACCESS_TOKEN] [-l LOG_LEVEL]
Get a Pin
options:
-h, --help show this help message and exit
-p PIN_ID, --pin-id PIN_ID
pin identifier
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Retrieves the information for a specific board with the /v5/boards/{board_id}
endpoint.
$ ./scripts/get_board.py --help
usage: get_board.py [-h] -b BOARD_ID [--pins] [-a ACCESS_TOKEN] [-l LOG_LEVEL]
Get a Board
options:
-h, --help show this help message and exit
-b BOARD_ID, --board-id BOARD_ID
board identifier
--pins Get the Pins for the Board
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Retrieves all of the pins for a user using several endpoints.
$ ./scripts/get_user_pins.py --help
usage: get_user_pins.py [-h] [-ps PAGE_SIZE] [-a ACCESS_TOKEN] [-l LOG_LEVEL]
Get A User's Pins
options:
-h, --help show this help message and exit
-ps PAGE_SIZE, --page-size PAGE_SIZE
Pins per page
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Retrieves all of the boards for a user with the /v5/boards
endpoint, using the paging mechanism of the API.
$ ./scripts/get_user_boards.py --help
usage: get_user_boards.py [-h] [-ps PAGE_SIZE] [--include-empty]
[--no-include-empty] [--include-archived]
[--no-include-archived] [-a ACCESS_TOKEN]
[-l LOG_LEVEL]
Get A User's Boards
options:
-h, --help show this help message and exit
-ps PAGE_SIZE, --page-size PAGE_SIZE
Boards per page
--include-empty Include empty boards?
--no-include-empty
--include-archived Include archived boards?
--no-include-archived
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Demonstration of how to use the POST /v5/pins
endpoint to create a pin. Copying a pin can be useful functionality for API developers, but does not represent typical user behavior on Pinterest. Note that copy_pin.py
can create a video pin from an image pin by suppling the -m/--media
argument, which is either a Pinterest media identifier (a number) or the path name of a file that contains a video.
$ ./scripts/copy_pin.py --help
usage: copy_pin.py [-h] -p PIN_ID [-m MEDIA] -b BOARD_ID [-s SECTION]
[-a ACCESS_TOKEN] [-l LOG_LEVEL]
Copy a Pin
options:
-h, --help show this help message and exit
-p PIN_ID, --pin-id PIN_ID
source pin identifier
-m MEDIA, --media MEDIA
media path or id
-b BOARD_ID, --board-id BOARD_ID
destination board identifier
-s SECTION, --section SECTION
destination board section
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Demonstration of how to use the POST /v5/boards
endpoint to create a board. Also uses the POST /boards/{board_id}/sections
endpoint to create board sections. This script accepts source and target access tokens, so that a board can be copied from one account to another. It also provides an --all
option that copies all of the boards and pins from a source account into a target account. Copying one or multiple boards can be useful functionality for API developers, but does not represent typical user behavior on Pinterest.
$ ./scripts/copy_board.py --help
usage: copy_board.py [-h] [-b BOARD_ID] [-n NAME] [-s SOURCE_ACCESS_TOKEN]
[-t TARGET_ACCESS_TOKEN] [--all] [--dry-run]
[-a ACCESS_TOKEN] [-l LOG_LEVEL]
Copy one Board or all Boards
options:
-h, --help show this help message and exit
-b BOARD_ID, --board-id BOARD_ID
source board identifier
-n NAME, --name NAME target board name
-s SOURCE_ACCESS_TOKEN, --source-access-token SOURCE_ACCESS_TOKEN
source access token name
-t TARGET_ACCESS_TOKEN, --target-access-token TARGET_ACCESS_TOKEN
target access token name
--all copy all boards from source to target
--dry-run print changes but do not execute them
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Reads information about advertiser accounts, campaigns, ad groups, and ads. By default, this script runs in interactive mode to get input on how to descend the advertising object hierarchy. Use the --all-ads
argument to print all of the information associated with an access token.
$ ./scripts/get_ads.py --help
usage: get_ads.py [-h] [--all-ads] [-a ACCESS_TOKEN] [-l LOG_LEVEL]
Advertisers API Example
options:
-h, --help show this help message and exit
--all-ads print all ads information
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Demonstrates how to use the API to retrieve analytics metrics with synchronous requests.
$ ./scripts/get_analytics.py --help
usage: get_analytics.py [-h]
[-o {user,pin,ad_account_user,ad_account,campaign,ad_group,ad}]
[--pin-id PIN_ID] [--ad-account-id AD_ACCOUNT_ID]
[--campaign-id CAMPAIGN_ID]
[--ad-group-id AD_GROUP_ID] [--ad-id AD_ID]
[-a ACCESS_TOKEN] [-l LOG_LEVEL]
Get Analytics
options:
-h, --help show this help message and exit
-o {user,pin,ad_account_user,ad_account,campaign,ad_group,ad}, --analytics-object {user,pin,ad_account_user,ad_account,campaign,ad_group,ad}
kind of object used to fetch analytics
--pin-id PIN_ID Get analytics for this pin identifier.
--ad-account-id AD_ACCOUNT_ID
Get analytics for this ad account identifier.
--campaign-id CAMPAIGN_ID
Get analytics for this campaign identifier.
--ad-group-id AD_GROUP_ID
Get analytics for this ad group identifier.
--ad-id AD_ID Get analytics for this ad identifier.
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Demonstrates how to use the API to generate an asynchronous delivery metrics report using the create and get endpoints.
$ ./scripts/analytics_api_example.py --help
usage: analytics_api_example.py [-h] [-a ACCESS_TOKEN] [-l LOG_LEVEL]
Analytics API Example
options:
-h, --help show this help message and exit
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
Shows how to use the Terms endpoint to view related and suggested terms for ads targeting.
$ ./scripts/get_terms.py --help
usage: get_terms.py [-h] [-r] [-s] [-n LIMIT] [-a ACCESS_TOKEN] [-l LOG_LEVEL]
terms
Get Related or Suggested Terms
positional arguments:
terms comma-separated list of terms
options:
-h, --help show this help message and exit
-r, --related get related terms
-s, --suggested get suggested terms
-n LIMIT, --limit LIMIT
limit for suggested terms
-a ACCESS_TOKEN, --access-token ACCESS_TOKEN
access token name
-l LOG_LEVEL, --log-level LOG_LEVEL
level of logging verbosity
The quickstart uses the Python Requests library, which supports the HTTPS_PROXY
environment variable. For example, to forward Pinterest API requests through a local proxy at port 8080, run this command in the shell before running any of the above commands:
$ export HTTPS_PROXY="http://localhost:8080"
Unit tests are in ./tests/src/
and integrations tests are in ./tests/scripts/
. To run the tests, run the following commands in your virtualenv:
$ . ./venv/api/bin/activate # always run in a vitualenv
$ pip install -r dev-requirements.txt # only needed with a new virtualenv or when requirements change
$ make tests
The Makefile
shows how to run the tests with the pytest
command. More information is in the pytest documentation.
If you want to use PyCharm as the IDE for this code, there are two ways to configure the environment.
-
Set up the environment and run PyCharm at the command line. This is the best way to keep your Pinterest API credentials secure. For example, on MacOS:
$ . ../common/scripts/api_env $ /Applications/PyCharm\ CE.app/Contents/MacOS/pycharm
-
Enter the environment variables into the PyCharm environment. Note that PyCharm will store your credentials in its workspace configuration, which is less secure than keeping the credentials in a file that you control.
-
Print the critical variables.
$ . ../common/scripts/api_env $ env | grep PINTEREST_APP PINTEREST_APP_ID=<number> PINTEREST_APP_SECRET=<string>
-
Start PyCharm.
-
Select Run/Edit Configurations...
-
Select Templates/Python
-
Enter the four list variables above in the Environment variables.
-
The code conventions are set by the standard configurations of the black, isort, and flake8 linters for python. Run these linters with make lint
.