l

ArtistLink API

Build apps with artist metadata, media and offers


Topspin ArtistLink is a REST API that provides access to artist metadata, media and offers from Topspin GoDirect artists. Artists use the GoDirect interface to update their profile, bio, images, songs, videos, products and offers... and developers then use ArtistLink to build great apps for fans around content that comes directly from artists.

Here's how it works:

  1. Email us via the form at right and we'll send you a key
  2. Build something awesome, making sure you include a link to GoDirect so artists know how to update content in your app
  3. Send us feedback and updates, so we can make the API better and promote your app to artists

Navigation through the docs is accessible on the left side of the page.


^ Get Started

Get access to ArtistLink:

loading...

U The Account Object

The Account object contains data about a single artist within GoDirect.

You can query the API to retrieve information about a particular artist or list all artists.

Attributes

id:
integer
name:
string
industry:
string
genre:
string
active_from:
timestamp
bio:
string or null
city:
string
country:
string
state:
string or null
state will be blank if the country is not "United States"
label:
string
facebook:
string or null
twitter:
string or null
soundcloud:
string or null
tunecore:
string or null
youtube:
string or null
vimeo:
string or null
instagram:
string or null
songkick:
string or null
flickr:
string or null
wordpress:
string or null
tumblr:
string or null
foursquare:
string or null
website_url:
string or null
uri:
string
updated_at:
timestamp
created_at:
timestamp

Z Example Code

{ id: 1, name: "Name", industry: null, genre: "Genre", label: "Label", country: "Country", city: "City", state: "State", website_url: "http://www.url.com", bio: "Bio", active_from: "2011-01-02T00:00:00Z", created_at: "2012-07-05T19:45:48Z", updated_at: "2012-08-20T20:46:10Z", facebook: "facebook", twitter: "twitter", soundcloud: "soundcloud", tunecore: "tunecore", youtube: "youtube", vimeo: "vimeo", instagram: "instagram", songkick: "songkick", flickr: "flickr", wordpress: "wordpress", tumblr: "tumblr", foursquare: "foursquare", uri: "/home/accounts/1.json", onebigthing_enabled: true, onebigthing_embed: \"<iframe id=\"obtFrame\" name=\"obtFrame\" src=\"http://d6plqejwhskqm.cloudfront.net/home/accounts/20 /mtv_artist_banner?1346343713\" frameborder=\"0\" width=\"100%\" height=\"324px\" scrolling=\"no\"></iframe>", mtv_artist_banner_enabled: true, mtv_artist_banner_embed: "<iframe id=\"obtFrame\" name=\"obtFrame\" src=\"http://d6plqejwhskqm.cloudfront.net/home/accounts/20 /mtv_artist_banner?1346343713\" frameborder=\"0\" width=\"100%\" height=\"324px\" scrolling=\"no\"></iframe>", mtv_id: null }

Retrieving an Account

Retrieves information about a specific Account.
Requires the Account's id.

Arguments

id:
required
The unique identifier of the Account

Returns

Returns an Account object if a valid id argument has been supplied. Otherwise, returns error json.

Get Account


DEFINITION

GET http://api.artistlink.com/home/accounts/1.json

EXAMPLE REQUEST

curl http://api.artistlink.com/home/accounts/1.json?auth_token=abc123

EXAMPLE RESPONSE

{ id: 1, name: "Name", industry: null, genre: "Genre", label: "Label", country: "Country", city: "City", state: "State", website_url: "http://www.url.com", bio: "Bio", active_from: "2011-01-02T00:00:00Z", created_at: "2012-07-05T19:45:48Z", updated_at: "2012-08-20T20:46:10Z", facebook: "facebook", twitter: "twitter", soundcloud: "soundcloud", tunecore: "tunecore", youtube: "youtube", vimeo: "vimeo", instagram: "instagram", songkick: "songkick", flickr: "flickr", wordpress: "wordpress", tumblr: "tumblr", foursquare: "foursquare", uri: "/home/accounts/1.json", onebigthing_enabled: true, onebigthing_embed: \"<iframe id=\"obtFrame\" name=\"obtFrame\" src=\"http://d6plqejwhskqm.cloudfront.net/home/accounts/20 /mtv_artist_banner?1346343713\" frameborder=\"0\" width=\"100%\" height=\"324px\" scrolling=\"no\"></iframe>", mtv_artist_banner_enabled: true, mtv_artist_banner_embed: "<iframe id=\"obtFrame\" name=\"obtFrame\" src=\"http://d6plqejwhskqm.cloudfront.net/home/accounts/20 /mtv_artist_banner?1346343713\" frameborder=\"0\" width=\"100%\" height=\"324px\" scrolling=\"no\"></iframe>", mtv_id: null }

SUBMIT FAN EMAIL FOR ACCOUNT


DEFINITION

GET http://api.artistlink.com/home/fans.json

EXAMPLE REQUEST

curl --data "auth_token=abc123&email=test@example.com&account_id=1&
acquired_by=curltest" http://api.artistlink.com/home/fans.json


