discogs

package module
v0.0.0-...-50ee0e6 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2024 License: MIT Imports: 9 Imported by: 0

README

REST API 2.0 Discogs.com client

go-discogs is a Go client library for the Discogs API. Check the usage section to see how to access the Discogs API.

The lib is under MIT but be sure you are familiar with Discogs API Terms of Use.

Features
  • Database
    • Releases
    • Release Rating
    • Master Releases
    • Master Versions
    • Artists
    • Artist Releases
    • Label
    • All Label Releases
  • Search
  • User Collection
    • Collection Folders
    • Folder
    • Collection Items by Folder
    • Collection Items by Release
  • Marketplace
    • Price Suggestions
    • Release Statistics

Install

go get github.com/irlndts/go-discogs

Usage

The discogs package provides a client for accessing the Discogs API. First of all import library and init client variable. According to discogs api documentation you must provide your user-agent.

import "github.com/irlndts/go-discogs"

Some requests require authentication (as any user). According to Discogs, to send requests with Discogs Auth, you have two options: sending your credentials in the query string with key and secret parameters or a token parameter.

client, err := discogs.New(&discogs.Options{
        UserAgent: "Some Name",
        Currency:  "EUR", // optional, "USD" (default), "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", "ZAR" are allowed
        Token:     "Some Token", // optional
        URL:       "https://api.discogs.com", // optional
    })
Releases
  release, _ := client.Release(9893847)
  fmt.Println(release.Artists[0].Name, " - ", release.Title) 
  // St. Petersburg Ska-Jazz Review  -  Elephant Riddim

Issue a search query to discogs database. This endpoint accepts pagination parameters. Authentication (as any user) is required.

Use SearchRequest struct to create a request.

type SearchRequest struct {
    Q             string // search query (optional)
    Type          string // one of release, master, artist, label (optional)
    Title         string // search by combined “Artist Name - Release Title” title field (optional)
    ReleaseTitle string // search release titles (optional)
    Credit        string // search release credits (optional)
    Artist        string // search artist names (optional)
    Anv           string // search artist ANV (optional)
    Label         string // search label names (optional)
    Genre         string // search genres (optional)
    Style         string // search styles (optional)
    Country       string // search release country (optional)
    Year          string // search release year (optional)
    Format        string // search formats (optional)
    Catno         string // search catalog number (optional)
    Barcode       string // search barcodes (optional)
    Track         string // search track titles (optional)
    Submitter     string // search submitter username (optional)
    Contributer   string // search contributor usernames (optional)

    Page     int // optional
    PerPage  int // optional
}

  request := discogs.SearchRequest{Artist: "reggaenauts", ReleaseTitle: "river rock", Page: 0, PerPage: 1}
  search, _ := client.Search(request)

  for _, r := range search.Results {
    fmt.Println(r.Title)
  }
User Collection

Query a users collection.

Collection Folders
  collection, err := client.CollectionFolders("my_user")
Folder
  folder, err := client.Folder("my_user", 0)
Collection Items by Folder
  items, err := client.CollectionItemsByFolder("my_user", 0, &Pagination{Sort: "artist", SortOrder: "desc", PerPage: 2})
Collection Items by Release
  items, err := client.CollectionItemsByRelease("my_user", 12934893)
Marketplace

Query a user's marketplace

Price Suggestions

Retrieve price suggestions for the provided Release ID

  suggestions, err := client.PriceSuggestions(12345)
Release Statistics

Retrieve marketplace statistics for the provided Release ID

  stats, err := client.ReleaseStatistics(12345)

...

by the way, this is my discogs page

Documentation

Overview

Package discogs is a Go client library for the Discogs API.

The discogs package provides a client for accessing the Discogs API. First of all import library and init client variable. According to discogs api documentation you must provide your user-agent.

Some requests require authentification (as any user). According to Discogs, to send requests with Discogs Auth, you have two options: sending your credentials in the query string with key and secret parameters or a token parameter. This is token way example: 

