This repository has been archived on 2023-04-13. You can view files and clone it, but cannot push or open issues or pull requests.
go-discogs/README.md

136 lines
4.6 KiB
Markdown
Raw Normal View History

2016-02-03 15:31:59 +00:00
# REST API 2.0 Discogs.com client
2016-02-04 12:30:49 +00:00
2017-02-14 19:01:50 +00:00
go-discogs is a Go client library for the [Discogs API](https://www.discogs.com/developers/). Check the usage section to see how to access the Discogs API.
2020-03-24 10:11:44 +00:00
The lib is under MIT but be sure you are familiar with [Discogs API Terms of Use](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use).
### Features
2016-03-11 14:41:48 +00:00
* Database
* [Releases](#releases)
* Release Rating
* Master Releases
* Master Versions
* Artists
* Artist Releases
* Label
* All Label Releases
2018-03-21 18:17:40 +00:00
* [Search](#search)
* [User Collection](#user-collection)
* Collection Folders
* Folder
* Collection Items by Folder
* Collection Items by Release
* [Marketplace](#marketplace)
* Price Suggestions
* Release Statistics
2016-03-11 14:41:48 +00:00
Install
--------
go get github.com/irlndts/go-discogs
2016-03-11 14:41:48 +00:00
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](https://www.discogs.com/developers/#page:home,header:home-general-information).
```go
2016-03-11 14:54:33 +00:00
import "github.com/irlndts/go-discogs"
```
2018-01-22 18:03:06 +00:00
Some requests require authentication (as any user). According to [Discogs](https://www.discogs.com/developers/#page:authentication,header:authentication-discogs-auth-flow), 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](https://www.discogs.com/settings/developers).
2017-02-14 19:01:50 +00:00
```go
2020-03-24 10:11:44 +00:00
client, err := discogs.New(&discogs.Options{
2018-03-12 16:30:58 +00:00
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
2020-03-24 10:11:44 +00:00
URL: "https://api.discogs.com", // optional
2018-03-12 16:30:58 +00:00
})
2016-03-11 14:41:48 +00:00
```
2018-01-22 18:01:29 +00:00
#### Releases
2016-03-11 14:41:48 +00:00
```go
release, _ := client.Release(9893847)
2018-01-22 18:01:29 +00:00
fmt.Println(release.Artists[0].Name, " - ", release.Title)
// St. Petersburg Ska-Jazz Review - Elephant Riddim
2016-03-11 14:41:48 +00:00
```
2017-02-14 19:01:50 +00:00
#### Search
2018-03-17 19:41:43 +00:00
Issue a search query to discogs database. This endpoint accepts pagination parameters.
2017-02-14 19:01:50 +00:00
Authentication (as any user) is required.
2018-03-17 19:41:43 +00:00
Use `SearchRequest` struct to create a request.
2017-02-14 19:01:50 +00:00
```go
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)
2018-03-17 19:41:43 +00:00
ReleaseTitle string // search release titles (optional)
2017-02-14 19:01:50 +00:00
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
2017-02-14 19:01:50 +00:00
}
```
```go
2018-03-17 19:41:43 +00:00
request := discogs.SearchRequest{Artist: "reggaenauts", ReleaseTitle: "river rock", Page: 0, PerPage: 1}
search, _ := client.Search(request)
2017-02-14 19:01:50 +00:00
for _, r := range search.Results {
fmt.Println(r.Title)
}
```
#### User Collection
Query a users [collection](https://www.discogs.com/developers#page:user-collection).
##### Collection Folders
```go
collection, err := client.CollectionFolders("my_user")
```
##### Folder
```go
folder, err := client.Folder("my_user", 0)
```
##### Collection Items by Folder
```go
items, err := client.CollectionItemsByFolder("my_user", 0, &Pagination{Sort: "artist", SortOrder: "desc", PerPage: 2})
```
##### Collection Items by Release
```go
items, err := client.CollectionItemsByRelease("my_user", 12934893)
```
#### Marketplace
Query a user's [marketplace](https://www.discogs.com/developers/#page:marketplace)
##### Price Suggestions
Retrieve price suggestions for the provided Release ID
```go
suggestions, err := client.PriceSuggestions(12345)
```
##### Release Statistics
Retrieve marketplace statistics for the provided Release ID
```go
stats, err := client.ReleaseStatisctics(12345)
```