OpenAura JavaScript SDK

The OpenAura JS SDK 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({
    stream_key: "YOUR_STREAM_KEY",
    info_key: "YOUR_INFO_KEY"
})

Note if you have an evaluation API key, it should work for both the stream and info APIs.

Artist Info API

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

• Bio

• Artist Profile Image

• Style Tags

• An Artist Fact Card

• Artist "Cover" Photos (large format, landscape images which can be used as a background).

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 all 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.

Stream API

Once the SDK is initialized, you can also make queries into an artist's aura or stream using the stream 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 origined 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

Building

This project uses Gulp to build. Assuming you have Node.js and npm installed, cd into the project directory and:

$ npm install -f gulp

$ npm install

To build, run gulp package. You should end up with a single file in build/js/oa-all.js. You can open (and play around with) build/index.html, which includes the JS in a script tag.