client, err := discogs.New(&discogs.Options{
	UserAgent: "Some Name",
	Currency:  "EUR", // optional, "USD" (default), "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", "ZAR" are allowed
	Token:     "Some Token", // optional
	URL:       "https://api.discogs.com", // optional
})

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrCurrencyNotSupported = &Error{"currency does not supported"}
	ErrInvalidReleaseID     = &Error{"invalid release id"}
	ErrInvalidSortKey       = &Error{"invalid sort key"}
	ErrInvalidUsername      = &Error{"invalid username"}
	ErrTooManyRequests      = &Error{"too many requests"}
	ErrUnauthorized         = &Error{"authentication required"}
	ErrUserAgentInvalid     = &Error{"invalid user-agent"}
)

APIErrors

Functions

This section is empty.

Types

type Alias 

type Alias struct {
	ID          int    `json:"id"`
	Name        string `json:"name"`
	ResourceURL string `json:"resource_url"`
}

Alias ...

type Artist 

type Artist struct {
	ID             int      `json:"id"`
	Name           string   `json:"name"`
	Realname       string   `json:"realname"`
	Members        []Member `json:"members,omitempty"`
	Aliases        []Alias  `json:"aliases,omitempty"`
	Namevariations []string `json:"namevariations"`
	Images         []Image  `json:"images"`
	Profile        string   `json:"profile"`
	ReleasesURL    string   `json:"releases_url"`
	ResourceURL    string   `json:"resource_url"`
	URI            string   `json:"uri"`
	URLs           []string `json:"urls"`
	Groups         []Member `json:"groups,omitempty"`
	DataQuality    string   `json:"data_quality"`
}

Artist resource represents a person in the Discogs database who contributed to a Release in some capacity. More information https://www.discogs.com/developers#page:database,header:database-artist

type ArtistReleases 

type ArtistReleases struct {
	Pagination Page            `json:"pagination"`
	Releases   []ReleaseSource `json:"releases"`
}

ArtistReleases ...

type ArtistSource 

type ArtistSource struct {
	Anv         string `json:"anv"`
	ID          int    `json:"id"`
	Join        string `json:"join"`
	Name        string `json:"name"`
	ResourceURL string `json:"resource_url"`
	Role        string `json:"role"`
	Tracks      string `json:"tracks"`
}

ArtistSource ...

type BasicInformation 

type BasicInformation struct {
	ID          int            `json:"id"`
	Artists     []ArtistSource `json:"artists"`
	CoverImage  string         `json:"cover_image"`
	Formats     []Format       `json:"formats"`
	Labels      []LabelSource  `json:"labels"`
	Genres      []string       `json:"genres"`
	MasterID    int            `json:"master_id"`
	MasterURL   *string        `json:"master_url"`
	ResourceURL string         `json:"resource_url"`
	Styles      []string       `json:"styles"`
	Thumb       string         `json:"thumb"`
	Title       string         `json:"title"`
	Year        int            `json:"year"`
}

BasicInformation ...

type CollectionFolders 

type CollectionFolders struct {
	Folders []Folder `json:"folders"`
}

CollectionFolders serves collection response from discogs.

type CollectionItemSource 

type CollectionItemSource struct {
	ID               int              `json:"id"`
	BasicInformation BasicInformation `json:"basic_information"`
	DateAdded        string           `json:"date_added"`
	FolderID         int              `json:"folder_id,omitempty"`
	InstanceID       int              `json:"instance_id"`
	Notes            []Notes          `json:"notes,omitempty"`
	Rating           int              `json:"rating"`
}

CollectionItemSource ...

type CollectionItems 

type CollectionItems struct {
	Pagination Page                   `json:"pagination"`
	Items      []CollectionItemSource `json:"releases"`
}

CollectionItems list of items in a user’s collection

type CollectionService 

