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.
$expand (OData expansion select)
Allows you to display subproperties of the returned objects that are complex types and which are not returned by default.
For example, when querying Albums, genres 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:
| Name | Type | Description | Example |
|---|---|---|---|
| eq | Operator | Equality comparison. | upc eq '800000' |
| gt | Operator | Greater than comparison. | volumenumber gt 1 |
| lt | Operator | Less than comparison. | volumenumber lt 2 |
| not | Operator | Not comparison. | |
| 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 Medias, 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)
Specify the format you'd like the data returned in. Valid options are json or atom. json is the default.
$count=true (Non-variable)
When you include $count=true 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.
keyword (string)
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).
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.
$skip (integer)
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.