Documentação: Letras de Músicas

Claudia Leitte Mika Frank Turner
  1. Como incluir letras de músicas em seu site?
    1. Exemplo Javascript
    2. Diferenças nos nomes dos artistas e músicas
  2. Direitos Autorais
  3. Parâmetros de consulta
  4. Resposta da consulta em JSON
  5. Informações extras
    1. Álbum relacionado
    2. Artistas relacionados
    3. Músicas relacionadas
    4. Imagens do artista
    5. Ranking do artista
  6. Captcha

Veja também:

  1. Buscas em geral

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.

Como incluir letras de músicas em seu site?

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.

Exemplo Javascript

Para que seja possível acessar a API via Javascript a partir do seu domínio, permitimos o acesso de outra origem com o Cross-Origin Resource Sharing (já suportado no Chrome e Firefox). Para os outros navegadores, você também pode utilizar a requisição JSONP passando um parâmetro de callback.

O exemplo abaixo é bem simples e utiliza getJSON do jQuery (sem necessidade de especificar o callback). Veja também o exemplo completo no Github.

// Exemplo de requisição
var artist = "U2";
var song   = "One";
jQuery.getJSON(
    "https://api.vagalume.com.br/search.php"
		+ "?art=" + artist
		+ "&mus=" + song,
		+ "&apikey={key}"
	function (data) {
		// Letra da música
		alert(data.mus[0].text);
	}
);
Exemplo completo »

Diferenças nos nomes dos artistas e músicas

Você não tem que se preocupar muito com diferenças nos nomes dos artistas e músicas. O Vagalume possui um grande banco de dados com nomes similares que está constantemente sendo alimentado. Sendo assim, situações como Beatles e The Beatles ou ainda Madonna e Madona são tratadas de forma bastante simples.

A utilização da API do Vagalume não transfere os direito de uso das letras de músicas que devem ser adquiridas diretamente com os proprietários. Caso não queria obter os direitos de exibição da letra da música, utilize a API para obter apenas o link no Vagalume para que a letra seja exibida dentro do site do Vagalume.

A API do Vagalume deve ser usada sempre acompanhando o link para o conteúdo acessado na URL do site Vagalume.
Para mais informações confira nossos Termos de uso.


Parâmetros de consulta

A consulta pode ser realizada via POST ou GET para obter informações do artista e/ou músicas. Como nos exemplos a seguir:
https://api.vagalume.com.br/search.php?art=U2&mus=one&apikey={key}
https://api.vagalume.com.br/search.php?art=Madonna&mus=One%20More%20Chance&extra=relart&apikey={key}
https://api.vagalume.com.br/search.php?art=Lady%20Gaga&mus=Alejandro&extra=relmus&apikey={key}
https://api.vagalume.com.br/search.php?musid=3ade68b6g4946fda3&apikey={key}
https://api.vagalume.com.br/search.php?musid=3ade68b6g4946fda3&extra=relmus,relart&apikey={key}

artNome do artista musTítulo da música (opcional) musidID da música. Quando este parâmetro for passado, art e mus são desnecessários. udigCaso o retorno seja o captcha por conta do rate limit de acessos, a requisição seguinte deve conter o parâmetro udig e serial. Veja o exemplo completo no tratamento do captcha. serialUsado em conjunto com udig para fazer a requisição pós-captcha. 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. nolyricsNão irá trazer o texto da letra da música, consequentemente não passará pela verificação de captcha. extraIndica quais informações extras podem vir na resposta. É uma lista de opções separadas por vírgulas que podem ser livremente combinadas. As opções possíveis são: alb, relart, relmus e rank

Resposta da consulta em JSON

URL: https://api.vagalume.com.br/search.php?art=madonna&mus=holiday&apikey={key}

// Exemplo de retorno da requisição
{  "type":"exact",
   "art":{
      "id": "3ade68b3g1f86eda3",
      "name":"Madonna",
      "url" :"https://www.vagalume.com.br/madonna/"
   },
   "mus":[{
      "id":"3ade68b6g8e27fda3",
      "name":"Holiday",
      "lang":2,
      "url":"https://www.vagalume.com.br/madonna/holiday.html",
      "text":"Holiday Celebrate\nHoliday Celebrate(..cut..)"
      "translate":[{
         "id":"3ade68b6g417afda3",
         "lang":1,
         "url":"https://www.vagalume.com.br/madonna/holiday-traducao.html",
         "text":"[Feriado]\nFeriado, comemore\nFeriado comemore(..cut..)"
      }]
   }]
};