type CollectionService interface {
	// Retrieve a list of folders in a user’s collection.
	// If folder_id is not 0, authentication as the collection owner is required.
	CollectionFolders(username string) (*CollectionFolders, error)
	// Retrieve a list of items in a folder in a user’s collection.
	// If folderID is not 0, authentication with token is required.
	CollectionItemsByFolder(username string, folderID int, pagination *Pagination) (*CollectionItems, error)
	// Retrieve the user’s collection folders which contain a specified release.
	// The releaseID must be non-zero.
	CollectionItemsByRelease(username string, releaseID int) (*CollectionItems, error)
	// Retrieve metadata about a folder in a user’s collection.
	Folder(username string, folderID int) (*Folder, error)
	// Change the value of a notes field (including media/sleeve condition) on a particular instance.
	// fieldID 0 = Media Condition, 1 = Sleeve Condition, 3+ = Notes fields.
	EditFieldsInstance(username string, folderID, releaseID, instanceID int, fieldID FieldID, value string) error
}

CollectionService is an interface to work with collection.

type Community 

type Community struct {
	Contributors []Contributor `json:"contributors"`
	DataQuality  string        `json:"data_quality"`
	Have         int           `json:"have"`
	Rating       Rating        `json:"rating"`
	Status       string        `json:"status"`
	Submitter    Submitter     `json:"submitter"`
	Want         int           `json:"want"`
}

Community ...

type Company 

type Company struct {
	Catno          string `json:"catno"`
	EntityType     string `json:"entity_type"`
	EntityTypeName string `json:"entity_type_name"`
	ID             int    `json:"id"`
	Name           string `json:"name"`
	ResourceURL    string `json:"resource_url"`
}

Company ...

type Contributor 

type Contributor struct {
	ResourceURL string `json:"resource_url"`
	Username    string `json:"username"`
}

Contributor ...

type DatabaseService 

type DatabaseService interface {
	// Artist represents a person in the discogs database.
	Artist(artistID int) (*Artist, error)
	// ArtistReleases returns a list of releases and masters associated with the artist.
	ArtistReleases(artistID int, pagination *Pagination) (*ArtistReleases, error)
	// Label returns a label.
	Label(labelID int) (*Label, error)
	// LabelReleases returns a list of Releases associated with the label.
	LabelReleases(labelID int, pagination *Pagination) (*LabelReleases, error)
	// Master returns a master release.
	Master(masterID int) (*Master, error)
	// MasterVersions retrieves a list of all Releases that are versions of this master.
	MasterVersions(masterID int, pagination *Pagination) (*MasterVersions, error)
	// Release returns release by release's ID.
	Release(releaseID int) (*Release, error)
	// ReleaseRating retruns community release rating.
	ReleaseRating(releaseID int) (*ReleaseRating, error)
}

DatabaseService is an interface to work with database.

type Discogs 

type Discogs interface {
	CollectionService
	DatabaseService
	MarketPlaceService
	SearchService
}

Discogs is an interface for making Discogs API requests.

func New 

func New(o *Options) (Discogs, error)

New returns a new discogs API client.

type Error 

type Error struct {
	Message string
}

Error represents a Discogs API error

func (*Error) Error 

func (e *Error) Error() string

type FieldID 

type FieldID int
const (
	MediaConditionField  FieldID = 1
	SleeveConditionField FieldID = 2
	NotesField           FieldID = 3
)

type Folder 

type Folder struct {
	ID          int    `json:"id"`
	Count       int    `json:"count"`
	Name        string `json:"name"`
	ResourceURL string `json:"resource_url"`
}

Folder serves folder response from discogs.

type Format 

type Format struct {
	Descriptions []string `json:"descriptions"`
	Name         string   `json:"name"`
	Qty          string   `json:"qty"`
	Text         string   `json:"text,omitempty"`
}

Format ...

type Identifier 

type Identifier struct {
	Description string `json:"description,omitempty"`
	Type        string `json:"type"`
	Value       string `json:"value"`
}

Identifier ...

type Image 

