dempe/pinterest-java

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

• GET /v1/pins/<pin_id>
• GET /v1/me/pins/<pin_id>
• GET /v1/boards/<board_name>/pins/
• GET /v1/me/boards/
• DELETE /v1/pins/<pin_id>
• POST /v1/pins/ (still missing multi-part form uploading and base64 encoded image URLs).
• POST /v1/boards/
• PATCH /v1/pins/<pin_id>
• PATCH /v1/boards/<board_name>
• DELETE /v1/boards/<board_name>
• GET /v1/me/
• GET /v1/me/boards/suggested/
• GET /v1/me/boards/
• GET /v1/me/pins/
• GET /v1/me/search/boards/
• GET /v1/me/search/pins/
• GET /v1/me/followers/
• GET /v1/me/following/boards/
• GET /v1/me/following/interests/
• GET /v1/me/following/users/
• POST /v1/me/following/boards/
• POST /v1/me/following/users/
• DELETE /v1/me/following/boards/<board>/
• DELETE /v1/me/following/users/<user>/

Contributing

See CONTRIBUTING.md.