Developer API documentation

Timeseries Endpoints

General URI Format

All the timeseries datasets follow the same basic URL structure:

http://api.semetric.com/[entity_type]/[id]/[data_type]/[data_source]?[arguments]
  • id can either be a Semetric UUID or one of the supported third-party ids (see ID Schemas) with the appropriate prefix
  • data_type is a valid data type for example fans, plays or views
  • data_source is a valid data source, for example facebook, twitter or bittorrent
  • arguments are options specified as key value pairs, with the only required pair being token=[api_key]

For a list of all the data types and data sources associated with a particular entity, use the summary endpoint:

http://api.semetric.com/[entity_type]/[id]/?token=[api_key]

Response Structure

The JSON response includes metadata specifying start_time and end_time as epoch time (for a definition see Unix time). The period will correspond to an hour (3600 seconds), day (86400 seconds) or week (604800 seconds) depending on what was requested in the arguments (detailed below). The data is given as a list of comma-separated numeric values.

{"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
}

Arguments

The arguments for timeseries calls are:

  • 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>] - timeseries for only the specified county, when available (default is ALL)

Artist Timeseries

Timeseries for music artists can be requested using:

http://api.semetric.com/artist/[artist_id]/[data_type]/[data_source]?[arguments]

Most datasets have a two level heirarchy to facilitate grouping and aggregation of related datasets. For example the total Vevo plays for an artist can be retrieved from /plays/vevo, and SoundCloud plays from /plays/soundcloud

/artist/[id]/plays

Number of plays for all tracks attributed to an artist from a given source, or total gives an aggregate of sources.

/artist/[id]/plays/total

/artist/[id]/plays/lastfm

/artist/[id]/plays/vevo

/artist/[id]/plays/soundcloud

/artist/[id]/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.

/artist/[id]/fans/total

/artist/[id]/fans/facebook

/artist/[id]/fans/lastfm

/artist/[id]/fans/twitter

/artist/[id]/fans/soundcloud

/artist/[id]/fans/instagram

/artist/[id]/views

Profile page views, in a given network or in aggregate

/artist/[id]/views/total

/artist/[id]/views/wikipedia

/artist/[id]/comments

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

/artist/[id]/comments/total

/artist/[id]/comments/soundcloud

/artist/[id]/comments/facebook

/artist/[id]/downloads

Downloads of all releases associated with an artist.

/artist/[id]/downloads/total

/artist/[id]/downloads/bittorrent