gopaper

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 6 Imported by: 0

README

GoPaper

GO documentation

A Go library for interacting with the Wallhaven API to search and retrieve wallpapers.

Installation

Installing the wrapper for use is as simple as:

go get github.com/Yustinia/gopaper

Usage

Quickstart:

package main

import (
    "fmt"
    "github.com/Yustinia/gopaper"
)

func main() {
    // Create a client without API Key
    client := gopaper.NewClient()

    // Use this if you have a valid API key
    // client := gopaper.NewClientWithKey("APIKey")

    // Create new search
    params := gopaper.NewSearch()
    // Filter content to Anime
    params.Categories = "010"
    // Filter content rating to SFW
    params.Purity = "100"

    // Configure the search parameters
    params.KeySearch = "japan"

    // Perform the search and provide
    result, err := client.Search(params)
    if err != nil {
        panic(err)
    }

    for i, wall := range result.Wallpapers {
        fmt.Printf("[%d] %s\n", i, wall.Path)
    }

    // Get full details for a specific wallpaper from the result
    details, err := client.GetWallpaperDetails(result.Wallpapers[0].ID)
    // or by providing the ID as the argument
    // details, err := client.GetWallpaperDetails("poyzl3")
}

Features

  • Search Wallpapers
  • Get wallpaper details
  • Filter through search parameters:
    • Categories
    • Purity
    • Sorting
    • Order
    • At Least
    • Resolution
    • Ratios
    • Page
    • Seed

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrAPICollections = errors.New("API required for retreiving collections")
View Source 
var ErrAPISettings = errors.New("API required for reading settings")
View Source 
var ErrFirstPage = errors.New("already on first page")
View Source 
var ErrInvalidPage = errors.New("not a valid page")
View Source 
var ErrInvalidPageRange = errors.New("invalid page range")
View Source 
var ErrInvalidWallCount = errors.New("invalid wallpaper fetch count")
View Source 
var ErrLastPage = errors.New("already on the last page")

Functions

This section is empty.

Types

type Client 

type Client struct {
	APIKey  string
	BaseURL string
}

func NewClient 

func NewClient() Client

NewClient returns a client for unauthenticated API requests

func NewClientWithKey 

func NewClientWithKey(apiKey string) Client

NewClientWithKey returns a client authenticated with the given API key Endpoints like fetching NSFW tagged wallpapers require authentication

func (*Client) FetchPage added in v0.10.0 

func (c *Client) FetchPage(sp *SearchParams, page int) ([]Wallpaper, error)

FetchPage queries the API to retrieve a slice of wallpapers in the given page number

func (*Client) FetchPages added in v0.9.0 

func (c *Client) FetchPages(sp *SearchParams, fromPage int, toPage int) ([]Wallpaper, error)

FetchPages queries the API to retrieve a slice of wallpapers from a range of pages

func (*Client) FetchWallpaperCount added in v0.9.0 

func (c *Client) FetchWallpaperCount(sp *SearchParams, wallCount int) ([]Wallpaper, error)

FetchWallpaperCount queries the API to fetch a number of wallpapers then returns a slice

func (*Client) GetCollections 

func (c *Client) GetCollections() (CollectionResponse, error)

GetCollections returns the user's own collections

func (*Client) GetSettings 

func (c *Client) GetSettings() (SettingsResponse, error)

GetSettings returns user settings

func (*Client) GetTagDetails 

func (c *Client) GetTagDetails(tagID int) (TagResponse, error)

GetTagDetails returns tag metadata for a specific tag ID

func (*Client) GetWallpaperDetails 

func (c *Client) GetWallpaperDetails(wallID string) (WallpaperResponse, error)

GetWallpaperDetails retrieves wallpaper information or metadata from the given wallhaven appropriate wallpaper ID

func (*Client) NextPage 

func (c *Client) NextPage(result SearchResponse, sp *SearchParams) (SearchResponse, error)

NextPage queries the API using the same search parameters but page is incremented

func (*Client) PrevPage 

func (c *Client) PrevPage(result SearchResponse, sp *SearchParams) (SearchResponse, error)

PrevPage queries the API using the same search parameters but page is decremented

func (*Client) Search 

func (c *Client) Search(sp SearchParams) (SearchResponse, error)

Search queries the API for wallpapers matching the given search parameters

func (*Client) SetPage 

func (c *Client) SetPage(result SearchResponse, sp *SearchParams, page int) (SearchResponse, error)

SetPage queries the API using the same search parameters with a provided page number which to fetch

type CollectionResponse 

type CollectionResponse struct {
	UserCollections []Collections `json:"data"`
}

CollectionResponse holds wallpaper collections

type Collections 

type Collections struct {
	// ID is the unique collection identifier.
	ID int `json:"id"`
	// Label is the collection's display name.
	Label string `json:"label"`
	// Views is the number of times the collection has been viewed.
	Views int `json:"views"`
	// Public indicates whether the collection is publicly visible (1) or private (0).
	Public int `json:"public"`
	// Count is the number of wallpapers in the collection.
	Count int `json:"count"`
}