EXAMPLE RESPONSE

Returns the account object where the email was submitted:

httpclient.post("http://api.artistlink.com/home/fans.json", # query params: { auth_token: auth_token, email: params['Body'], account_id: 7, acquired_by: 'FanFi' } )

List All Accounts

Lists Accounts in order of their creation date.

Arguments

genre:
optional
Return artist accounts falling within a specified genre.
count:
optional, default is 10
The number of Accounts to be returned. Can range between 1 and 100 Accounts.
offset:
optional, default is 0
The offset to the array of Accounts to be returned. The Accounts requested will be returned starting at this number.
name:
optional
Filters accounts by name.

Returns

An array containing up to count Accounts, starting at the offset index. Each entry in the array will be an Account object. If no more Accounts are available, the resulting array will be empty. This request should never return an error.

List Accounts


DEFINITION

GET http://api.artistlink.com/accounts.json

EXAMPLE REQUEST

curl "http://api.artistlink.com/home/accounts.json?auth_token=abc123"

EXAMPLE RESPONSE

{ id: 1, name: "HTMPC", industry: null, genre: "Bluegrass", label: "Unsigned", country: "United States", city: "Colada City", state: "CA", website_url: null, bio: "Hey, That's My Pina Colada", active_from: "2011-01-02T00:00:00Z", created_at: "2012-06-27T23:42:12Z", updated_at: "2013-03-05T23:53:36Z", facebook: "1360877850", twitter: "topspinqa", soundcloud: "", tunecore: null, youtube: "", vimeo: null, instagram: "", songkick: "", flickr: null, wordpress: null, tumblr: null, foursquare: null, tip_jar_embed_code: "<iframe id="tip_jar_frame" name="tip_jar_frame" src="http://godirect.topspin.net/home/accounts/1/tip_jar" frameborder="0" width="65" height="24" allowtransparency="true"></iframe>", tip_jar_uri: "http://godirect.topspin.net/home/accounts/1/tips/new", uri: "http://godirect.topspin.net/home/accounts/1.json", onebigthing_enabled: true, onebigthing_embed: "<iframe id="obtFrame" name="obtFrame" src="http://d6plqejwhskqm.cloudfront.net/home/accounts/1/mtv_artist_banner? ts=1358484948" frameborder="0" width="100%" height="324px" scrolling="no"></iframe>", mtv_artist_banner_enabled: true, mtv_artist_banner_embed: "<iframe id="obtFrame" name="obtFrame" src="http://d6plqejwhskqm.cloudfront.net/home/accounts/1/mtv_artist_banner? ts=1358484948" frameborder="0" width="100%" height="324px" scrolling="no"></iframe>", mtv_id: null, email: "jstemmle@topspinmedia.com" }, { id: 2, name: "MTV Test", industry: null, genre: "Polka", label: "Unsigned", country: "United States", city: "Los Angeles", state: "CA", website_url: "http://mtv.com/", bio: "Edit me!", active_from: "2012-01-02T00:00:00Z", created_at: "2012-06-28T07:22:38Z", updated_at: "2012-08-15T00:51:01Z", facebook: null, twitter: null, soundcloud: null, tunecore: null, youtube: null, vimeo: null, instagram: null, songkick: null, flickr: null, wordpress: null, tumblr: null, foursquare: null, tip_jar_embed_code: "<iframe id="tip_jar_frame" name="tip_jar_frame" src="http://godirect.topspin.net/home/accounts/2/tip_jar" frameborder="0" width="65" height="24" allowtransparency="true"></iframe>", tip_jar_uri: "http://godirect.topspin.net/home/accounts/2/tips/new", uri: "http://godirect.topspin.net/home/accounts/2.json", onebigthing_enabled: false, mtv_artist_banner_enabled: false, mtv_id: null }

b The Product Object

The Product object contains data about a particular track, video, or image, denoted by its "type" attribute.

Currently you may only retreive information about a particular Product or list all Products.

Attributes

id:
integer
unique id of the Product
account_id:
integer
id of the Account the Product belongs to
name:
string or null
type:
string
designates the type of Product.
Will be one of the following: "track","video", or "image"
embed_codes:
hash
Hash containing different widget configurations in the form of iframe html that can be embedded into html pages. player : string or null download_button : string or null standard string : string or null
metadata:
hash
Hash containing Product's metadata.
FOR TRACK PRODUCTS
album:
string or null
title:
string or null
artist:
string or null
comment:
string or null
genre:
string or null
year:
integer or null
track_number:
integer or null
length:
integer or null
composer:
string or null
publisher:
string or null
performance_rights_
organization:

string or null
other_performers:
string or null
isrc:
string or null
FOR VIDEO PRODUCTS
title:
string or null
artist:
string or null
length:
string or null
composer:
string or null
publisher:
string or null
performance_rights_
organization:

string or null
other_performers:
string or null
isrc:
string or null
director:
string or null
cinematographer:
string or null
album:
string or null
images:
hash
Hash containing uris to the Product's images
thumbnail:
string or null
logo:
string or null
medium_square:
string or null
uri:
string
URI of the Product. Use this to retrieve data for a specific Product
updated_at:
timestamp
created_at:
timestamp

Z Example Code

{ "account_id": 1, "created_at": "2012-09-04T16:56:12Z", "embed_codes": { "player": "<iframe id=\"tsFrame\" name=\"tsFrame\" src=\"http://api.artistlink.com/home/widgets/1? type=player\" frameborder=\"0\" width=\"300px\" height=\"270px\" ></iframe>" }, "id": 1, "images": { "background": "https://image_host.com/image1.jpg", "logo": "https://image_host.com/image2.jpg", "medium_square": "https://image_host.com/image3.jpg", "mtv_artist_banner": "https://image_host.com/image4.jpg", "thumbnail": "https://image_host.com/image5.jpg" }, "metadata": { "album": "Album", "artist": "Artist", "comment": "Comment", "composer": "Composer", "genre": "Genre", "isrc": "ISRC123", "length": 200, "other_performers": "Other Performers", "performance_rights_organization": "Rights Org", "publisher": "Publisher", "title": "Title", "track_number": 1, "year": 1985 }, "name": "Title", "type": "track", "updated_at": "2012-09-04T20:23:28Z", "uri": "/home/products/1.json" }

Retrieving a Product

Retrieves a specific Product's data. Requires the id of the Product.

Arguments

id:
required
The unique identifier of the Product

Returns

Returns Product json if a valid id argument has been supplied. Otherwise, returns error json.

Get Product


DEFINITION

GET http://api.artistlink.com/home/products/1.json

EXAMPLE REQUEST

curl http://api.artistlink.com/home/products/1.json?auth_token=abc123

EXAMPLE RESPONSE

{ "account_id": 1, "created_at": "2012-09-04T16:56:12Z", "embed_codes": { "player": "<iframe id=\"tsFrame\" name=\"tsFrame\" src=\"http://api.artistlink.com/home/widgets/1?type=player\" frameborder=\"0\" width=\"300px\" height=\"270px\" ></iframe>" }, "id": 1, "images": { "background": "https://image_host.com/image1.jpg", "logo": "https://image_host.com/image2.jpg", "medium_square": "https://image_host.com/image3.jpg", "mtv_artist_banner": "https://image_host.com/image4.jpg", "thumbnail": "https://image_host.com/image5.jpg" }, "metadata": { "album": "Album", "artist": "Artist", "comment": "Comment", "composer": "Composer", "genre": "Genre", "isrc": "ISRC123", "length": 200, "other_performers": "Other Performers", "performance_rights_organization": "Rights Org", "publisher": "Publisher", "title": "Title", "track_number": 1, "year": 1985 }, "name": "Title", "type": "track", "updated_at": "2012-09-04T20:23:28Z", "uri": "/home/products/1.json" }

List all Products

Lists Products in order of their creation date.

Arguments

type:
optional
Filter by Product type. Available product types are 'track', 'album', 'video', 'image'
genre
count:
optional, default is 10
The number of Products to be returned. Can range between 1 and 100.
offset:
optional, default is 0
The offset to the array of Products to be returned. The Products requested will be returned starting at this number.
account_id:
optional
Lists all Products belonging to a specific Account id
account_name:
optional
Filter by Products belonging to an account with the name attribute matching this argument. Case sensitive.

Returns

An array containing up to count Products, starting at the offset index, with any further passed in arguments/filters applied. Each entry in the array will be a Product object. If no more Products are available, the resulting array will be empty. This request should never return an error.

List Products


DEFINITION

GET http://api.artistlink.com/products.json

EXAMPLE REQUEST

curl "http://api.artistlink.com/home/products.json?auth_token=abc123&type=track&genre=electronic"

EXAMPLE RESPONSE

{ "account_id": 1, "created_at": "2012-09-04T16:56:12Z", "embed_codes": { "player": "<iframe id=\"tsFrame\" name=\"tsFrame\" src=\"http://api.artistlink.com/home/widgets/1?type=player\" frameborder=\"0\" width=\"300px\" height=\"270px\" ></iframe>" }, "id": 1, "images": { "background": "https://image_host.com/image1.jpg", "logo": "https://image_host.com/image2.jpg", "medium_square": "https://image_host.com/image3.jpg", "mtv_artist_banner": "https://image_host.com/image4.jpg", "thumbnail": "https://image_host.com/image5.jpg" }, "metadata": { "album": "Album", "artist": "Artist", "comment": "Comment", "composer": "Composer", "genre": "Genre", "isrc": "ISRC123", "length": 200, "other_performers": "Other Performers", "performance_rights_organization": "Rights Org", "publisher": "Publisher", "title": "Title", "track_number": 1, "year": 1985 }, "name": "Title", "type": "track", "updated_at": "2012-09-04T20:23:28Z", "uri": "/home/products/1.json" }, {...}, {...}, {...}