Developer API documentation

Demographics Endpoints

The demographics endpoints provide a snapshot of the current age, gender and location breakdown for the fans or followers of an entity.

The age demographic data is provided as the percentage of followers of a given age in variable size bins covering an age range of 0 - 99.

The gender demographic data gives the total number of male and female followers for the given data source.

The location-based endpoints provide a snapshot of the country-level or city-level distribution of fans or file sharing activity.

General URI Format

The age and gender demographics datasets follow this basic URI structure:

http://api.semetric.com/[entity_type]/[id]/demographics/[data_source]/[age|gender]?[arguments]
  • id can either be a Semetric UUID or one of the supported third-party ids with the appropriate prefix (see ID Schemas)
  • entity_type is a valid entity type for which fan demographics data is available, eg: artist, tvprogram or film
  • data_source is a valid data source for age and gender demographics, these being: twitter or myspace
  • arguments are options specified as key value pairs, with the only required pair being token=[api_key]

The location-based demographics datasets follow this basic URI structure:

http://api.semetric.com/[entity_type]/[id]/demographics/[data_source]/location/[country|city]?[arguments]
  • id can either be a semetric UUID or one of the supported third-party ids with the appropriate prefix
  • entity_type is a valid entity type for example artist, tv or movie
  • data_source is a valid data source for location demographics, these being: twitter-mentions or twitter-fans
  • arguments are options specified as key value pairs, with the only required pair being token=[api_key]

Examples

/artist/[id]/demographics/twitter/gender

The total number of male and female followers for an artist on Twitter.

http://api.semetric.com/artist/[id]/demographics/twitter/gender?token=[api_key]

example

{
   "response":{
      "data":[
         {
            "count":487560,
            "gender":"female"
         },
         {
            "count":617020,
            "gender":"male"
         }
      ]
   },
   "success":true
}

/artist/[id]/demographics/twitter/age

The age breakdown for followers for an artist on Twitter.

http://api.semetric.com/artist/[id]/demographics/twitter/age?token=[api_key]

example

Age breakdown of Lady Gaga’s followers on Twitter:

http://api.semetric.com/artist/fe66302b0aee49cfbd7d248403036def/demographics/twitter/age?token=[api_key]
{
   "response":{
      "data":[
         {
            "age":"00-16",
            "percent":0.5664336
         },
         {
            "age":"17-19",
            "percent":0.1961056
         },
         {
            "age":"20-24",
            "percent":0.1880757
         },
         {
            "age":"25-29",
            "percent":0.03045575
         },
         {
            "age":"30-34",
            "percent":0.007945503
         },
         {
            "age":"35-39",
            "percent":0.00249578
         },
         {
            "age":"40-49",
            "percent":0.003146853
         },
         {
            "age":"50-59",
            "percent":0.003809983
         },
         {
            "age":"60-69",
            "percent":0.001241862
         },
         {
            "age":"70-99",
            "percent":0.0002893658
         }
      ]
   },
   "success":true
}