Collections represents a user's wallpaper collection.

type Meta 

type Meta struct {
	// CurrentPage is the page number returned in this response.
	CurrentPage int `json:"current_page"`
	// LastPage is the final available page for this query.
	LastPage int `json:"last_page"`
	// PerPage is the number of results returned per page.
	PerPage int `json:"per_page"`
	// Total is the total number of results matching the query.
	Total int `json:"total"`
	// Seed is the randomization seed used for "random" sorting.
	// Reuse this seed to retrieve the same result set again.
	Seed string `json:"seed"`
}

Meta contains pagination metadata for search results.

func (*Meta) UnmarshalJSON 

func (m *Meta) UnmarshalJSON(data []byte) error

type SearchParams 

type SearchParams struct {
	// KeySearch is the search keyword or phrase.
	KeySearch string

	// Categories filters by content type using a 3-bit string:
	// "100" = general, "010" = anime, "001" = people.
	// Combine with "1" for enabled (e.g., "111" for all).
	Categories string

	// Purity filters by content rating using a 3-bit string:
	// "100" = sfw, "010" = sketchy, "001" = nsfw.
	// Combine with "1" for enabled (e.g., "110" for sfw + sketchy).
	Purity string

	// Sorting determines result order: "date_added", "relevance", "random",
	// "views", "favorites", or "toplist".
	Sorting string

	// Order is the sort direction: "desc" or "asc".
	Order string

	// TopRange filters results to a time window when Sorting is "toplist":
	// "1d", "3d", "1w", "1M", "3M", "6M", "1y".
	TopRange string

	// AtLeast is the minimum resolution (e.g., "1920x1080").
	AtLeast string

	// Resolution is a comma-separated list of exact resolutions
	// (e.g., "1920x1080,2400x1080").
	Resolution string

	// Ratios is a comma-separated list of aspect ratios
	// (e.g., "16x9,16x10").
	Ratios string

	// Page is the result page to retrieve (1-based).
	Page int

	// Seed is the randomization seed for consistent results when
	// Sorting is "random". Reuse the same seed to get the same page.
	Seed string
}

SearchParams configures a wallpaper search query.

func NewSearch 

func NewSearch() SearchParams

NewSearch returns SearchParams with sensible and safe defaults: Defaults to SFW content rating

type SearchResponse 

type SearchResponse struct {
	Metadata   Meta        `json:"meta"`
	Wallpapers []Wallpaper `json:"data"`
}

SearchResponse holds Meta and Wallpaper slices

type Settings 

type Settings struct {
	// ThumbSize is the preferred thumbnail resolution (e.g., "small", "large").
	ThumbSize string `json:"thumb_size"`
	// PerPage is the number of wallpapers to display per page.
	PerPage string `json:"per_page"`
	// Purity is the list of enabled content ratings (e.g., ["sfw", "sketchy"]).
	Purity []string `json:"purity"`
	// Categories is the list of enabled content categories (e.g., ["general", "anime"]).
	Categories []string `json:"categories"`
	// Resolutions is the list of allowed wallpaper resolutions.
	Resolutions []string `json:"resolutions"`
	// Ratios is the list of preferred aspect ratios.
	Ratios []string `json:"aspect_ratios"`
	// ToplistRange is the time period for toplist results (e.g., "1d", "1w", "1M", "1y").
	ToplistRange string `json:"toplist_range"`
	// TagBlacklist is the list of tags to exclude from search results.
	TagBlacklist []string `json:"tag_blacklist"`
	// UserBlacklist is the list of uploaders whose wallpapers are hidden.
	UserBlacklist []string `json:"user_blacklist"`
}

Settings represents a user's Wallhaven account preferences.

type SettingsResponse 

type SettingsResponse struct {
	UserSettings Settings `json:"data"`
}

SettingsResponse holds user settings data

type TagResponse 

type TagResponse struct {
	Tagdata Tags `json:"data"`
}

TagResponse holds data when looking up tag IDs

type Tags 

type Tags struct {
	// ID is the unique tag identifier.
	ID int `json:"id"`
	// Name is the display name of the tag.
	Name string `json:"name"`
	// Alias is an alternative name or shorthand for the tag, if any.
	Alias string `json:"alias"`
	// CategoryID is the identifier of the tag's parent category.
	CategoryID int `json:"category_id"`
	// Category is the human-readable name of the parent category.
	Category string `json:"category"`
	// Purity is the content rating associated with this tag: "sfw", "sketchy", or "nsfw".
	Purity string `json:"purity"`
	// Date is the RFC3339 timestamp when the tag was created.
	Date string `json:"created_at"`
}

Tags represent a tag assigned to a wallpaper.

func (Tags) TagAlias 

func (t Tags) TagAlias() string

Return alias of tag

func (Tags) TagCategory 

func (t Tags) TagCategory() string

Return category name

func (Tags) TagCategoryID 

func (t Tags) TagCategoryID() int

