Search

The API search action is a direct link into the same search you use on the site, if you’re not already familiar with how filters and advanced search work on the site, please check that out. Because the filter system is so “close to the metal”, we highly recommend using advanced search to do things like searching by genre or any other simple filter. As in, instead of sending in a filter array with the genre id you parsed from a previous request, just send in the search string as “genre:rock”.

/api/tracks/search
Param Required Description
s no The search string.
show no How many records to show, defaults to your site’s value. Max 1000
pg no Page number, default is 0.
fields no The metadata fields to include. Uses array index of the field in /api/tracks/getAvailableFields call; comma-separated
custom_fields no The custom fields to include. Uses the custom field id in /api/tracks/getAvailableFields call; comma-separated
filters no Filter array (deprecated, see below)
orderby no What field to order by
dir no What direction to order the “order by” field
combineMasters no Whether or not to group master and alt tracks together or return them all separately
onlyMasters no Whether or not to only show master tracks
master_id no If supplied, will return alts with this master id
includeMasterWithAlts no If set to 1, and you search with a master_id, then the track you provided will also be returned.
similarTo no If set to a track id, it’ll show results that have similar metadata
catalog_id no Used to filter by Catalog ID
label_id no Used to filter by Label ID
album_id no Used to filter by Album ID
maf no Music Access Filter id to filter by
raw no Includes a new property on each track track that contains the raw SA Track object. Might be easier to parse, but is substantially more data
ai no Used to submit a natural language search. If included, the response will have an ai section that includes the same info the site returns

Try it out: https://brentracks.sourceaudio.com/api/tracks/search?s=genre:electronic&token=436-efd0e91972231f705457d444cbc505f0

Example Response

{
"search": "genre:electronic",
"count": 5,
"page": 0,
"show": 15,
"filters": {
"label": {
"60481": {
"text": "Brentracks",
"value": 60481,
"count": {
"count": 5
}
}
},
// ...
}
},
"trackInRequest": 5,
"tracks": Array[5][
{
"SourceAudio ID": 12074528,
"Title": "Centurion",
"Artist": "Brent Phillips",
"Album": "Chiptrax",
"Composer": "Brent Phillips",
"Catalog": "Brentracks",
"Publisher": "",
"Has Vocals": 2,
"Explicit": 2,
"BPM": 0,
"Duration": 44.64329167,
"Description": "New theme for the 100th episode.",
"Release Date": 1436841161,
"Lyrics": "",
"Filename": "Centurion.mp3",
"Track Number": 0,
"Label": "Brentracks",
"Style Of": "",
"Master ID": 12074528,
"ISRC": "",
"ISWC": "",
"Album Description": "An album of music, made by Brent.",
"Album Code": "BRE2002",
"Album Release Date": 1402006279,
"Album Genre": null,
"Last Update Date": 1498604451,
"Tempo": "Unspecified",
"Genre": "Electronic, Soundtrack / Orchestral / Score",
"Cue Type": "Songs",
"Mood": "chill, epic",
"Style": "digital, orchestral",
"Album ID": 696325,
"Album Artist": null,
"Album Image": "/user_data/35146/1498604451-35146-150.png",
"Writer 1 First Name": "Brent",
"Writer 1 Last Name": "Phillips",
"Writer 1 Company": "",
"Writer 1 PRO Affiliation": null,
"Writer 1 CAE/IPI": null,
"Writer 1 Ownership Share": 100,
"Writer 1 Role": "Composer/Author",
"Writer 1 Publishing Interest": null,
"Custom: Program": "Garageband",
"Out Of Date": false
},
// ...
}

Filtering

As I alluded to above, we’ve changed the way we’re recommending you handle this from previous documentation. In the old way of filtering, you had to build a filter array from the ids in the filters property of the the response object. This makes a lot more sense when you’re actually on SourceAudio, since you’re filtering the results you already have, but it can get a bit complicated to use through the API.

You should instead filter by just doing advanced searches through the search string s. You can build them yourself on the site by clicking the “hamburger” menu on the right side of the search bar, and then just pass it into the search API and you’ll get the same results.

Filename Search

This feature is also available on the site, but has been extra useful to our API clients. You can search for any track by its filename, as long as you include an ending. What ending you include is not important. Just use .mp3 to keep it simple. If you have unique filenames (and I hope you do), then you can use this to quickly find your tracks by your own external system.

Sorting

The orderby and dir parameters work much like you’d expect, except that the field names do not match the names in the standard fieldset. The most commonly sorted fields are release_date and title, but if you want to sort by something else, I recommend you do a search on the site and inspect o parameter that’s sent in the AJAX call. We support a lot of fields, and it changes a lot per site, so I’d rather leave this answer incomplete and teach you how to fish than give you a list that might not be right.