Documentação: Popularidade de Artistas

Ne-Yo
  1. Por que usar a popularidade do Vagalume em seu projeto?
  2. Parâmetros de consulta
  3. Resposta da consulta em JSON
    1. Resposta para artistas
    2. Resposta para artistas e suas músicas

Por que usar a popularidade dos artista no Vagalume em seu projeto?

As informações de popularidade no Vagalume são constantemente atualizadas e representam a tendência musical conforme milhões de acessos diários a páginas de letras, artistas, álbuns dentre outros. As informações são bem seccionadas, permitindo uso variado e fornecendo inúmeras possibilidades de aplicação em seu projeto.

A maneira mais fácil de fazer essa integração é utilizar Javascript permitindo que o próprio navegador do usuário acesse as informações, evitando problemas de rate limit com o número máximo de requisições por IP. Assim, inclusive, seu servidor não terá nenhum trabalho para buscar e mostrar o conteúdo.

Parâmetros de consulta

A consulta deve ser realizada via GET para obter informações do artista e/ou músicas. Como nos exemplos a seguir:
https://api.vagalume.com.br/rankArtist.php?artID=3ade68b2g3b86eda3&limit=10
https://api.vagalume.com.br/rankArtist.php?artID=3ade68b2g3b86eda3&period=daily&periodStart=2012-08-01&periodEnd=2012-12-30
https://api.vagalume.com.br/rankArtist.php?artID=3ade68b7g6b960ea3&musID=3ade68b8g42c34fa3,3ade68b8g869e2fa3,3ade68b8g145b4fa3...

period Período ao qual as informações se referem. Os valores possíveis são:
daily Informações diárias. weekly Informações semanais (valor padrão caso period não seja definido). monthly Informações mensais.
artID ID do artista/banda. As informações serão referentes ao ID pesquisado, apenas 1 ID por consulta. musID ID da musica a ser pesquisada. É opcional, podendo pesquisar até 5 musicas. limit Quantidade de resultados trazidos para cada pesquisa. Valor default 10 e no máximo 100. periodStartDefine a data que deve começar a pesquisa. É opcional e deve ser usado em conjunto com periodEnd.
Formatos de acordo com period: dialy:YYYY-MM-DD, weekly:YYYY-WW, month:YYYY-MM. periodEndDefine a data que deve terminar a pesquisa. É opcional e deve ser usado em conjunto com periodStart.
Formatos de acordo com period: dialy:YYYY-MM-DD, weekly:YYYY-WW, month:YYYY-MM.

Resposta da consulta em JSON

Resposta para artistas

URL de exemplo: https://api.vagalume.com.br/rankArtist.php?artID=3ade68b7g6b960ea3&limit=1

{
	"artist": {
		"week": [{
			"period": 201302,
			"pos": "11",
			"rank": 78.881750746658
		}]
	}
}

Descrição dos valores retornados:

artistContém o retorno dos dados pedidos. No caso, a popularidade de artistas.
week Contém as informações de popularidade para o período especificado. Podendo ser "day","week" ou "month".
period Data a que o período se refere. No caso ano 2013 e semana 02. pos Contém a posição do artista no rank de top artistas do Vagalume. rank Contém a pontuação do artista de acordo com a quantidade de acessos.

Resposta para artista e suas músicas

URL de exemplo: https://api.vagalume.com.br/rankArtist.php?artID=3ade68b7g6b960ea3&musID=3ade68b8g42c34fa3,3ade68b8g869e2fa3&period=monthly&limit=2

{
    "artist": {
        "month": [{
            "period": 201212,
            "pos": "10",
            "rank": 81.719660806764
        }, {
            "period": 201301,
            "pos": "11",
            "rank": 74.763519741729
        }]
    },
    "music": {
        "month": {
            "3ade68b8g42c34fa3": [{
                "period": 201212,
                "pos": "3079",
                "rank": 0.50146783717838
            }, {
                "period": 201301,
                "pos": "3068",
                "rank": 0.49854883749153
            }],
            "3ade68b8g869e2fa3": [{
                "period": 201212,
                "pos": "3401",
                "rank": 0.45940724173568
            }, {
                "period": 201301,
                "pos": "3683",
                "rank": 0.42352051737562
            }]
        }
    }
}

Descrição dos valores retornados:

artistContém o tipo de retorno dos dados pedidos. No caso, a popularidade de artista.
monthContém as informações de ranking para o período especificado. Podendo ser "day","week" ou "month"
period Contém informações da data a que o período se refere. No caso ano 2012 e mes 09. pos Contém a posição do artista no rank de top artistas do Vagalume. rank Contém a pontuação do artista de acordo com a quantidade de acessos.
musicContém o tipo de retorno dos dados pedidos. No caso, a popularidade de musicas do artista.
monthContém o tipo de retorno. Podendo ser "day","week" ou "month"
3ade6...Id do artista, contém as informações de popularidade.
period Contém informações da data. No primeiro caso ano 2012 e mes 12. pos Contém a posição da música no rank de top músicas do Vagalume. rank Contém a pontuação da música baseado na quantidade de acessos.