As propriedades do objeto JSON de resposta são as seguintes:

typeO tipo de retorno dos dados que vem a seguir. Os possíveis resultados são:
exactResposta exata (artista e música foram encontrados). aproxO título da música não foi encontrada exatamente como pesquisado. song_notfoundO título da música não foi encontrado e não existem possíveis resultados. notfoundO artista não foi encontrado.
artContém informações do artista no Vagalume:
name Nome do artista url Url da página do artista no Vagalume
musInformações adicionais sobre a música encontrada. Caso o type seja "aprox", é possível que neste array exista mais de uma música.
idID da música encontrada. Poderá ser utilizado em uma outras requisições. nameO título da música encontrada langO idioma da música encontrada. Possíveis valores são: 1 (Português Brasil), 2 (Inglês), 3 (Espanhol), 4 (Francês), 5 (Alemão), 6 (Italiano), 7 (Holandês), 8 (Japonês), 9 (Português Portugal). O valor 999999 é reservado para "Outros". urlA URL da música no Vagalume textO texto da letra da música translateCaso existam versões da música em outros idiomas, estará listado neste array. A maioria das requisições de músicas em inglês deverá conter esse array com objetos para outras músicas de outros idiomas (seguindo o padrão dos campos id, lang, url e text. Você poderá utilizar essa informação para saber se existe uma tradução disponível e colocar um link para a URL informada.
O objeto translate é semelhante ao item do array, tendo as propriedades id, lang, url e text, com exceção das propriedades name e translate.

Informações extras

Informações extras podem ser solicitadas através do parâmetro "extra", e podem ser combinadas de acordo com a necessidade de sua aplicação. Exemplos:
https://api.vagalume.com.br/search.php?art=u2&mus=one&extra=relmus&apikey={key}
https://api.vagalume.com.br/search.php?art=u2&mus=one&extra=relmus,relart&apikey={key}
https://api.vagalume.com.br/search.php?art=u2&mus=one&extra=relart,relmus&apikey={key}
https://api.vagalume.com.br/search.php?art=u2&mus=one&extra=alb,relart,relmus&apikey={key}

Álbum relacionado

Para obter dados do álbum mais recente que a música procurada está presente, se houver, utiliza-se o valor alb no parâmetro extra. Exemplo:
https://api.vagalume.com.br/search.php?art=U2&mus=One&extra=alb&nolyrics=1&apikey={key}

// Exemplo de retorno da requisição JSON
{
  "type": "exact",
  "art": {
    "id": "3ade68b2g3b86eda3",
    "name": "U2",
    "url": "https://www.vagalume.com.br/u2/"
  },
  "mus": [{
    "id": "3ade68b3gdb86eda3",
    "name": "One",
    "url":"https://www.vagalume.com.br/u2/one.html",
    "lang":2,
    "alb": {
      "id": "3ade68b6ge7e7fda3",
      "name": "U218 Singles",
      "url":"https://www.vagalume.com.br/u2/discografia/u218-singles.html",
      "year": "2006",
      "img": "https://www.vagalume.com.br/u2/discografia/u218-singles-W125.jpg"
    }
  }]
}

Artistas relacionados

Para obter uma relação de artistas relacionados ao artista encontrado, utiliza-se o valor relart no parâmetro extra. Exemplo:
https://api.vagalume.com.br/search.php?art=madonna&extra=relart&extra=relart&apikey={key}

// Exemplo de retorno da requisição JSON
{
  "type": "song_notfound",
  "art": {
    "id": "3ade68b3g1f86eda3",
    "name": "Madonna",
    "url": "https://www.vagalume.com.br/madonna/",
    "related": [{
      "id": "3ade68b2g4b86eda3",
      "name": "Kid Abelha",
      "url": "https://www.vagalume.com.br/kid-abelha/"
    }, {
      "id": "3ade68b5g67d7eda3",
      "name": "Britney Spears",
      "url": "https://www.vagalume.com.br/britney-spears/"
    }]
  }
}

Músicas relacionadas

Para obter uma relação de músicas relacionadas com a música encontrada, utilize o valor relmus no parâmetro extra. Por exemplo, para encontrar músicas relacionadas a "One" do U2, usamos a seguinte url:
URL: https://api.vagalume.com.br/search.php?art=U2&mus=One&extra=relmus&nolyrics=1&apikey={key} 

// Exemplo de retorno da requisição JSON
{
  "type": "exact",
  "art": {
    "id": "3ade68b2g3b86eda3",
    "name": "U2",
    "url": "https://www.vagalume.com.br/u2/"
  },
  "mus": [{
    "id": "3ade68b3gdb86eda3",
    "name": "One",
    "url": "https://www.vagalume.com.br/u2/one.html",
    "lang": 2,
    "translate": [{
      "id": "3ade68b6g8048fda3",
      "lang": 1,
      "url": "https://www.vagalume.com.br/u2/one-traducao.html"
    }],
    "related": [{
      "art": {
        "id": "3ade68b3g0f86eda3",
        "name": "R.E.M.",
        "url": "https://www.vagalume.com.br/r-e-m/"
      },
      "mus": {
        "id": "3ade68b4gf596eda3",
        "lang": "2",
        "name": "Losing My Religion",
        "url": "https://www.vagalume.com.br/r-e-m/losing-my-religion.html"
      }
    }, {
        "art": { /* outro artista relacionado */ },
        "mus": { /* outra música relacionada */ }
    }]
  }]
}

Imagens do artista

Disponibilizamos uma foto ou imagem do artista em dois tamanhos: pequeno (pic_small) e médio (pic_medium). Para incluí-las no retorno da consulta, basta passar o valor artpic no parâmetro extra. Por exemplo, para obtera foto do "U2", usamos a seguinte url:
URL: https://api.vagalume.com.br/search.php?art=U2&extra=artpic&nolyrics=1&apikey={key} 

{
  "type": "song_notfound",
  "art": {
    "id": "3ade68b2g3b86eda3",
    "name": "U2",
    "url": "https://www.vagalume.com.br/u2/",
    "pic_small": "https://www.vagalume.com.br/u2/images/profile.jpg",
    "pic_medium": "https://www.vagalume.com.br/u2/images/u2.jpg"
  }
}

Ranking do Artista

Caso queira adicionar dados sobre o ranking do artista no Vagalume em sua aplicação, é possível obter os dados mais recentes, se houver, na base de dados do Vagalume. Para isto basta passar o valor rank no parâmetro extra.

Veja o exemplo abaixo para obter o ranking do U2:
URL: https://api.vagalume.com.br/search.php?art=U2&extra=rank&nolyrics=1&apikey={key} 

// Exemplo de retorno da requisição JSON

{
 "type": "song_notfound",
 "art": {
    "id": "3ade68b2g3b86eda3",
    "name": "U2",
    "url": "https://www.vagalume.com.br/u2/",
    "rank": {
         "pos": "100",
         "period": 201111,
         "views": "225014",
         "uniques": "90313",
         "points": "17.5"
    }
 }
}

Captcha (Rate Limit)

O Vagalume é constantemente alvo de "robôs" na Internet. Para proteger o nosso conteúdo foi necessário implementar um limite de requisições do mesmo IP por algum tempo. Fazemos o possível para não afetar usuários comuns neste ponto, mas é possível que alguns usuários tenham que ser verificados.

É uma autenticação bem simples, com apenas 4 números que deverá ser digitado. No exemplo completo já colocamos o código que verifica o captcha e pede para o usuário digitar os números.

O retorno da requisição poderá vir da maneira abaixo:

// Exemplo de retorno com captcha
{captcha: true
 serial: 1353907813
 key2: "sAPI"
 captcha_img: "https://www.vagalume.com.br/control/web_dig_img.php?key2=sAPI&serial=1353907813"}

Para resolver o captcha, basta mostrar a imagem do captcha_img (sempre utilize a URL informada, não monte a URL pois o 'key2' pode mudar no futuro) e pedir para o usuário fazer a requisição. Assim, a requisição seguinte para o search.php deve conter o serial (informado no retorno acima) e o udig (número digitado pelo usuário). Para saber mais, veja os parâmetros do search.php acima.

Dica: Se seu aplicativo só precisa verificar a existência da música (por exemplo, para colocar um ícone do Vagalume para fazer uma requisição completa depois), você pode utilizar o parâmetro nolyrics (exemplo) na requisição para que não haja verificação de captcha (a letra da música não será enviada neste caso).