Documentação: Ranking Vagalume

Ne-Yo Snow Patrol
  1. Por que usar o ranking do Vagalume em seu projeto?
  2. Parâmetros de consulta
  3. Combinações de escopos
    1. Escopos para artistas
    2. Escopos para álbuns
    3. Escopos para músicas
  4. Resposta da consulta em JSON
    1. Resposta para artistas
    2. Resposta para álbuns
    3. Resposta para músicas
  5. Combinando múltiplas pesquisas em uma só consulta

Importante

Para usar Vagalume API, é necessário que seu aplicativo tenha credenciais de autorização. Cadastre-se no Vagalume e crie sua chave de API. Esta credencial será requerida a partir do dia 23/11/2015.

Por que usar o ranking do Vagalume em seu projeto?

As informações de ranking 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/rank.php?type=art&period=day&scope=internacional&limit=2&apikey={key}
https://api.vagalume.com.br/rank.php?type=alb&period=week&periodVal=201220&scope=internacional&limit=2&apikey={key}
https://api.vagalume.com.br/rank.php?type=mus&period=month&periodVal=201201&scope=translations&limit=2&apikey={key}

type Ranking se deseja obter. Valores possíveis: art (artistas), alb (álbuns), mus (músicas) period Período ao qual as informações se referem. Alguns períodos não estão disponíveis para a consulta de álbuns. Os valores possíveis são:
day Retorna o ranking do dia atual ou o informado no periodVal. Não está disponível para type=album. week Retorna o ranking da semana atual ou o informado no periodVal. month Retorna o ranking do mês atual ou o informado no periodVal.
periodVal Refere a data desejada de pesquisa. Caso não tenha este informação, retornará o ranking do período ("day", "week" ou "month") atual. Deve estar formatado de acordo com o period informado:
day Usar o formato YYYYMMDD week Usar o formato YYYYWW (WW sendo o número da semana do ano) month Usar o formato YYYYMM
scope Escopo das informações. As possibilidades podem variar de acordo com tipo de ranking obtido. Leia mais na seção sobre combinações de escopos limit Quantidade de resultados trazidos para cada tipo/período/escopo da pesquisa. callbackFunção que será chamada em seu código para requisição JSONP. Como permitimos requisição de qualquer origem, este parâmetro não é necessário.

Combinações de escopos

O escopo define diferentes contextos ao qual a informação deve se referir e são diferentes de acordo com o tipo (parâmetro type) utilizado.

Escopos para artistas:

all Retorna o ranking geral de artistas, que inclui nacionais e internacionais. internacional Retorna o ranking considerando somente os artistas internacionais. nacional Retorna o ranking considerando somente os artistas nacionais.

Exemplos:
https://api.vagalume.com.br/rank.php?type=art&period=month&periodVal=201210&scope=all&limit=2&apikey={key}
https://api.vagalume.com.br/rank.php?type=art&period=week&scope=nacional,internacional&limit=2&apikey={key}

Escopos para álbuns

Lembrando que não é possível efetuar a pesquisa com "period=day".

all Retorna o ranking geral de álbuns, incluindo lançamentos nacionais e internacionais. internacional Retorna o ranking considerando somente os álbuns de artistas internacionais. nacional Retorna o ranking considerando somente os álbuns de artistas nacionais.

Exemplos:
https://api.vagalume.com.br/rank.php?type=alb&period=month&scope=all&limit=2&apikey={key}
https://api.vagalume.com.br/rank.php?type=alb&period=week&periodVal=201240&scope=nacional,internacional&limit=2&apikey={key}

Escopos para músicas

all Retorna ranking geral de todas as músicas que constam no site. lyricsRetorna o ranking geral de letras de músicas (sejam originais, traduções ou cifras) translationsRetorna o ranking geral somente das letras traduzidas. chordsRetorna o ranking geral das letras de músicas cifradas.

