Hunted API

We listen to what people are saying about artists and their music on social networks like Facebook and MySpace, music blogs, message boards and forums, Twitter and P2P networks to chart the top songs online everyday. All this data is yours to play with.


The Hunted API provides three core functions:

  1. Suggest Songs
  2. Download Charts
  3. Cache Artists

Using the API

The We Are Hunted API is a REST service that exposes the data we use to create the Hunted charts so you can use it on your own website.

All API functions are GET requests.

API arguments may be specified in two ways:

  1. Using encoded values in the GET URL.
  2. Using an JSON encoded request payload. The format for the payload is indicated using the Content-Type request header.

The API returns JSON encoded output by default. If you provide a format=xml argument on the URL, or specify a HTTP Accept header that declares you want XML content (e.g., Accept: text/xml), the output format will be XML.

Each API client is throttled to a limited number of requests per minute. If you need to make more requests, or would like access to data that we don't currently expose through our API, please contact us.

Presently the API is restricted based on IP. This means that multiple users on mobile devices will not be affected by throttling as much as a website using the same API. However, we are open to discussion about this policy -- we want to work together with you to find a model that works. We want to find out how people want to use the API so we can make the important decisions about access control.

If you have an app that you think will be able to use the API then let us know what would work best for you!

Also - This API is not final. We are still fine tuning the arguments and format of return values. We will endeavor to keep the API as stable as possible, but some changes may occur during development.

Every call to the API accepts an version argument. In future, this argument will be used to allow us to modify argument or output formats. If unspecified, the version argument assumes the current API version. At present, the API version is '0'.

We aren't making any guarantees of stability in API version '0'. However, when we finalize the API and make version '1', we will guarantee that there are no incompatible changes in the API, and we will notify all registered API users of potential changes before they occur.

Suggest Songs

Pass an artist, playlist or text (blog post) and we will suggest some fresh new tracks that you should listen to. We use the ranking data from Hunted to make suggestions and return Grooveshark, Spotify, MySpace, and YouTube playable tracks.


Rather than use collaborative filtering or song analysis to make recommendations, our suggestions are based on what we think are the freshest tracks the music experts are listening to right now. Our goal is not extreme accuracy, but extreme freshness, seeking to always deliver music that is new, cool and relevant. We are constantly discovering and ranking new tracks so our suggestions change frequently.


Examples

1. Suggest 5 emerging tracks with Grooveshark URLs for someone that likes "The Ting Tings" and "Passion Pit":


http://wearehunted.com/api/suggest/singles/?count=5&provider=grooveshark&name=The+Ting+Tings&name=Passion+Pit

2. Suggest 10 mainstream tracks playable on YouTube for someone that loves "Bob Dylan"; also provide images


http://wearehunted.com/api/suggest/singles/?count=10&emerging=False&provider=youtube&provider=imagetext=I+love+Bob+Dylan

3. Suggest 10 mainstream tracks with YouTube links to match a blog entry. Use the JSON interface; request a JSON response:


GET /api/suggest/singles/ HTTP/1.1
Host: wearehunted.com
Content-Type: application/json
Accept: application/json

{
    "text":"I just listened to a great track by The Killers and then one ..."
    "emerging": false,
    "providers": ["youtube"]
}

This function returns a list of tracks with an artist name and playable URL.
The source track provider for the URL is configurable.


URL

http://wearehunted.com/api/suggest/singles/

Arguments

All arguments are optional. All have default values.

If no suitable suggestions can be made, the current emerging track chart will be returned.