type Image struct {
	Height      int    `json:"height"`
	Width       int    `json:"width"`
	ResourceURL string `json:"resource_url"`
	Type        string `json:"type"`
	URI         string `json:"uri"`
	URI150      string `json:"uri150"`
}

Image ...

type Label 

type Label struct {
	Profile     string     `json:"profile"`
	ReleasesURL string     `json:"releases_url"`
	Name        string     `json:"name"`
	ContactInfo string     `json:"contact_info"`
	URI         string     `json:"uri"`
	Sublabels   []Sublable `json:"sublabels"`
	URLs        []string   `json:"urls"`
	Images      []Image    `json:"images"`
	ResourceURL string     `json:"resource_url"`
	ID          int        `json:"id"`
	DataQuality string     `json:"data_quality"`
}

Label resource represents a label, company, recording studio, location, or other entity involved with artists and releases.

type LabelReleases 

type LabelReleases struct {
	Pagination Page            `json:"pagination"`
	Releases   []ReleaseSource `json:"releases"`
}

LabelReleases is a list of Releases associated with the label.

type LabelSource 

type LabelSource struct {
	Catno          string `json:"catno"`
	EntityType     string `json:"entity_type"`
	EntityTypeName string `json:"entity_type_name"`
	ID             int    `json:"id"`
	Name           string `json:"name"`
	ResourceURL    string `json:"resource_url"`
}

LabelSource ...

type Listing 

type Listing struct {
	Currency string  `json:"currency"`
	Value    float64 `json:"value"`
}

Listing is a marketplace listing with the user's currency and a price value

type MarketPlaceService 

type MarketPlaceService interface {
	// The best price suggestions according to grading
	// Authentication is required.
	PriceSuggestions(releaseID int) (*PriceListing, error)
	// Short summary of marketplace listings
	// Authentication is optional.
	ReleaseStatistics(releaseID int) (*Stats, error)
}

type Master 

type Master struct {
	ID                   int            `json:"id"`
	Styles               []string       `json:"styles"`
	Genres               []string       `json:"genres"`
	Title                string         `json:"title"`
	Year                 int            `json:"year"`
	Tracklist            []Track        `json:"tracklist"`
	Notes                string         `json:"notes"`
	Artists              []ArtistSource `json:"artists"`
	Images               []Image        `json:"images"`
	Videos               []Video        `json:"videos"`
	NumForSale           int            `json:"num_for_sale"`
	LowestPrice          float64        `json:"lowest_price"`
	URI                  string         `json:"uri"`
	MainRelease          int            `json:"main_release"`
	MainReleaseURL       string         `json:"main_release_url"`
	MostRecentRelease    int            `json:"most_recent_release"`
	MostRecentReleaseURL string         `json:"most_recent_release_url"`
	VersionsURL          string         `json:"versions_url"`
	ResourceURL          string         `json:"resource_url"`
	DataQuality          string         `json:"data_quality"`
}

Master resource represents a set of similar releases. Masters (also known as `master releases`) have a `main release` which is often the chronologically earliest. More information https://www.discogs.com/developers#page:database,header:database-master-release

type MasterVersions 

type MasterVersions struct {
	Pagination Page      `json:"pagination"`
	Versions   []Version `json:"versions"`
}

MasterVersions retrieves a list of all releases that are versions of this master.

type Member 

type Member struct {
	Active      bool   `json:"active"`
	ID          int    `json:"id"`
	Name        string `json:"name"`
	ResourceURL string `json:"resource_url"`
}

Member ...

type Notes 

type Notes struct {
	FieldID FieldID `json:"field_id"`
	Value   string  `json:"value"`
}

Notes ...

type Options 

type Options struct {
	// Discogs API endpoint (optional).
	URL string
	// Currency to use (optional, default is USD).
	Currency string
	// UserAgent to to call discogs api with.
	UserAgent string
	// Token provided by discogs (optional).
	Token string
}

Options is a set of options to use discogs API client

type Page 