Exemplos:
https://api.vagalume.com.br/rank.php?type=mus&period=month&scope=lyrics&limit=2&apikey={key}
https://api.vagalume.com.br/rank.php?type=mus&period=week&periodVal=201220&scope=all,lyrics&limit=2&apikey={key}
https://api.vagalume.com.br/rank.php?type=mus&period=day&periodVal=20121015&scope=translations,chords&limit=2&apikey={key}

Captcha

serialUsado em conjunto com udig para fazer a requisição pós-captcha.

Resposta da consulta em JSON

Resposta para artistas

URL de exemplo: https://api.vagalume.com.br/rank.php?type=art&period=week&periodVal=201134&scope=all&limit=1&apikey={key}

{
  "art": {
    "week": {
      "period": {
        "year": "2011",
        "week": "34"
      },
      "all": [{
        "id": "3ade68b7g98d71ea3",
        "name": "Bruno Mars",
        "url": "https://www.vagalume.com.br/bruno-mars/",
        "pic_small": "https://www.vagalume.com.br/bruno-mars/images/profile.jpg",
        "pic_medium": "https://www.vagalume.com.br/bruno-mars/images/bruno-mars.jpg",
        "uniques": "84709",
        "views": "183162"
      }]
    }
  }
}

Descrição dos valores retornados:

artContém o tipo de retorno dos dados pedidos. No caso, o ranking de artistas.
week Contém as informações de ranking para o período especificado. No caso, para a semana. period Contém informações da data a que o período se refere. all Contém a lista com o ranking de artistas, ordenados da melhor posição (primeiro lugar) para a menor posição. As pesquisas pelo ranking de artistas nacionais ou internacionais possuem estrutura semelhante a esta.
id Id do artista no Vagalume name Nome do artista url URL do artista no Vagalume pic_small Imagem do artista em miniatura pic_medium Imagem do artista em tamanho médio uniques Número de usuários únicos a acessar o artista no período views Número total de visualizações do conteúdo do artista no período

Resposta para álbuns

URL de exemplo: https://api.vagalume.com.br/rank.php?type=alb&period=week&periodVal=201134&scope=all&limit=1&apikey={key}

{
  "alb": {
    "week": {
      "period": {
        "year": "2011",
        "week": "34"
      },
      "all": [{
        "id": "3ade68b6g9188fda3",
        "name": "Paula Fernandes - Ao Vivo",
        "url": "https://www.vagalume.com.br/paula-fernandes/discografia/paula-fernandes-ao-vivo.html",
        "cover": "https://www.vagalume.com.br/paula-fernandes/discografia/paula-fernandes-ao-vivo-W100.jpg",
        "uniques": 59860,
        "views": 71702,
        "art": {
          "id": "3ade68b6g1e32fda3",
          "name": "Paula Fernandes"
          "url": "https://www.vagalume.com.br/paula-fernandes/",
          "pic_small": "https://www.vagalume.com.br/paula-fernandes/images/profile.jpg",
          "pic_medium": "https://www.vagalume.com.br/paula-fernandes/images/paula-fernandes.jpg"
        }
      }]
    }
  }
}

Descrição dos valores retornados:

albContém o tipo de retorno dos dados pedidos. No caso, o ranking de álbuns.
week Contém as informações de ranking para o período especificado. No caso, para a semana. period Contém informações da data a que o período se refere. all Contém a lista com o ranking de álbuns, ordenados da melhor posição (primeiro lugar) para a menor posição. As pesquisas pelo ranking de álbuns com scope=nacional ou scope=internacional possuem estrutura semelhante a esta.
id Id do álbum no Vagalume name Nome do álbum url URL da página do álbum no Vagalume cover URL para a imagem da capa do álbum uniques Número de usuários únicos a acessar o conteúdo do álbum no período views Número total de visualizações do conteúdo do álbum no período art Artista ao qual o álbum se refere.
id Id do artista no Vagalume name Nome do artista url URL do artista no Vagalume pic_small Imagem do artista em miniatura pic_medium Imagem do artista em tamanho médio

Resposta para músicas

