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 |
Example Response
{ |
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.