type Page struct {
	PerPage int      `json:"per_page"`
	Items   int      `json:"items"`
	Page    int      `json:"page"`
	URLs    URLsList `json:"urls"`
	Pages   int      `json:"pages"`
}

Page ...

type Pagination 

type Pagination struct {
	// TODO(irlndts): validate requested Sort
	Sort string // year, title, format etc
	// TODO(irlndts): validate requested SortOrder
	SortOrder string // asc, desc
	Page      int
	PerPage   int
}

Pagination ...

type PriceListing 

type PriceListing struct {
	VeryGood     *Listing `json:"Very Good (VG),omitempty"`
	GoodPlus     *Listing `json:"Good Plus (G+),omitempty"`
	NearMint     *Listing `json:"Near Mint (NM or M-)"`
	Good         *Listing `json:"Good (G),omitempty"`
	VeryGoodPlus *Listing `json:"Very Good Plus (VG+),omitempty"`
	Mint         *Listing `json:"Mint (M),omitempty"`
	Fair         *Listing `json:"Fair (F),omitempty"`
	Poor         *Listing `json:"Poor (P),omitempty"`
}

PriceListings are Listings per grading quality

type Rating 

type Rating struct {
	Average float32 `json:"average"`
	Count   int     `json:"count"`
}

Rating ...

type Release 

type Release struct {
	Title             string         `json:"title"`
	ID                int            `json:"id"`
	Artists           []ArtistSource `json:"artists"`
	ArtistsSort       string         `json:"artists_sort"`
	DataQuality       string         `json:"data_quality"`
	Thumb             string         `json:"thumb"`
	Community         Community      `json:"community"`
	Companies         []Company      `json:"companies"`
	Country           string         `json:"country"`
	DateAdded         string         `json:"date_added"`
	DateChanged       string         `json:"date_changed"`
	EstimatedWeight   int            `json:"estimated_weight"`
	ExtraArtists      []ArtistSource `json:"extraartists"`
	FormatQuantity    int            `json:"format_quantity"`
	Formats           []Format       `json:"formats"`
	Genres            []string       `json:"genres"`
	Identifiers       []Identifier   `json:"identifiers"`
	Images            []Image        `json:"images"`
	Labels            []LabelSource  `json:"labels"`
	LowestPrice       float64        `json:"lowest_price"`
	MasterID          int            `json:"master_id"`
	MasterURL         string         `json:"master_url"`
	Notes             string         `json:"notes,omitempty"`
	NumForSale        int            `json:"num_for_sale,omitempty"`
	Released          string         `json:"released"`
	ReleasedFormatted string         `json:"released_formatted"`
	ResourceURL       string         `json:"resource_url"`
	Series            []Series       `json:"series"`
	Status            string         `json:"status"`
	Styles            []string       `json:"styles"`
	Tracklist         []Track        `json:"tracklist"`
	URI               string         `json:"uri"`
	Videos            []Video        `json:"videos"`
	Year              int            `json:"year"`
}

Release serves relesase response from discogs.

type ReleaseRating 

type ReleaseRating struct {
	ID     int    `json:"release_id"`
	Rating Rating `json:"rating"`
}

ReleaseRating serves response for community release rating request.

type ReleaseSource 

type ReleaseSource struct {
	Artist      string `json:"artist"`
	Catno       string `json:"catno"`
	Format      string `json:"format"`
	ID          int    `json:"id"`
	ResourceURL string `json:"resource_url"`
	Status      string `json:"status"`
	Thumb       string `json:"thumb"`
	Title       string `json:"title"`
	Year        int    `json:"year"`
	MainRelease int    `json:"main_release"`
	Role        string `json:"role"`
	Type        string `json:"type"`
}

ReleaseSource ...

type Result 

