Developer API documentation

Artist Timeseries calls

URL form

All the timeseries datasets follows the same basic URL structure:

http://api.semetric.com/artist/[ID]/[dataset]?[qualifier_arguments]
  • ID can either be a semetric UUID or one of the supported third-party ids (see A bit about identification) with the appropriate prefix.
  • dataset A valid dataset, as described below.
  • qualified_arguments any desired options specefied as cgi key value pairs, with the only required pair being token=YOURAPIKEY

Response structure

All the timeseries endpoints return a sequence of values with header-like metadata for start_time, end_time and period to minmise data transfered while allowing the time and data of any particular datapoint to be calculated. Timeseries responses follow the form (assuming JSON):

{"response":
   {
    "start_time":/*seconds from epoch to start of timeseries*/,
    "period": /*seconds in timeseries period*/,
    "end_time": /*seconds from epoch to start of the last datapoint in timeseries*/,
    "data": /*timeseries data, as list of integers*/
   },
 "success": true
}

Qualifiers

The timeseries calls can be qualified in a few ways (note that the country filter will only have an effect for timeseries with underlying country data, principally bittorrent):
variant=[diff|cumulative] - switch between change/period and total-to-date for a timeseries (default is diff) granularity=[hour|day|week] - length of time covered by each data point in a timeseries (default is day) country=[ALL|<ISO country code>] - ts for only the specified county, when available (default is ALL)

Datasets

Datasets have a two level heirarchy to facilitate grouping and aggregation of related datasets i.e. in place of a specific social network, total fans can be found from /fans/total.

Note that these endpoints are not tied to any specific release or work. There will be forthcoming endpoints exposing analogous data for track entities in an upcoming release.

plays

Series data describing playbacks of all tracks attributed to an artist from a given source or aggregate of sources.

/plays/total

/plays/lastfm

/plays/myspace

/plays/youtube

/plays/soundcloud

/plays/vevo

fans

The number of users paying attention to an artist in a given network or aggregate of networks. Naming convetions vary and can include friends, followers, or subscribers.

/fans/total

/fans/facebook

/fans/lastfm

/fans/myspace

/fans/youtube

/fans/twitter

/fans/soundcloud

views

Profile page views, in a given network or in aggregate

/views/total

/views/myspace

/views/youtube

comments

Comments received by an artist. Note that for networks that provide a facility to comment on a particular track (e.g. youtube) this reflects the sum of comments across all tracks associated with the artist’s profile in a given period of time.

/comments/total

/comments/myspace

/comments/youtube

downloads

Downloads of all releases associated with an artist.

/downloads/total

/downloads/bittorrent