Search & OData
We've already covered a pretty good introduction to the concepts of OData in Getting Started > Intro to OData. Now it's time to delve more deeply and more greedily and really put OData to work in searching.
Search API OData URL Query Parameters
These are the OData query parameters we support as a part of a REST-link URL call to the Search API across all collections (e.g. Albums, Artists and Media), in alphabetical order.
Note: Requires $format be set to json.
For more information about JSONP with regards to Rhymba, check out the Intro to JSONP page in Getting Started.
$expand (OData expansion select)
Allows you to display subproperties of the returned objects that are complex types and which are not returned by default.
Note: You must also include these subproperties in your $select statement.
For Media(), for example, genre is a single complex type:
Whereas, when querying Albums(), it's genres and is a collection of the genres assigned to subordinate media:
$filter (OData filter)
The $filter parameter in the search API allows for advanced searching of content based on the properties of the collection objects. The properties & metadata are discussed in-depth in each collections' information page in this section.
Note: The property values you're $filter-ing against should be wrapped in single quotes if they're strings such as titles, names, and UPCs/ISRCs. Booleans and integers are not wrapped in single quotes.
Note: Unless you really need to use $filter, you should avoid it as much as possible; because this results in a raw index query, the speed of searching can be impacted by using $filter.
The following operators and functions are supported:
|eq||Operator||Equality comparison.||upc eq '800000'|
|gt||Operator||Greater than comparison.||volumenumber gt 1|
|lt||Operator||Less than comparison.||volumenumber lt 2|
|endswith()1||Function||Function to determine if a field ends with a string. Truth value comparisons are not implemented with this function.||endswith(artist_name,'C')|
|startswith()||Function||Function to determine if a field starts with a string. Truth value comparisons are not implemented with this function.||startswith(artist_name, 'C')|
|substringof()1||Function||Function to determine if a field contains a string. Truth value comparisons are not implemented with this function. Please note that the parameter order here is different than endswith() and startswith().||substringof('Céline Dion', artist_name)|
A word about substringof(), however: bear in mind that you'll almost invariably have better results when attempting to do a text search by using the keyword parameter, described below.
1 Since Lucene is built entirely around startswith-type searches, startswith() search is near-instantaneous. However, on large collections like Media(), substringof()/contains and endswith() can take multiple seconds for a common/vague search like substringof('a', title) to complete because they result in an unindexed brute force search. We prefer that you narrow down the scope of the unindexed search with more specificity when using these queries — it will be better for not only us, but also for you (as results will be faster). In short: Proceed with care.
You can chain $filter options with a simple "and" between them, and group them within parentheses much like "if" conditions in OO languages. You can find more interesting applications of $filter on the Advanced Queries page.
Example: $filter=isexplicit eq false
$format (string) Required
Specify the format you'd like the data returned in. Valid options are json or atom.
Note: We recommend JSON, and, in case it's not obvious, JSON is required for JSONP.
id_cdl (integer array, comma-separated, with array wrapped in single quotes)
The id_cdl parameter is a custom OData query parameter we've implemented allowing you to retrieve several pieces of specific content by their Rhymba ID. This differs from retrieving a single piece of content using the standard OData method, described in the Getting Started > Intro to OData page. In other words, let's say you want to retrieve data on specific tracks in a playlist you're using in your application. You'd pass a comma-separated list of IDs to the appropriate collection endpoint (Albums, Artists, or Media) and any of that content whitelisted for your application will be returned.
You can also exclude specific IDs by prefexing them with a dash, e.g. to exclude IDs 1234 and 5678 you would do id_cdl=-1234,-5678. At present, you can't mix and match positive and negative id_cdls... well, technically, you can, but the results can be a little odd. There are more ramifications to using id_cdl covered on the Advaned Queries page.
When you include $inlinecount=allpages as a part of your URL query string, it instructs Rhymba's Search API to include a field with the total results found, regardless of any $top or $skip values specified. This is a good idea for implementations where you're adding pagination.
Run the example below both with and without the "Include inline count" checkbox enabled to see how the JSON returned shows or doesn't show the odata.count property.
The keyword parameter is a custom OData query parameter we've implemented for Rhymba that performs a textual search across various text fields of the different collection objects, powered by Lucene.NET. Common text fields are things like album titles, song titles, and artist names. In addition, keyword also takes advantage of the score returned to help order the results in a more relevant fashion. Finally, we've recently started improving keyword handling by attempting to prioritize "correct" content (e.g., trying to prioritize an artist's original release over cover versions by other artists). This is a work in-progress, and only currently applies to a small portion of our catalog — but using keyword as opposed to implementing your own search means you will continue to receive the benefits as we improve relevancy.
Note: You can only use one keyword query parameter in your query, but the keyword value can be multiple words — we split on spaces.
Note: keyword values should be wrapped in single quotes, and properly URL-escaped.
When doing a traditional text search, we almost always recommend using keyword.
Example: keyword='get lucky daft punk'
$select (string array, comma-separated)
Which specific properties of the objects returned you wish to receive.
For example, we have a ton of metadata on tracks. Sending all of the information across the wire on every request results in needless bandwidth usage and processing time. Maybe you're just interested in the track ID, album name, and album ID? Then you'd simply do $select=id,album_name,album_id in your URL query parameters. Then, the resultant JSON or XML returned will only contain those fields.
In the Exampler.js widgets throughout this documentation, we already use $select quite a bit to limit the information returned in the JSON.
Note: As mentioned above in the description for $expand, bear in mind that you must $select any properties you are $expanding for them to be returned.
The number of results to skip. Used for paging. Explained more in-depth on the Getting Started > Intro to OData page.
$top (integer) Required
The number of results to retrieve. Used for paging. Explained more in-depth on the Getting Started > Intro to OData page.
Note: If you don't include this parameter, you'll only receive a single result back. We do this to prevent a developer accidentally requesting ALL of our content!
Use the example widget below to see the results of different $skip and $top values.