EDIT 2020-03-29

This project is no longer actively maintained. I no longer have access to the Pinterest API. Feel free to take over development. I'm happy to answer any questions.

Happy hacking! Dempe

Description

Public Java/Kotlin SDK for Pinterest's new API.

Maven

<dependency>
    <groupId>com.chrisdempewolf</groupId>
    <artifactId>pinterest-sdk</artifactId>
    <version>4.1.0</version>
</dependency>

Or check Maven Central for a list of published artifacts.

Versioning

This project uses Semantic Versioning; MAJOR.MINOR.PATCH: X.Y.Z, such that X, Y, and Z are natural numbers where an update to X indicates a breaking (API) change, to Y indicates new, backwards-compatible features were added, and to Z indicates a bug was patched. Please see the Semantic Versioning website for more information.

Examples

Quick Note on Terminology

The word "Board" on Pinterest can be somewhat confusing - does it refer to <username/board_name> or just the latter, board_name part?

Here, when I say "board", I mean the <username/board_name> combination. I will say "board name" when I'm specifically refering to the name of the Board without the prepended username portion. I believe this is the approach Pinterest takes as well.

Initialization

Construct a new Pinterest SDK:

 final Pinterest pinterest = new Pinterest("<INSERT_YOUR_PINTEREST_ACCESS_TOKEN>");

Pin Methods

Fetching

Available Fields

.withCounts()
.withLink()
.withMetadata()
.withNote()
.withURL()
.withColor()
.withAttribution()
.withCreatedAt()

Usage

To get a Pin (with all fields) via a Pin ID:
- Example Pin ID: 525091637782793357; from URL: https://www.pinterest.com/pin/525091637782793357/

final PinResponse pin = pinterest.getPin("<PIN_ID>", new PinFields().withAll());

To get a Pin with only default fields (url, note, link, id) set:

final PinResponse pin = pinterest.getPin("<PIN_ID>");

To get a Pin with only link, created_at, and color set:

final PinResponse pin = pinterest.getPin("<PIN_ID>", new PinFields().withLink().withCreatedAt().withColor());

To get your own Pins (with all fields):

final Pins pins = pinterest.getMyPins(new PinFields().withAll());
pins.forEach(pin -> {System.out.println(pin);});

To get your own Pins (with any arbitrary field):

final Pins pins = pinterest.getMyPins(new PinFields().with("some_field"));
pins.forEach(pin -> {System.out.println(pin);});

To get all the Pins from a board with default fields:
- Example Board: cdatarank/欲しいもの; from URL: https://www.pinterest.com/cdatarank/欲しいもの/

final Pins pins = pinterest.getPinsFromBoard("<BOARD>");

To get all the Pins from a board with all fields:

final Pins pins = pinterest.getPinsFromBoard("<BOARD>", new PinFields().withAll());

Paging through Pin responses:

Pins pins = pinterest.getPinsFromBoard(BOARD);
while (pins.getNextPage() != null) {
    pins = pinterest.getNextPageOfPins(pins.getNextPage());
}

Updating

List of parameters:

Field	Required	Description
Pin ID	Yes	ID of Pin to update
Board	No	Board to post to
Note	No	Pin's "note" or "description"
Link	No	The URL to the the Pin

(See the Pinterest API documentation for more info).

final ResponseMessageAndStatusCode response = pinterest.patchPin("<PIN_ID>", 
                                                                "(optional)<BOARD>", 
                                                                "(optional)<NOTE>", 
                                                                "(optional)<LINK>");

To update a Pin's note:

final ResponseMessageAndStatusCode response = pinterest.patchPin("<PIN_ID>", null, "<NOTE>", null);

Posting

Currently, only POSTing via an image URL is supported. Multi-part form and base64 encoded image uploading will be added soon.

final ResponseMessageAndStatusCode response = pinterest.postPin("<BOARD>", "<NOTE>", "<IMG_URL>", "<LINK>");

Deleting

All you need is the Pin ID and an access token with write access to the Pin question. This method returns true if the Pin was successfully deleted; false otherwise. This true/false return pattern was adopted from RestFB.

final boolean deleted = pinterest.deletePin("<PIN_ID>");

Board Methods

Fetching

Available Fields

.withCounts()
.withCreatedAt()
.withDescription()
.withID()
.withImage()
.withName()
.withURL()

Usage

To get info about a particular Board with default fields:
Example Board: cdatarank/欲しいもの from URL: https://www.pinterest.com/cdatarank/欲しいもの/

final BoardResponse boardResponse = pinterest.getBoard("<BOARD>");
final Board board = boardResponse.getBoard();

To get info about a particular Board with an arbitrary field:

final BoardResponse boardResponse = pinterest.getBoard("<BOARD>", new BoardFields().with("foo"));
final Board board = boardResponse.getBoard();

To get info about a particular Board with all fields:

final BoardResponse boardResponse = pinterest.getBoard("<BOARD>", new BoardFields().withAll());
final Board board = boardResponse.getBoard();

Paging through Board responses:

Boards boards = pinterest.getMyBoards(new BoardFields().withAll());
while (boards.getNextPage() != null) {
    boards = pinterest.getNextPageOfBoards(boards.getNextPage());
}

Posting

Note: this method requires a Board name not a Board (see terminology section for more information).

final String boardName = "foo";
final ResponseMessageAndStatusCode response = pinterest.postBoard(boardName, "<BOARD_DESCRIPTION>");

Updating