Return category id of a tag

func (Tags) TagDate 

func (t Tags) TagDate() string

Return tag creation date

func (Tags) TagID 

func (t Tags) TagID() int

Return tag ID

func (Tags) TagName 

func (t Tags) TagName() string

Return tag name

func (Tags) TagPurity 

func (t Tags) TagPurity() string

Return tag content rating

type Thumbs 

type Thumbs struct {
	Large string `json:"large"`
	Orig  string `json:"original"`
	Small string `json:"small"`
}

Thumbs contain thumbnail URLs of a wallpaper

type Uploader 

type Uploader struct {
	// Username is the name of the uploader
	Username string `json:"username"`
	// Group is where the uploader is a part of
	Group string `json:"group"`
}

Uploader contains information who uploaded the wallpaper

type Wallpaper 

type Wallpaper struct {
	Thumbnails Thumbs `json:"thumbs"`
	// ID contains the uniquely assigned ID for the wallpaper
	ID string `json:"id"`
	// URL contains the full wallhaven URL
	URL string `json:"url"`
	// ShortURL contains the shortened wallhaven URL
	ShortURL string `json:"short_url"`
	// Views is the number of times a wallpaper has ben seen
	Views int `json:"views"`
	// Favorites is the number of users that has favorited a wallpaper
	Favorites int `json:"favorites"`
	// Purity indicates rating: "sfw", "sketchy", "nsfw"
	Purity string `json:"purity"`
	// Category indicates content: "general", "anime", "people"
	Category string `json:"category"`
	// AxisX contains the width pixel count
	AxisX int `json:"dimension_x"`
	// AxisY contains the height pixel count
	AxisY int `json:"dimension_y"`
	// Resolution contains the WIDTH x HEIGHT pixel count
	Resolution string `json:"resolution"`
	// Date indicates when the wallpaper is was uploaded
	Date string `json:"created_at"`
	// Ratio is the wallpaper's aspect ratio
	Ratio string `json:"ratio"`
	// FileSize is how large the file is in Bytes
	FileSize int `json:"file_size"`
	// FileType is the format the wallpaper
	FileType string `json:"file_type"`
	// Path holds the direct image path
	Path string `json:"path"`

	WallpaperUploader Uploader `json:"uploader"`
	WallpaperTags     []Tags   `json:"tags"`
}

Wallpaper represents a single wallpaper from the API

func (Wallpaper) ImageURL 

func (w Wallpaper) ImageURL() string

Returns a direct image URL

func (Wallpaper) IsAnime 

func (w Wallpaper) IsAnime() bool

IsAnime checks if wallpaper category is Anime

func (Wallpaper) IsGeneral 

func (w Wallpaper) IsGeneral() bool

IsGeneral checks if wallpaper category rating is General

func (Wallpaper) IsNSFW 

func (w Wallpaper) IsNSFW() bool

IsNSFW checks if wallpaper content rating is NSFW

func (Wallpaper) IsPeople 

func (w Wallpaper) IsPeople() bool

IsPeople checks if wallpaper category is People

func (Wallpaper) IsSFW 

func (w Wallpaper) IsSFW() bool

IsSFW checks if wallpaper content rating is SFW

func (Wallpaper) IsSketchy 

func (w Wallpaper) IsSketchy() bool

IsSketchy checks if wallpaper content rating is Sketchy

func (Wallpaper) SizeByte 

func (w Wallpaper) SizeByte() int

Return file size in bytes

func (Wallpaper) SizeKiB 

func (w Wallpaper) SizeKiB() float64

Return file size in KiB

func (Wallpaper) SizeMiB 

func (w Wallpaper) SizeMiB() float64

Return file size in MiB

func (Wallpaper) TagNames 

func (w Wallpaper) TagNames() []string

TagNames returns a slice of tags assigned to the wallpaper

func (Wallpaper) ThumbLarge 

func (w Wallpaper) ThumbLarge() string

Returns the path of the large thumbnail

func (Wallpaper) ThumbOrig 

func (w Wallpaper) ThumbOrig() string

Returns the original size of the thumbnail

func (Wallpaper) ThumbSmall 

func (w Wallpaper) ThumbSmall() string

Return the path of the small thumbnail

func (Wallpaper) WallFileType 

func (w Wallpaper) WallFileType() string

Return file type in "image/type"

func (Wallpaper) WallShortURL 

func (w Wallpaper) WallShortURL() string

Returns the shortened wallhaven link

func (Wallpaper) WallURL 

func (w Wallpaper) WallURL() string

Returns the full wallhaven link

func (Wallpaper) WallXAxis 

func (w Wallpaper) WallXAxis() int

Returns pixel count at the X axis

func (Wallpaper) WallYAxis 

func (w Wallpaper) WallYAxis() int

Returns pixel count at the Y axis

type WallpaperResponse 

type WallpaperResponse struct {
	Wall Wallpaper `json:"data"`
}

WallpaperResponse holds data of a singular wallpaper

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.