type Result struct {
	Style       []string  `json:"style,omitempty"`
	Thumb       string    `json:"thumb,omitempty"`
	CoverImage  string    `json:"cover_image,omitempty"`
	Title       string    `json:"title,omitempty"`
	Country     string    `json:"country,omitempty"`
	Format      []string  `json:"format,omitempty"`
	URI         string    `json:"uri,omitempty"`
	Community   Community `json:"community,omitempty"`
	Label       []string  `json:"label,omitempty"`
	Catno       string    `json:"catno,omitempty"`
	Year        string    `json:"year,omitempty"`
	Genre       []string  `json:"genre,omitempty"`
	ResourceURL string    `json:"resource_url,omitempty"`
	Type        string    `json:"type,omitempty"`
	ID          int       `json:"id,omitempty"`
	MasterID    int       `json:"master_id,omitempty"`
}

Result describes a part of search result 

type Search struct {
	Pagination Page     `json:"pagination"`
	Results    []Result `json:"results,omitempty"`
}

Search describes search response

type SearchRequest 

type SearchRequest struct {
	Q            string // search query
	Type         string // one of release, master, artist, label
	Title        string // search by combined “Artist Name - Release Title” title field
	ReleaseTitle string // search release titles
	Credit       string // search release credits
	Artist       string // search artist names
	Anv          string // search artist ANV
	Label        string // search label names
	Genre        string // search genres
	Style        string // search styles
	Country      string // search release country
	Year         string // search release year
	Format       string // search formats
	Catno        string // search catalog number
	Barcode      string // search barcodes
	Track        string // search track titles
	Submitter    string // search submitter username
	Contributor  string // search contributor usernames

	Page    int
	PerPage int
}

SearchRequest describes search request

type SearchService 

type SearchService interface {
	// Search makes search request to discogs.
	// Issue a search query to database. This endpoint accepts pagination parameters.
	// Authentication (as any user) is required.
	// https://www.discogs.com/developers/#page:database,header:database-search
	Search(req SearchRequest) (*Search, error)
}

SearchService is an interface to work with search.

type Series 

type Series struct {
	Catno          string `json:"catno"`
	EntityType     string `json:"entity_type"`
	EntityTypeName string `json:"entity_type_name"`
	ID             int    `json:"id"`
	Name           string `json:"name"`
	ResourceURL    string `json:"resource_url"`
	ThumbnailURL   string `json:"thumbnail_url,omitempty"`
}

Series ...

type Stats 

type Stats struct {
	LowestPrice *Listing `json:"lowest_price"`
	ForSale     int      `json:"num_for_sale"`
	Blocked     bool     `json:"blocked_from_sale"`
}

Stats returns the marketplace stats summary for a release containing

type Sublable 

type Sublable struct {
	ResourceURL string `json:"url"`
	ID          int    `json:"id"`
	Name        string `json:"name"`
}

Sublable ...

type Submitter 

type Submitter struct {
	ResourceURL string `json:"resource_url"`
	Username    string `json:"username"`
}

Submitter ...

type Track 

type Track struct {
	Duration     string         `json:"duration"`
	Position     string         `json:"position"`
	Title        string         `json:"title"`
	Type         string         `json:"type_"`
	Extraartists []ArtistSource `json:"extraartists,omitempty"`
	Artists      []ArtistSource `json:"artists,omitempty"`
}

Track ...

type URLsList 

type URLsList struct {
	Last string `json:"last,omitempty"`
	Next string `json:"next,omitempty"`
}

URLsList ...

type Version 

type Version struct {
	Catno       string `json:"catno"`
	Country     string `json:"country"`
	Format      string `json:"format"`
	ID          int    `json:"id"`
	Label       string `json:"label"`
	Released    string `json:"released"`
	ResourceURL string `json:"resource_url"`
	Status      string `json:"status"`
	Thumb       string `json:"thumb"`
	Title       string `json:"title"`
}

Version ...

type Video 

type Video struct {
	Description string `json:"description"`
	Duration    int    `json:"duration"`
	Embed       bool   `json:"embed"`
	Title       string `json:"title"`
	URI         string `json:"uri"`
}

Video ...

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.