OpenAura JavaScript SDK

The OpenAura JS SDK (beta) provides simple access to the OpenAura API via a simple JavaScript interface.

Installation

Download the minified JS here and include it in your HTML via a script tag.

Usage

Setting up your API Key

The SDK will load the OA modules into the OA variable in your global namespace. You can access the ArtistInfo and Aura modules from within this namespace.

To start, you'll need to initialize the client libs with your API key. This can be done by passing your API keys to the initialize method:

OA.initialize({
    api_key: "YOUR_API_KEY",
})

Artist Info API

The Info API is designed to provide you with access to data and assets which can be used to create quality artist page experiences for your users. Artist Info responses typically include the following information about a given artist:

-Bio

-Fact card

-Several artist images

In the JS SDK, you make queries into the Artist Info API with the ArtistInfo module. The ArtistInfo module provides three "fetch" methods which allow you to access ArtistInfo objects via OpenAura artist id, Musicbrainz GID, or OpenAura anchor ID.

All fetch queries follow the same general format. Each takes an ID and a callback function that takes an ArtistInfo object as a parameter, which is executed once the API returns.

Here's a simple example, using OpenAura artist id 71 (Pearl Jam):

OA.ArtistInfo.fetchByOaArtistId(71, function (artistInfo) {
    console.log(artistInfo.name());
});

See the reference for details on working with ArtistInfo objects.

Particles API

Once the SDK is initialized, you can also make queries into an artist's aura or stream using the particles API. Here we make a query against OpenAura artist id 47 (Taylor Swift). In the callback, we grab the PartcicleCollection from the returned Aura, and call its each() method, printing the id of each returned particle:

OA.Aura.fetchByOaArtistId(47, function (aura) {
    aura.particles().each(function(x) {
        console.log(x.id());
    });
});

5286c81576f96fcc3100054c
5286c81576f96fcc31000551
5293c7a776f96f73ce000301
52b0e6a0aea68d506c01d1c0
52b0e6a0aea68d506c01d1cc
52b0e6a0aea68d506c01d1d0
52b0e6a1aea68d506c01d1d6
52cda30aaea68d23720014a1
52cda30aaea68d23720014a5
52cf1bc8aea68dca30059505

In this next example, we use make the same query, but in this case, we use the ParticleCollection's filterByProvider method to only return those particles which originated from the artist's Twitter account:

OA.Aura.fetchByOaArtistId(47, function (a) {
    a.particles().filterByProvider("twitter").each(function(x) {
        console.log(x.id());
    });
});

52cda30aaea68d23720014a1
52cda30aaea68d23720014a5
52cf1bc8aea68dca30059505 

In this last example, we use the ParticleCollection's withMediaWithin method to only return particle which have media (most likely video or images) within a certain range of pixel sizes. In this case, we're filtering for particles that have media objects which are at least 0x0 pixels, and at most 1000x3000 pixels:

OA.Aura.fetchByOaArtistId(47, function (a) {
    a.particles().withMediaWithin(0, 0, 1000, 3000).each(function(x) {
        console.log(x.id());
    });
});

5286c81576f96fcc3100054c
5286c81576f96fcc31000551
5293c7a776f96f73ce000301
52cda30aaea68d23720014a1

SDK API Reference

The SDK reference is provided in the form of annotated source to serve as an example of how you might build your own library using the OpenAura API. Connection details are handled in api.js.

The following modules represent useful data structures built around the API:

  • Search - A wrapper object for search calls. Acts as a factory class for ArtistInfo and Aura on exact calls or returns a collection of results.
  • SearchResult - SearchResults collection operations and Result object.
  • ArtistInfo - A wrapper object for /info calls. Acts as a factory class and manages connection details for the info API.
  • Aura A wrapper object for /particles calls. Acts as a factory class and manages connection details stream API.
  • FactCard - A data structure representing a collection of facts about an artist.
  • Media An object representing the actual media in a particle.
  • MediaCollection - A collection which provides convenience methods for working with multiple Media objects.
  • Particle - A Particle represents a single visual asset (bio, tweet, image, video, etc.)
  • ParticleCollection A collection which provides convenience methods for working with multiple Particles.
  • Source An object which represents an individual source of particles (Twitter user, Facebook page, etc.)