You'll need to have cURL installed to follow along with the examples below.
Getting an artist id
To begin with, we're going to use the /search endpoint to get an OpenAura (and Musicbrainz along the way) artist id. This will make it easy to make subsequent queries against the API.
Suppose we want to find Taylor Swift's id, we can start by making a query against 'taylor' by setting q=taylor in the query string.
As you can see, this goes on for a bit. Let's limit our query to the top 5 results. We do this by adding limit=5 to our query string.
The results contain both oa_artist_id, which is an id unique to OpenAura, and a Musicbrainz id. We'll use the OpenAura id of 47 in the following examples.
Getting Artist Info
Artist info exposes deeper structure and metadata around each piece of data that you're concerned about. We do this by exposing our uniform wrapper around media objects, which we call a particle. Particles have a consistent structure and each wrap a piece of media, which can be of many types.
An /info call exposes the following bits of data about an artist:
- oa_anchor_id: The 'anchor id' for an artist. This is different than the oa_artist_id.
- oa_artist_id: An integer id for an artist.
- musicbrainz_gid: A string representing the Musicbrainz GID.
- name: The artist name.
- fact_card: A particle containing artist facts (DOB, band members, labels, hometown, etc.)
- tags: A particle containing genre, or "style tag" information.
- bio: A particle with a text biography for the artist.
- profile_photo: A particle with the artist's profile photo.
- cover_photo: A collection of particles which contain artist cover photos (that is, Facebook-style cover images, not album covers).
- artist_images: A collection of particles which contain images of the artist.
Let's make a query against the info API for Taylor Swift's structured data.
As you can see, this is quite a bit of data. Note that particles have a consistent structure. Particles represent the fundamental unit of rights bearing content in the OpenAura system, so we wrap them in a uniform wrapper.
Also note that each particle has a field with an array of media. The media object refers to the actual media in the particle. This can be URI, a reference to an image (usually a URI), a piece of text, or a JSON blob, among other things.
When a particle has multiple image media, these usually represent different sizes of the same image.
Accessing an Artist's Particle Set
The /particles endpoint provides an additional view into an artist's aura by exposing a larger set of particles. This set contains images, tweets, video, and audio embeds which are related to an anchor. These results are returned in paginated chunks that can be requested by the client.
Let's use the info API to grab some of Taylor Swift's aura. We'll use the artist id (47) that we found in the first example. We'll also limit the response to 10 particles by adding 'limit=10' in the query string.
Our response has some basic information about the return set, primarily, the number of particles returned and a URI reference to the next set of particles (with the same offset as the initial query). Beyond the basic facts, we have a 'particles' field which contains the result set of particles. Note that these particles are of the same structure as the particles returned in the info query.
Take a look at the API Explorer for more details on what you can do when making queries.