README
(Unofficial) "Pin It" Pinterest API
This is an unofficial interface to Pinterest's pin-it api. You can pin anything you want to your own boards programatically using nodejs!
Note: Pinterest could change their api at any time causing this library to break. You've been warned.
Installation
From the command line
npm install pin-it-node
In package.json
{
dependencies: {
"pin-it-node": "~0.2.0"
}
}
Usage
To Pin:
var PinIt = require('pin-it-node');
var pinIt = new PinIt({
username: 'MyUsername',
userurl: 'kengoldfarb', //A user's page shows up on Pinterest as: "http://www.pinterest.com/userurl/"
password: 'MySuperSecretPassword'
});
pinIt.createPin({
boardId: '294704438055170924',
url: 'http://www.kengoldfarb.com', // The click back link from pinterest
description: 'Wow. Such dev.',
media: 'http://www.kengoldfarb.com/images/pin-it.png' // The actual image that will be pinned
}, function(err, pinObj) {
if(err) {
// Uh-oh...handle the error
console.log(err);
return;
}
console.log('Success! New pin has been added to the board.');
console.log(pinObj);
})
To Remove Pin:
var PinIt = require('pin-it-node');
var pinIt = new PinIt({
username: 'MyUsername',
userurl: 'kengoldfarb',
password: 'MySuperSecretPassword'
});
pinIt.deletePin({
pinId: '123'
}, function(err, pinObj) {
if(err) {
// Uh-oh...handle the error
console.log(err);
return;
}
console.log('Success! Pin has been removed from the board.');
console.log(pinObj);
})
To Create Board:
var PinIt = require('pin-it-node');
var pinIt = new PinIt({
username: 'MyUsername',
userurl: 'kengoldfarb',
password: 'MySuperSecretPassword'
});
pinIt.createBoard({
boardName: 'Ken\'s Awesome Board',
description: 'an #awesome board of epic proportions',
boardCategory: 'geek', //Limited options, check README for list
boardPrivacy: 'public' //refer to privacy section if you plan to make a board secret.
}, function(err, pinObj) {
if(err) {
// Uh-oh...handle the error
console.log(err);
return;
}
console.log('Success! The board has been created.');
console.log(pinObj);
})
To Delete Board:
var PinIt = require('pin-it-node');
var pinIt = new PinIt({
username: 'MyUsername',
userurl: 'kengoldfarb',
password: 'MySuperSecretPassword'
});
pinIt.deleteBoard({
boardId: '294704438055170924',
}, function(err, pinObj) {
if(err) {
// Uh-oh...handle the error
console.log(err);
return;
}
console.log('Success! The board has been deleted.');
console.log(pinObj);
})
Getting the boardurl and userurl
If you look at any the url of any board, you will be looking at: http://www.pinterest.com/userurl/boardurl/
.
The formatting of a boardurl is generally in lowercase with removed puncuation and "-" substituted for whitespace.
Getting the pinId
(for pin removal)
It's easy to grab from the html of the board. Look for the href in the .pinImageWrapper
class. If you are viewing a pin, the pinId is the number in the url.
Board Category
There is a limted number of categories that Pinterest lets you choose from: "animals", "architecture", "art", "cars_motorcycles", "celebrities", "design", "diy_crafts", "education", "film", "music_books", "food_drink", "gardening", "geek", "hair_beauty", "health_fitness", "history", "holidays_events", "home_decor", "humor", "illustrations_posters", "kids", "mens_fashion", "outdoors", "photography", "products", "quotes", "science_nature", "sports", "tattoos", "technology", "travel", "weddings", "womens_fashion", and "other"
Board Privacy
Boards can be 'public' or 'secret'. Insert one of those two as a string when creating or updating a board. SECRET BOARDS CANNOT BE UPDATED OR DELETED via pin-it-node. This functionality is in the works, but it is not implemented yet.
Board ID's
The boardId is REQUIRED to pin. In the future, ideally pin-it-node will accept a board url as an alternative.
You can get the boardId by going to pinterest and inspecting the GET request to https://www.pinterest.com/resource/BoardResource/get/. You should see it listed in the "module_path" parameter of the request in the format: resource=BoardResource(board_id=1234567)
Advanced Options
'request' module options
This module makes all it's http(s) requests using request. You can optionally pass in a set of options for this module when making a request.
For example...
var PinIt = require('pin-it-node');
var pinIt = new PinIt({
username: 'MyUsername',
userurl: 'kengoldfarb',
password: 'MySuperSecretPassword',
requestDefaults: {
proxy:'http://127.0.0.1:8888',
strictSSL: false
}
});
pinIt.pin({
...
});
Consult the request module documentation for a full list of options.
debug mode
When instantiating set options.debug = true
for more verbose log output.
var PinIt = require('pin-it-node');
var pinIt = new PinIt({
username: 'MyUsername',
userurl: 'kengoldfarb',
password: 'MySuperSecretPassword',
debug: true
});
...
Versioning
This project will follow the Semantic Versioning 2.0.0 guidelines once version 1.0.0 is released. Until that time, any updates might be backwards-incompatible changes.
Since this is an unofficial api, a "stable" version 1.0.0 will be released once this has been tested in the wild and includes reasonable unit testing.
Unit tests
Not yet complete.
To run the tests...
$ cd tests/
$ npm install
$ node_modules/.bin/mocha pinItTests.js
Author
Ken Goldfarb http://www.kengoldfarb.com
Contributed unpin and repin functions, board functions, and boardId-less functionality:
Ben Pevsner http://www.benpevsner.com
License
MIT. Do whatever you want with it.