So, now we've covered the basics of OData as well as some more search-specific concepts of using OData against the Rhymba Search APIs. We've also gone through the collections, Artists(), Albums(), and Media(), and what properties they expose.
If that were all, you would have enough information to get started creating the majority of typical store, widget, or application experiences. But where's the fun in the basics?
Enter Advanced Queries.
Caution: Here May Be Dragons
A preface to these advanced queries: they often rely on tricks & techniques that are subject to change, or they may be capable of slowing down the response time of Rhymba. Meaning, we're not showing you these examples in the interest of "go out and use the heck out of 'em", but rather more as examples of some interesting & powerful things you can do with OData + Rhymba.
With all that out of the way... let's get on to the good stuff.
Querying By Genres & Other Properties That Are Collections
By now, you've seen how to query by most of the standard properties of a collection item, such as string- or integer-based fields. But, what if you want to query against a property that's a collection? Say, for instance, an album's genres property, which is a collection of Genres?
Remember this Exampler from the search OData page?
You can actually query to find albums that have content in a specific genre using the $filter genres/any(g:g/id eq some_genre_id) using a custom filter. Check out the query below; this will return albums that are in the genre ID of 65, which is Rock:
Developers familiar with lambda expressions should recognize the similar structure. Let's take genres/any(g:g/id eq 65) piece-by-piece to explain what's going on here.
genres/, with the slash, indicates that we're querying subproperties of items in the genres collection, which is itself a property of our Album objects.
Then, any() is a function that means "return any objects where this condition is true". The condition is coming up.
Next, we give a shorthand variable name for items in the genres collection, g:. This will be used in our comparison condition coming up.
The magic happens in g/id eq 65. The slash once again indicates we're querying subproperties; in this case, we're querying the genre by ID, and the ID is 65 — Rock.
If you're following all of this, then you're wondering if genres/any(g:g/name eq 'Rock') would also work. What do you think, will it?
Spoiler alert: yep, it works just fine. Querying by ID though is often marginally faster, though, and is generally the preferred method since you don't have to worry about single-quotes and escaping text.
If you want to search for two genres, you can combine them using "and" or "or" and judicious usage of parentheses as below:
Searching for both "Jazz" and "Rock" with an and only returns albums that have tracks in both genres.
And, you can of course combine & collapse it into a single lambda-esque expression like so: genres/any(g:g/name eq 'Jazz' and g/name eq 'Rock') instead of the two statements joined by the "and". Go ahead and replace the Filter above with this condensed version — you should receive the same results.
You can of course combine this custom $filter with keywords and all the other goodies you've come to expect. Try it out!
Working With id_cdl
As described on the Search > OData page, our custom query parameter id_cdl allows you retrieve information on a collection of content in the form of a comma-separated array of integer IDs. This differs from retrieving a single specific piece of content using the standard OData method as described on the Getting Started > Intro to OData page (by using a URL like Media(1234)).
Let's see this in action using our Exampler widget. Note: the items you request are, of course, subject to whitelisting rules, so the examples below may not work if your system isn't whitelisted for the content used in this example.
First, a standard id_cdl query. This example retrieves three albums by ID:
You can also use id_cdl to exclude specific content IDs by prefacing them with a -, making them negative integers. Let's do a search for "Face Value", but exclude the ID for Phil Collins's album:
If you remove the value -240732 for id_cdl above and re-run the example, you'll see Phil Collins's album show up; it's excluded from the results because it's a negative integer.
Note: Mixing and matching negative and positive integers in the array can have some unexpected results at this time.
If your service agreement with us allows for usage in multiple territories, you can use OData $filter to easily retrieve content specific to a geographic region. First, let's deconstruct the geo results for content. Note: if your access token is valid for US-only, the principles are the same — but the content that's returned to you will already be pre-filtered to only show content valid for your use in the United States. Depending on your system/application rights, however, you can still see the available geographic information.
Go ahead and run the example below, and then we'll go from there.
So, let's say you wanted to only show content available for digital download in Australia. First, you'd check out the page containing all of our Country Codes to find Australia's, which is AU. With that information, you arrive at the following filter: geos/any(g:g/country_code eq 'AU'). Try it out below:
You can see the difference in the results if you remove the filter above; exampler will remove that parameter from the URL and show you all content matching your keyword with territories expanded.