final name = "newname"; // the _actual_ name of the board
final board = "<CURRENT_BOARD>";
final ResponseMessageAndStatusCode response = pinterest.patchBoard(board, name, description);

Deleting

final Boolean deleted = pinterest.deleteBoard("<BOARD>");
assertEquals(true, deleted);

User Methods

Note: user methods only work with the authenticated user (i.e., the owner of the access token you used to initialize the Pinterest SDK).

Fetching

Available Fields

.withBio()
.withCounts()
.withCretedAt()
.withFirstName()
.withImage()
.withLastName()
.withURL()
.withUsername()

Usage

USER

To get a user with the default fields:

final User user = pinterest.getUser();

To get a user with all fields:

final User user = pinterest.getUser(new UserFields().withAll());

To get a user with an arbitrary field:

final User user = pinterest.getUser(new UserFields().with("foo"));

To get a user with first name and last name:

final User user = pinterest.getUser(new UserFields().withFirstName().withLastName());

USER'S SUGGESTED BOARDS

To get the user's list of suggested Boards (with default fields):

final Boards boards = pinterest.getUserSuggestedBoards();

This method takes an optional BoardFields parameter (see the Board section above for more info).

final Boards boards = pinterest.getUserSuggestedBoards(new BoardFields().withName());

USER'S BOARDS

Retrieving all of a user's Boards works the same way:

final Boards boards = pinterest.getUserBoards(new BoardFields().withName());

Paging works the same for all Boards responses, so:

Boards boards = pinterest.getUserBoards(new BoardFields().withName());
while (boards.getNextPage() != null) {
    boards = pinterest.getNextPageOfBoards(boards.getNextPage());
}

USER'S PINS

Similarly, to retrieve a user's Pins:

final Pins pins = pinterest.getUserPins();

Or...

final Pins pins = pinterest.getUserPins(new PinFields().withCreatedAt());

SEARCH USER'S PINS

With default fields:

final Pins pins = pinterest.searchUserPins("cucumber");

With select fields:

final Pins pins = pinterest.searchUserPins("cucumber", new PinFields().withNote());

Paging works the same for all Pins responses, so:

Pins pins = pinterest.searchUserPins("cucumber", new PinFields().withNote());
while (pins.getNextPage() != null) {
    pins = pinterest.getNextPageOfPins(pins.getNextPage());
}

USER'S FOLLOWERS

With default fields:

final Users users = pinterest.getFollowers();

With select fields:

final Users users = pinterest.getFollowers(new UserFields().withCounts().withBio());

Paginating:

Users users = pinterest.getFollowers(new UserFields().withCounts().withBio());
while (users.getNextPage() != null) {
    users = pinterest.getNextPageOfUsers(users.getNextPage());
}

FOLLOWERS' BOARDS

With default fields:

final Boards boards = pinterest.getFollowersBoards();;

With select fields:

final Boards boards = pinterest.getFollowersBoards(new BoardFields().withName().withURL());

Paginating:

Boards boards = pinterest.getFollowersBoards(new BoardFields().withName().withURL());
while (boards.getNextPage() != null) {
    boards = pinterest.getNextPageOfBoards(boards.getNextPage());
}

FOLLOWING

With default fields:

final Users users = pinterest.getFollowing();

With select fields:

final Users users = pinterest.getFollowing(new UserFields().withCounts().withBio());

Paginating:

Users users = pinterest.getFollowing(new UserFields().withCounts().withBio());
while (users.getNextPage() != null) {
    users = pinterest.getNextPageOfUsers(users.getNextPage());
}

SEARCH USER'S BOARDS

With default fields:

final Boards boards = pinterest.searchUserBoards("cucumber");

With select fields:

final Boards boards = pinterest.searchUserBoards("cucumber", new BoardFields().withName());

Paging works the same for all Boards responses, so:

Boards boards = pinterest.searchUserBoards("cucumber", new BoardFields().withName());
while (boards.getNextPage() != null) {
    boards = pinterest.getNextPageOfBoards(boards.getNextPage());
}

Posting

FOLLOW BOARD

final ResponseMessageAndStatusCode resp = pinterest.followBoard("cdatarank/my-board");
assertEquals(200L, resp.getStatusCode());

FOLLOW USER

final ResponseMessageAndStatusCode resp = pinterest.followUser("cdatarank");
if (resp.getStatusCode() != 200) {
    System.err.println(resp.getMessage());
}

Deleting

UNFOLLOW BOARD

final boolean unfollowed = pinterest.unfollowBoard("cdatarank/my-board");

UNFOLLOW USER

final boolean unfollowed = pinterest.unfollowUser("cdatarank");

Coverage

Contributing

See CONTRIBUTING.md.

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

dempe / pinterest-java

Programming Languages

Labels

Projects that are alternatives of or similar to pinterest-java

EDIT 2020-03-29

Description

Maven

Versioning

Examples

Quick Note on Terminology

Initialization

Pin Methods

Fetching

Available Fields

Usage

Updating

Posting

Deleting

Board Methods

Fetching

Available Fields

Usage

Posting

Updating

Deleting

User Methods

Fetching

Available Fields

Usage

USER

USER'S SUGGESTED BOARDS

USER'S BOARDS

USER'S PINS

SEARCH USER'S PINS

USER'S FOLLOWERS

FOLLOWERS' BOARDS

FOLLOWING

SEARCH USER'S BOARDS

Posting

FOLLOW BOARD

FOLLOW USER

Deleting

UNFOLLOW BOARD

UNFOLLOW USER

Coverage

Contributing