text A block of text containing artist names.
name(s) A list of strings with each string the name of an artist. When specified using GET arguments, use multiple instances of the keyword name.
artist(s) A list of We Are Hunted artist IDs (see Find Artists below). When specified using GET arguments, use multiple instances of the keyword artist. Passing artist IDs rather than text or names will deliver better performance for larger playlists.
emerging Boolean value (True / False). Suggest songs from emerging or mainstream artists. The default value of True will return tracks from emerging artists.
providers A list indicating the providers that should be used to supply track URLs. Available song providers are: image, youtube, myspace, spotify, grooveshark, last.fm, itunes. When specified using GET arguments, use multiple instances of the keyword provider.
allow_blanks Boolean value (True / False). We Are Hunted may not have a URL for every track from each requested provider. The allow_blanks boolean specifies whether you want to include results in the suggestions when no URL is available. The default value is False indicating that tracks with no URL will be omitted from suggestions; a value of True will result in a Null value being returned.
include_seeds Boolean value (True / False). The default value is False indicating that suggestions will exclude songs by the artists passed. A value of True will allow songs from the Artist passed to be include in the results. This setting is useful if you are looking to make recommendation based on text like blog posts.
count The maximum number of tracks that should be returned.

Return value

A list of tuples. Each tuple element in the list is a track. The first two elements in the tuple are the track name and the artist name; an additional element will be included for each provider requested.

Download Charts

The We Are Hunted charts can all be retrieved programmatically.
This function provides easy access to live chart data for reuse inside your own apps.

Examples

Retrieve 10 artists from the weekly rock chart:


http://wearehunted.com/api/chart/rock/artists/7/

Retrieve 6 songs with Image and Grooveshark links from Adrian's Chart:


http://wearehunted.com/api/chart/by/adrian/?provider=image&provider=grooveshark&count=6

URLs

http://wearehunted.com/api/chart/<chart type>/<period>/
http://wearehunted.com/api/chart/<chart name>/<chart type>/<period>/
http://wearehunted.com/api/chart/by/<user name>/

URL Structure

chart name The chart name should be one of the following:
  • rock
  • pop
  • folk
  • metal
  • alternative
  • electronic
  • punk
  • rap-hip-hop
  • twitter
  • remix

A URL without a chart name will return the overall We Are Hunted chart.
chart type The chart type should be either artists or singles. The Remix chart is only available as a singles chart type.
period The period describes the number of days over which the chart data is collated. It can be 1, 7, or 30, describing a daily, weekly or monthly chart, respectively
user name Retrieve the chart compiled by a specific user.

Arguments

All arguments are optional. All have default values.

If no suitable suggestions can be made to match the artists, names or text specified, the current emerging track chart will be returned.


A list indicating the providers that should be used to supply track URLs. Available song providers are: image, youtube, myspace, spotify, grooveshark, last.fm, and itunes. Artist charts may use one of the providers image, youtube, myspace, facebook, itunes, last.fm, and twitter. When specified using GET arguments, use multiple instances of the keyword provider.
count The maximum number of artists/tracks that should be returned.
providers
allow_blanks Boolean value (True / False). We Are Hunted may not have a URL for every track from each provider requested. The allow_blanks boolean specifies whether you want to include results in the suggestions when no URL is available. The default value is False indicating that tracks with no URL will be omitted from suggestions; a value of True will result in a Null value being returned.

Return value

Returns a list of tuples. The Single Chart will return the track name, artist name, plus one element for each provider that has been requested. The Artist Chart returns tuples of artist name, plus an element for each provider that has been requested.

Cache Artists

We Are Hunted uses an integer ID to identify Artists and Tracks. The Artist Lookup API allows you to discover the ID that identifies a particular artist. Passing artist IDs rather than text or names will deliver better performance for larger playlists.

Examples

Find the ID for "The Ting Tings"

http://wearehunted.com/api/lookup/artist/?name=The+Ting+Tings

Find the ID for "The Ting Tings" and "Passion Pit"

http://wearehunted.com/api/lookup/artist/?name=The+Ting+Tings&name=Passion+Pit

Find the IDs of artists mentioned in a blog post. Use the JSON interface; request a JSON response:

GET /api/lookup/artist/ HTTP/1.1
Host: wearehunted.com
Content-Type: application/json
Accept: application/json

{"text":"I just listened to a great track by 'Passion Pit'..."}

URL

http://wearehunted.com/api/lookup/artist/

Arguments

name(s) A list of strings with each string the name of an artist. When specified using GET arguments, use multiple instances of the keyword name.
text A block of text that contains artist names (for example, a blog post).

Return value

A list of We Are Hunted IDs matching the names or text provided.