Just a quick note that the API is not the best way to do one-off metadata updates of all your data. Downloading a copy of your metadata, editing, then reuploading as a CSV is what most of our clients prefer for large changes.
The API uses the standard fieldset, rather than whatever your site has them named, so you don’t have to recode your integration if someone renames something. Meaning if you’ve renamed Catalog into Katalog because your site is in German, you still need to send in data with the standard Catalog field.
/api/tracks/getAvailableFields
This request will return the standard fieldset for your site. This matches the CSV Metadata export format, if you do an export from Admin Panel → Manage Metadata → Export Data.
Try it out: https://brentracks.sourceaudio.com/api/tracks/getAvailableFields?token=436-efd0e91972231f705457d444cbc505f0
Interested Parties data has multiple values (and subvalues), so they’ll come back like Writer {X} First Name. Publishers have multiple collection interests, so they’ll be formatted like Publisher {X} Collection Share Percentage {Y}. You’ll set the data exactly the same way and the indexing starts at 1.
Custom fields are specific to your site, so they need to be marked differently in case you have a custom field that conflicts with a standard one. For example, you would send in something like ...&meta[Custom: External ID]=123314. Your custom fields will show up in the standard fieldset, so you can see what’s on there. If you need to add a custom field, you’ll need to do it from the site admin panel at Admin Panel → Manage Metadata → Fields → Custom Fields.
/api/tracks/update
| Param | Required | Description |
|---|---|---|
| track_id | yes | The id of the track you wish to update |
| meta | yes | The array, keyed to the standard fieldset, with the updated metadata |
Example Response
{ |
Album Art
Album Artwork will automatically be pulled from your ID3 tags, but you can also set it manually either using /api/tracks/update or /api/tracks/albumArtUpdate URLs. Since we’re doing this on the track level, the album is updated each time, and the import process is distributed, you cannot guarantee what track will be last and finally update the album, thus the safest method will be to set the url on each track and let it do it each time. The final sizes created are at the native size and 300x300. Make sure you supply a square image if you want to avoid stretching. This can be done as part of other setMetadata parameters, it’s just broken out into its own section for clarity. If you’re having trouble with a URL, check for special characters and try encoding the URL before sending the request. Alternatively, you can send the URL in a POST request, passing meta[Album Artwork] as the key and the URL as the value in the POST body.
Example:
/api/tracks/update?track_id=12345&meta[Album Artwork]=http://mydomain.com/image.jpg&meta[Album Artwork Type]=jpg&token={token-goes-here}
Note: Album Artwork and Album Artwork Type are not in the standard fieldset and will not be returned.
Album Art Update
Update album artwork on a per-track basis.
/api/tracks/albumArtUpdate
| Param | Required | Description |
|---|---|---|
| track_id | yes | The id of the track you wish to update with the album artwork |
| url | yes | The direct URL to an image satisfying the album art requirements above. |
Example Response
"Album Artwork Result": { |
Nesting Sort Position
If you have a track with alternates, you can sort how those alternates are ordered when the track is expanded on the site. This field is called Nesting Sort Position. It is set only and only for the Tracks API. It will not work in the Import API. It will not return in searches or getById. The value defaults to 0, and it takes a few minutes to take effect.