AcousticBrainz API documentation Outdated

AcousticBrainz
1

Just reading the weekly meeting notes and found that AcousticBrainz does already have a way to get data for multiple mbids (at least for low level) - https://acousticbrainz.readthedocs.io/api.html#get--api-v1-low-level

e.g

https://acousticbrainz.org/api/v1/low-level?recording_ids=96685213-a25c-4678-9a13-abd9ec81cf35;abb11b76-3103-4716-b388-434c4479367a

But this is not documented on the official site, https://acousticbrainz.org/data - could this be updated ?

1 Like
2

Also looking at the data returned is it valid at the top level to have recordingId : Offset: lowlevel should it not be more recordingId: recordingId, offset :Offset: lowlevel: lowleveldata

i.e what I mean is that shouldn’t recordingId and offset have a label to identify that the value is a recording id or an offset ?

3

Thanks for bringing this to our attention! I guess we shouldn’t duplicate this documentation - I think we can change the page on https://acousticbrainz.org/data to describe the data and link to the API reference on readthedocs.

Regarding the dictionary format, the idea of putting query parameters (mbid, offset) as the dictionary key means that you can access the data that you want without having to iterate through results and comparing them,
e.g. in python with

result = {"mbid1": {"offset1": {document},
                    "offset2": {document}},
          "mbid2": {"offset1": {document}}
}

you can do
result[mbid][offset] to directly get the result that you want. If it was a list of dictionaries with keys mbid, offset, data then you would always have to iterate through the list checking each element to find a specific mbid/offset.

Note that in the case of the example query you gave offset is implicitly 0, as explained in the docs.

1 Like
4

Great, but would be good to add some example urls into readthedocs it took me a while to work out the url from the documentation alone.

Okay, a map rather than a list, thats fine (i still find Xml easier to understand than json)

5

OK, we’ll look at improving this documentation as well. Does something like https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/#get--users-(int-user_id)-posts-(tag) look good?

6

Yes, except it doesnt include a full clickable url that user can just click on to see results