URL de exemplo: https://api.vagalume.com.br/rank.php?type=mus&period=week&periodVal=201134&scope=all&limit=1&apikey={key}

{
  "mus": {
    "week": {
      "period": {
        "year": "2011",
        "week": "34"
      },
      "all": [{
        "id": "3ade68b8gadffdfa3",
        "name": "High Life",
        "url": "https://www.vagalume.com.br/b-o-b/high-life.html",
        "uniques": "28866",
        "views": "31219",
        "art": {
          "id": "3ade68b7gaeb31ea3",
          "name": "B.o.B."
          "url": "https://www.vagalume.com.br/b-o-b/",
          "pic_small": "https://www.vagalume.com.br/b-o-b/images/profile.jpg",
          "pic_medium": "https://www.vagalume.com.br/b-o-b/images/b-o-b.jpg"
        }
      }]
    }
  }
}

Descrição dos valores retornados:

musContém o tipo de retorno dos dados pedidos. No caso, o ranking de músicas.
week Contém as informações de ranking para o período especificado. No caso, para a semana. period Contém informações da data a que o período se refere. all Contém a lista com o ranking de músicas, ordenados da melhor posição (primeiro lugar) para a menor posição. As pesquisas pelo ranking de músicas com scope=lyrics, scope=translations ou scope=chords possuem estrutura semelhante a esta.
id Id da música no Vagalume name Nome da música url URL da página da música no Vagalume uniques Número de usuários únicos a acessar a música no período views Número total de visualizações da música no período art Artista que interpreta a música.
id Id do artista no Vagalume name Nome do artista url URL do artista no Vagalume pic_small Imagem do artista em miniatura pic_medium Imagem do artista em tamanho médio

Combinando múltiplas pesquisas em uma só consulta

Se você precisa obter a informação de mais de um tipo ou de mais de um escopo... é possível combinar as várias pesquisas na mesma consulta, porém sempre para o mesmo período. Somente deve se estar atento para a resposta e sua estrutura, como visto anteriormente.

Se consultado http://api.vagalume.com.br/rank.php?type=art,alb&period=month&periodVal=201108&scope=nacional,internacional observe que a resposta trará tanto do ranking de artistas como álbums, com posicionamentos do mês separados em grupos de artistas nacionais e internacionais e álbuns nacionais e internacionais.

Considere que combinando a consulta de artistas e músicas, alguns escopos aparecerão somente para artistas e outros só para as músicas, como na consulta em https://api.vagalume.com.br/rank.php?type=art,mus&period=month&periodVal=201108&scope=nacional,translations&limit=1&apikey={key}

{
  "art": {
    "month": {
      "period": {
        "year": "2011",
        "month": "08"
      },
      "nacional": [{
        "id": "3ade68b6g39a2fda3",
        "name": "Jorge e Mateus",
        "url": "https://www.vagalume.com.br/jorge-e-mateus/",
        "pic_small": "https://www.vagalume.com.br/jorge-e-mateus/images/profile.jpg",
        "pic_medium": "https://www.vagalume.com.br/jorge-e-mateus/images/jorge-e-mateus.jpg",
        "uniques": "959755",
        "views": "2492570"
      }]
    }
  },
  "mus": {
    "month": {
      "period": {
        "year": "2011",
        "month": "08"
      },
      "translations": [{
        "id": "3ade68b8gf12ebfa3",
        "name": "Talking To The Moon (tradução)",
        "url": "https://www.vagalume.com.br/bruno-mars/talking-to-the-moon-traducao.html",
        "uniques": "398487",
        "views": "474797",
        "art": {
          "id": "3ade68b7g98d71ea3",
          "name": "Bruno Mars",
          "url": "https://www.vagalume.com.br\/bruno-mars\/",
          "pic_small": "https://www.vagalume.com.br/bruno-mars/images/profile.jpg",
          "pic_medium": "https://www.vagalume.com.br/bruno-mars/images/bruno-mars.jpg"
        }
      }]
    }
  }
}