gopaper

package module
v0.8.0 Latest Latest
Warning

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

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

README

GoPaper

A GO library to interact with the Wallhaven API to search and retrieve wallpapers

Installation

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 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 creates a new unauthorized client

func NewClientWithKey 

func NewClientWithKey(apiKey string) Client

NewClientWithKey creates a new authorized client

func (*Client) GetCollections 

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

func (*Client) GetSettings 

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

func (*Client) GetTagDetails 

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

func (*Client) GetWallpaperDetails 

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

GetWallpaperDetails retrieves metadata of a wallpaper provided with the ID

func (*Client) NextPage 

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

NextPage retrieves new results of the next page

func (*Client) PrevPage 

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

PrevPage retrieves results of the previous page

func (*Client) Search 

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

Search performs the search based on provided search parameters

func (*Client) SetPage 

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

SetPage retrieves results based on the provided page

type CollectionResponse 

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

CollectionResponse holds wallpaper collections

type Collections 

type Collections struct {
	ID     int    `json:"id"`
	Label  string `json:"label"`
	Views  int    `json:"views"`
	Public int    `json:"public"`
	Count  int    `json:"count"`
}

Collections holds per collection data

type Meta 

type Meta struct {
	CurrentPage int    `json:"current_page"`
	LastPage    int    `json:"last_page"`
	PerPage     int    `json:"per_page"`
	Total       int    `json:"total"`
	Seed        string `json:"seed"`
}

Meta holds pagindation data

func (*Meta) UnmarshalJSON 

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

type SearchParams 

type SearchParams struct {
	// KeySearch holds the query of what will be searched
	KeySearch string

	// Categories filters the search to "general", "anime", and "people" as indicated by: "100", "010", "001"
	Categories string

	// Purity filters the search to "sfw", "sketchy", and "nsfw" as indicated by: "100", "010", "001"
	Purity string

	// Sorting: "date_added", "relevance", "random", "views", "favorites", "toplist"
	Sorting string

	// Order sorts by "desc" or "asc"
	Order string

	// AtLeast defines the minimum resolution allowed for the search: "1920x1080"
	AtLeast string

	// Resolution defines a list of allowed resolutions: "1920x1080,2400x1080"
	Resolution string

	// Ratios defines a list of allowed ratios: "16x9,16x10"
	Ratios string

	// Page specifies which page to obtain wallpapers
	Page int

	// Seed specifies the randomness if Sorting is set to "random"
	Seed string
}

SearchParams holds the seacrh configuration

func NewSearch 

func NewSearch() SearchParams

NewSearch initializes the default search parameters

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     string   `json:"thumb_size"`
	PerPage       string   `json:"per_page"`
	Purity        []string `json:"purity"`
	Categories    []string `json:"categories"`
	Resolutions   []string `json:"resolutions"`
	Ratios        []string `json:"aspect_ratios"`
	ToplistRange  string   `json:"toplist_range"`
	TagBlacklist  []string `json:"tag_blacklist"`
	UserBlacklist []string `json:"user_blacklist"`
}

Settings holds field data

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         int    `json:"id"`
	Name       string `json:"name"`
	Alias      string `json:"alias"`
	CategoryID int    `json:"category_id"`
	Category   string `json:"category"`
	Purity     string `json:"purity"`
	Date       string `json:"created_at"`
}

Tags holds the tags assigned to the 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 holds the thumbnail paths of the wallpaper

type Uploader 

type Uploader struct {
	Username string `json:"username"`
	Group    string `json:"group"`
}

Uploader holds the user to uploads the wallpaper

type Wallpaper 

type Wallpaper struct {
	Thumbnails Thumbs `json:"thumbs"`
	ID         string `json:"id"`
	URL        string `json:"url"`
	ShortURL   string `json:"short_url"`
	Views      int    `json:"views"`
	Favorites  int    `json:"favorites"`
	// Purity indicates content rating: "sfw", "sketchy", "nsfw"
	Purity string `json:"purity"`
	// Category indiacates content: "general", "anime", "people"
	Category   string `json:"category"`
	AxisX      int    `json:"dimension_x"`
	AxisY      int    `json:"dimension_y"`
	Resolution string `json:"resolution"`
	Date       string `json:"created_at"`
	Ratio      string `json:"ratio"`
	FileSize   int    `json:"file_size"`
	FileType   string `json:"file_type"`
	// Path holds the direct image path
	Path string `json:"path"`

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

Wallpaper holds the data of a wallpaper

func (Wallpaper) ImageURL 

func (w Wallpaper) ImageURL() string

Returns direct image URL of wallpaper

func (Wallpaper) IsAnime 

func (w Wallpaper) IsAnime() bool

IsAnime checks if wallpaper is Anime

func (Wallpaper) IsGeneral 

func (w Wallpaper) IsGeneral() bool

IsGeneral checks if wallpaper is General

func (Wallpaper) IsNSFW 

func (w Wallpaper) IsNSFW() bool

IsNSFW checks if wallpaper is NSFW

func (Wallpaper) IsPeople 

func (w Wallpaper) IsPeople() bool

IsPeople checks if wallpaper is People

func (Wallpaper) IsSFW 

func (w Wallpaper) IsSFW() bool

IsSFW checks if wallpaper is SFW

func (Wallpaper) IsSketchy 

func (w Wallpaper) IsSketchy() bool

IsSketchy checks if wallpaper 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 large thumbnail path

func (Wallpaper) ThumbOrig 

func (w Wallpaper) ThumbOrig() string

Returns the original thumbnail path

func (Wallpaper) ThumbSmall 

func (w Wallpaper) ThumbSmall() string

Return the small thumbnail path

func (Wallpaper) WallFileType 

func (w Wallpaper) WallFileType() string

Return file type

func (Wallpaper) WallShortURL 

func (w Wallpaper) WallShortURL() string

Returns shortened wallhaven link

func (Wallpaper) WallURL 

func (w Wallpaper) WallURL() string

Returns 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.