API access to Custom Fields

[LP-collector]

I have added two Custom Fields to my Discogs collection. These are "Shelf" and "Position." (Note that these correspond to data that is collected by an app called "Record Scanner." I do not work for them by the way.)

These fields are working properly within Discogs. If I export my collection, they appear.

Collection Media Condition, Collection Sleeve Condition, Collection Notes, Collection Shelf, Collection Position
Very Good (VG), Very Good Plus (VG+), Row 1 Col 3, 1
Very Good Plus (VG+), Good (G), Row 1 Col 3, 2

However, I can't figure out how to access Shelf and Position. There is an API function to “List Custom Fields" but I can't figure out where, or if, it exists in this package.

Eventually, I will want to import my 2000+ records from Record Scanner into my Discogs Collection (Not Inventory. I don't want to sell anything through Discogs for now.)

Full disclosure: I have sent questions to Discogs support as well as the Record Scanner folks, but since I don't know where the problem is coming from, I wanted to add in the Discogs_Client community.

[JOJ0]

This object contains them in the notes property, it returns a list of dictionaries with all your custom fields if I'm not mistaken: https://python3-discogs-client.readthedocs.io/en/latest/discogs_client.models.html#discogs_client.models.CollectionItemInstance

[LP-collector]

I don't think the problem is accessing the Notes Field.

Here is code to print out the Collection Items.

import discogs_client
d = discogs_client.Client('my_user_agent/1.0', user_token=***)
me=d.identity()
print(me)
#   print the releases in the folder
for item in me.collection_folders[2].releases:
    print(item)
#   Now pick a release to find collection items
alb=me.collection_items(8201511)
# 
def print_collection_items(instances):
    for page_number, instance in enumerate(instances, start=1):
        print(f"Page {page_number}")
        print(f"ID: {instance.id}")
        print(f"Instance ID: {instance.instance_id}")
        print(f"Rating: {instance.rating}")
        print(f"Folder ID: {instance.folder_id}")
        print(f"Notes: {instance.notes}")
        print(f"Date Added: {instance.date_added}")
        print(f"Release: {instance.release}")
        print(f"Shelf: {instance.shelf}")
        print("\n")

# And print the items
print_collection_items(alb)

The output from the "notes" field is:

Notes: [{'field_id': 1, 'value': 'Mint (M)'}, {'field_id': 2, 'value': 'Mint (M)'}, {'field_id': 3, 'value': 'sealed'}]

The extra Custom Fields are not in the Notes field. It contains "Media condition" "Sleeve condition" and "Notes."

It seems that Discogs has hidden the Custom Fields somewhere else.

[LP-collector]

And by the way, it errors on "shelf" and I assume it would also error on "position."

AttributeError: 'CollectionItemInstance' object has no attribute 'shelf'

[JOJ0]

ok that's bad news. This is the implementation of CollectionItemInstance, and I'm scratching my head around the TODO comment form an ancient developer we don't know anymore ;-) @AnssiAhola what would you make of it? The second comment line! The developer ment that the notes field should be a first order item, i.e. use PrimaryAPIObject which requires to have an endpoint of it's own, like the "List Custom Field" endpoint we mentioned above. Does that make sense?

discogs_client/discogs_client/models.py

Lines 712 to 727 in f18fc8c

	# TODO: folder_id should be a Folder object; needs folder_url
	# TODO: notes should be first-order (somehow); needs resource_url
	class CollectionItemInstance(PrimaryAPIObject):
	id = SimpleField() #:
	instance_id = SimpleField() #:
	rating = SimpleField() #:
	folder_id = SimpleField() #:
	notes = SimpleField() #:
	date_added = SimpleField(transform=parse_timestamp) #:
	release = ObjectField('Release', key='basic_information') #:
	def __init__(self, client, dict_):
	super(CollectionItemInstance, self).__init__(client, dict_)
	def __repr__(self):
	return '<CollectionItemInstance {0!r} {1!r}>'.format(self.id, self.release.title)

@LP-collector what you could certainly do in the meantime, is try to use a regular curl to:

• double check if your fields really are "generally" available via the API using the "List Custom Fields" endpoint.
  BTW this endpoint's docs tells us Retrieve a list of user-defined collection notes fields. These fields are available on every release in the collection. -> which says, they must be somewhere :-)
• use a regular curl and see if the data is contained in what you get from the two possible endpoints:
  • https://www.discogs.com/developers#page:user-collection,header:user-collection-collection-items-by-release
  • https://www.discogs.com/developers#page:user-collection,header:user-collection-collection-items-by-folder
  • Hint: pipe the output through the jq tool to get an easier human-parsable output! It's availalbe via homebrew on macOS and generally on any Linux distro. Windows dunno. Ask google/gpt!

[AnssiAhola]

Not sure what that TODO comment means exactly, maybe they were thinking about implementing its own endpoint at some point? hmm...

I tested a bit and it seems the custom fields are included in the notes property ONLY when they are defined, so for instances/releases those fields are left empty, they would not be included in the api response.

collection_folder = client.identity().collection_folders[0]
instances = collection_folder.releases
for instance in instances:
    print(instance.fetch("notes")) 

>>> None
>>> None
>>> [{'field_id': 1, 'value': 'Poor (P)'}, {'field_id': 2, 'value': 'Poor (P)'}]
>>> [{'field_id': 1, 'value': 'Poor (P)'}, {'field_id': 2, 'value': 'Poor (P)'}]
>>> [{'field_id': 1, 'value': 'Poor (P)'}, {'field_id': 3, 'value': 'Sleeve is missing'}]
>>> [{'field_id': 1, 'value': 'Fair (F)'}, {'field_id': 2, 'value': 'Fair (F)'}]
>>> None
>>> None

If we want, we could implement a method and classes for fetching/listing the custom fields so you'd at least have access to them and can find out the custom field name by using the field_id from above

For example something like

custom_fields = me.collection_fields() # calls /api/{username}/collection/fields
for note in instance.notes:
   print(custom_fields.find_by_id(note.field_id).name)    

pseudo code, might not work 😛

[LP-collector]

Aha. I added my custom fields at least a week or so ago, so they are "defined" and appear for each release. However, none of them included any data until a few days ago. I entered data manually on one Collection Item and ran code on it. Nothing came back. Some days (hours) later, the same code returns those fields.

In any case, you are correct. I retrieved the data for a different release with blank custom fields. The Custom Fields were not even reported. Put data into both fields - Code now shows them.

Since Discogs is using the notes field for their standard "Media condition" "Sleeve condition" and "Notes" and then allows users to add N custom fields, I"d rather have seen an Empty or NULL or something to indicate the presence of the field in the collection. Might have saved a lot of digging.

[LP-collector]

Ah, the magic of other people's databases!

Rather than set up to use curl (being Windows and having to learn more coding than I want to.), I ran the same code as above today and the results are different. Maybe weird updating processes overnight at Discogs. To sort of simplify, I took the endpoint as in the API and used a requests.get and some JSON-y stuff. Here is the code:

import requests
import discogs_client
import json
d = discogs_client.Client('my_user_agent/1.0', user_token='...')
# Make sure I'm real
me=d.identity()
print(me)
username = '***'
payload = {'value': username}

url = f'https://api.discogs.com/users/{username}/collection/fields'
headers = {
    'Authorization': 'Discogs token=...',
    'Content-Type':'application/json'
}
response = requests.get(url, data=json.dumps(payload), headers=headers)
t=response.text
print(t)

And the results are:

{"fields":[{"id":1,"name":"Media Condition","type":"dropdown","position":1,"public":false,"options":["Mint (M)","Near Mint (NM or M-)","Very Good Plus (VG+)","Very Good (VG)","Good Plus (G+)","Good (G)","Fair (F)","Poor (P)"]},{"id":2,"name":"Sleeve Condition","type":"dropdown","position":2,"public":false,"options":["Generic","No Cover","Mint (M)","Near Mint (NM or M-)","Very Good Plus (VG+)","Very Good (VG)","Good Plus (G+)","Good (G)","Fair (F)","Poor (P)"]},{"id":3,"name":"Notes","type":"textarea","position":3,"public":false,"lines":3},{"id":4,"name":"Shelf","type":"textarea","position":4,"public":true,"lines":1},{"id":5,"name":"Position","type":"textarea","position":5,"public":true,"lines":1}]}

Lo and behold, my 2 custom fields are now showing up as fields 4 and 5 in "Notes." I am also able to write to those fields and it shows up in my collection on Discogs. You really have to burrow deeply in the URL to get to a specific Notes field.

import requests
import json
# Define your parameters
username = '***'
folder_id = 1
release_id = 8201511
instance_id = 1917135456
field_id = 4
new_value = 'This is a test'

# Define the API endpoint
url = f'https://api.discogs.com/users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}/fields/{field_id}'

# Define the payload with the new value
payload = {'value': new_value}
headers = {
    'Authorization': 'Discogs token='...',
    'Content-Type':'application/json'
}
# Make the PUT request to update the field value
response = requests.post(url, data=json.dumps(payload), headers=headers)

# Check the response status
if response.status_code == 204:
    print('Field value updated successfully!')
else:
    print(f'Error: {response.status_code} - {response.text}')

So in the end, I think I answered my own questions. Do you agree?

[JOJ0]

Well @LP-collector, like Joe Cocker said: "With a little help from a friend... ;-)

I sometimes call it "The teddybear principle: You explain stuff to someone else, which brings you closer to finding a solution yourself.

(and yes it actually were the Beatles that said that ;-)

[JOJ0]

I've set my very first reply as the immediate answer since it is the most straightforward and still is correct (which we only could confirm after investigating more closely. Thanks for that again!). I just corrected in the post that not a dictionary but a list of dictionaries is returned.

Accepting your last answer could be misleading to future readers since it uses requests instead of python3-discogs-client implying that access to those fields is not implemented.

Hope that's ok for you @LP-collector and thanks a lot for the question. We learned something, confirmed something and also created a useful feature request out of it. 💌