discogs

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.

Feauteres

• Database
• Releases
• Release Rating
• Master Releases
• Master Versions
• Artists
• Artist Releases
• Label
• All Label Releases
• Search

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

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

Search

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
}

Example

  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)
  }

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

• Variables
• type Alias
• type Artist
• type ArtistReleases
• type ArtistSource
• type Community
• type Company
• type Contributor
• type DatabaseService
• type Discogs
  • func New(o *Options) (Discogs, error)
• type Error
  • func (e *Error) Error() string
• type Format
• type Identifier
• type Image
• type Label
• type LabelReleases
• type LabelSource
• type Master
• type MasterVersions
• type Member
• type Options
• type Page
• type Pagination
• type Rating
• type Release
• type ReleaseRating
• type ReleaseSource
• type Result
• type Search
• type SearchRequest
• type SearchService
• type Series
• type Sublable
• type Submitter
• type Track
• type URLsList
• type Version
• type Video

Variables

var (
	ErrUnauthorized         = &Error{"authentication required"}
	ErrCurrencyNotSupported = &Error{"currency does not supported"}
	ErrUserAgentInvalid     = &Error{"invalid user-agent"}
)

APIErrors

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"`
	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 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 {
	DatabaseService
	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 Format

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

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 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 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 {
	Sort      string // year, title, format
	SortOrder string // asc, desc
	Page      int
	PerPage   int
}

Pagination ...

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

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 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"`
	Next string `json:"next"`
}

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