pinboard

README

Package pinboard

Package pinboard implements a golang wrapper for the pinboard api.

Documentation

Please refer to GoDoc for up-to-date documentation.

Documentation

Overview

Package pinboard provides a wrapper for accessing the Pinboard API.

https://pinboard.in/api/

All Pinboard API methods are fully supported.

Function names mirror the API endpoints. For example:

PostsAdd() calls the /posts/add method
TagsDelete() calls the /tags/delete method

If a method supports optional arguments then a MethodOptions struct allows you to specify those options to pass to said method. For example:

PostsAdd(&PostsAddOptions{})
PostsGet(&PostsGetOptions{})

Not all endpoints require arguments, in which case just pass nil.

PostsAll(nil)

Index

• func PostsAdd(opt *PostsAddOptions) error
• func PostsDates(opt *PostsDatesOptions) (map[string]int, error)
• func PostsDelete(url string) error
• func PostsSuggestPopular(url string) ([]string, error)
• func PostsSuggestRecommended(url string) ([]string, error)
• func PostsUpdate() (time.Time, error)
• func SetToken(token string)
• func TagsDelete(tag string) error
• func TagsRename(old, new string) error
• func UserAPIToken() (string, error)
• func UserSecret() (string, error)
• type Note
  • func NotesID(id string) (*Note, error)
  • func NotesList() ([]*Note, error)
• type Post
  • func PostsAll(opt *PostsAllOptions) ([]*Post, error)
  • func PostsGet(opt *PostsGetOptions) ([]*Post, error)
  • func PostsRecent(opt *PostsRecentOptions) ([]*Post, error)
• type PostsAddOptions
• type PostsAllOptions
• type PostsDatesOptions
• type PostsGetOptions
• type PostsRecentOptions
• type Tags
  • func TagsGet() (Tags, error)

Examples

• PostsAdd
• PostsGet

Functions

func PostsAdd

func PostsAdd(opt *PostsAddOptions) error

PostsAdd adds a bookmark.

https://pinboard.in/api/#posts_add

Example

opt := &PostsAddOptions{
	URL:         "https://github.com/imwally/pinboard",
	Description: "Testing Pinboard Go Package",
}

err := PostsAdd(opt)
if err != nil {
	log.Println("error adding post:", err)
}

func PostsDates

func PostsDates(opt *PostsDatesOptions) (map[string]int, error)

PostsDates returns a list of dates with the number of posts at each date.

https://pinboard.in/api/#posts_dates

func PostsDelete

func PostsDelete(url string) error

PostsDelete deletes the bookmark by url.

https://pinboard.in/api/#posts_delete

func PostsSuggestPopular

func PostsSuggestPopular(url string) ([]string, error)

PostsSuggestPopular returns a slice of popular tags for a given URL. Popular tags are tags used site-wide for the url.

https://pinboard.in/api/#posts_suggest

func PostsSuggestRecommended

func PostsSuggestRecommended(url string) ([]string, error)

PostsSuggestRecommended returns a slice of recommended tags for a given URL. Recommended tags are drawn from the user's own tags.

https://pinboard.in/api/#posts_suggest

func PostsUpdate

func PostsUpdate() (time.Time, error)

PostsUpdate returns the most recent time a bookmark was added, updated or deleted.

https://pinboard.in/api/#posts_update

func SetToken

func SetToken(token string)

SetToken sets the API token required to make API calls. The token is expected to be the full string "name:random".

func TagsDelete

func TagsDelete(tag string) error

TagsDelete deletes an existing tag.

func TagsRename

func TagsRename(old, new string) error

TagsRename renames a tag, or folds it in to an existing tag.

func UserAPIToken

func UserAPIToken() (string, error)

UserAPIToken returns the user's API token (for making API calls without a password).

func UserSecret

func UserSecret() (string, error)

UserSecret returns the user's secret RSS key (for viewing private feeds).

Types

type Note

type Note struct {
	// Unique ID of the note.
	ID string

	// Title of the note.
	Title string

	// 20 character long sha1 hash of the note text.
	Hash []byte

	// Time the note was created.
	CreatedAt time.Time

	// Time the note was updated.
	UpdatedAt time.Time

	// Character length of the note.
	Length int

	// Body text of the note.
	//
	// Note: only /notes/ID returns body text.
	Text []byte
}

Note represents a Pinboard note.

func NotesID

func NotesID(id string) (*Note, error)

NotesID returns an individual user note. The hash property is a 20 character long sha1 hash of the note text.

https://pinboard.in/api/#notes_get

func NotesList

func NotesList() ([]*Note, error)

NotesList returns a list of the user's notes.

https://pinboard.in/api/#notes_list

type Post

type Post struct {
	// URL of bookmark.
	Href *url.URL

	// Title of bookmark. This field is unfortunately named
	// 'description' for backwards compatibility with the
	// delicious API
	Description string

	// Description of the item. Called 'extended' for backwards
	// compatibility with delicious API.
	Extended []byte

	// Tags of bookmark.
	Tags []string

	// If the bookmark is private or public.
	Shared bool

	// If the bookmark is marked to read later.
	Toread bool

	// Create time for this bookmark.
	Time time.Time

	// Change detection signature of the bookmark.
	Meta []byte

	// Hash of the bookmark.
	Hash []byte

	// The number of other users who have bookmarked this same
	// item.
	Others int
}

Post represents a bookmark.

func PostsAll

func PostsAll(opt *PostsAllOptions) ([]*Post, error)

PostsAll returns all bookmarks in the user's account.

https://pinboard.in/api/#posts_all

func PostsGet

func PostsGet(opt *PostsGetOptions) ([]*Post, error)

PostsGet returns one or more posts (on a single day) matching the arguments. If no date or URL is given, date of most recent bookmark will be used.Returns one or more posts on a single day matching the arguments. If no date or URL is given, date of most recent bookmark will be used.

https://pinboard.in/api/#posts_get

Example

dt, err := time.Parse("2006-01-02", "2010-12-11")
if err != nil {
	log.Println(err)
}

posts, err := PostsGet(&PostsGetOptions{Dt: dt})
if err != nil {
	log.Println("error getting posts:", err)
}

for _, post := range posts {
	fmt.Println(post.Description)
	fmt.Println(post.Href)
	fmt.Println(post.Time)
}

Output:

Testing Pinboard Go Package
https://github.com/imwally/pinboard
2010-12-11 19:48:02 +0000 UTC

func PostsRecent

func PostsRecent(opt *PostsRecentOptions) ([]*Post, error)

PostsRecent returns a list of the user's most recent posts, filtered by tag.

https://pinboard.in/api/#posts_recent

type PostsAddOptions

type PostsAddOptions struct {
	// Required: The URL of the item.
	URL string

	// Required: Title of the item. This field is unfortunately
	// named 'description' for backwards compatibility with the
	// delicious API.
	Description string

	// Description of the item. Called 'extended' for backwards
	// compatibility with delicious API.
	Extended []byte

	// List of up to 100 tags.
	Tags []string

	// Creation time for this bookmark. Defaults to current
	// time. Datestamps more than 10 minutes ahead of server time
	// will be reset to current server time.
	Dt time.Time

	// Replace any existing bookmark with this URL. Default is
	// yes. If set to no, will throw an error if bookmark exists.
	Replace bool

	// Make bookmark public. Default is "yes" unless user has
	// enabled the "save all bookmarks as private" user setting,
	// in which case default is "no".
	Shared bool

	// Marks the bookmark as unread. Default is "no".
	Toread bool
}

PostsAddOptions represents the required and optional arguments for adding a bookmark.

type PostsAllOptions

type PostsAllOptions struct {
	// Filter by up to three tags.
	Tag []string

	// Offset value (default is 0).
	Start int

	// Number of results to return. Default is all.
	Results int

	// Return only bookmarks created after this time.
	Fromdt time.Time

	// Return only bookmarks created before this time.
	Todt time.Time

	// Include a change detection signature for each bookmark.
	//
	// Note: This probably doesn't work. A meta field is always
	// returned. The Pinboard API says the datatype is an int but
	// changing the value has no impact on the results. Using a
	// yes/no string like all the other meta options doesn't work
	// either.
	Meta int
}

PostsAllOptions represents the optional arguments for returning all bookmarks in the user's account.

type PostsDatesOptions

type PostsDatesOptions struct {
	// Filter by up to three tags.
	Tag []string
}

PostsDatesOptions represents the single optional argument for returning a list of dates with the number of posts at each date.

type PostsGetOptions

type PostsGetOptions struct {
	// Filter by up to three tags.
	Tag []string

	// Return results bookmarked on this day. UTC date in this
	// format: 2010-12-11.
	Dt time.Time

	// Return bookmark for this URL.
	URL string

	// Include a change detection signature in a meta attribute.
	Meta bool
}

PostsGetOptions represents the optional arguments for getting bookmarks.

type PostsRecentOptions

type PostsRecentOptions struct {
	// Filter by up to three tags.
	Tag []string

	// Number of results to return. Default is 15, max is 100.
	Count int
}

PostsRecentOptions represents the optional arguments for returning the user's most recent posts.

type Tags

type Tags map[string]string

Tags maps a tag name to the number of bookmarks that use that tag.

func TagsGet

func TagsGet() (Tags, error)

TagsGet returns a full list of the user's tags along with the number of times they were used.