Use a API do streaming xCAST para mostrar no site a música tocando, o status da rádio e os ouvintes conectados, com exemplos em PHP e JavaScript.
A API do streaming entrega as informações da rádio em um endereço que qualquer site, app ou sistema consegue ler: se a rádio está no ar, a música que está tocando (com artista e capa), quantos ouvintes estão conectados e o histórico do que tocou. Ela está incluída em todos os planos xCAST, sem custo extra.
Onde fica a chave da sua rádio
- Painel BETA: menu Painel de Controle → API, página API & Integrações. Ali estão a KEY da rádio, os endereços prontos para copiar, exemplos e a criação de chaves privadas.
- Painel CLÁSSICO: a página de API mostra a KEY e os endereços de leitura da API antiga.
A KEY serve para as informações públicas da rádio: status, música atual, histórico e uptime. Dados de audiência (resumo de 7 e 30 dias, músicas mais tocadas, ouvintes por hora, mapa por cidade), playlists e agendamentos exigem uma chave privada, criada no painel BETA em Gerar nova chave. A documentação completa, com todos os endereços e formatos de resposta, fica em beta.xcast.com.br/api-v2/docs.
Os endereços mais usados (API v2, em JSON)
| Endereço | O que devolve |
|---|---|
/api-v2/status/SUA_KEY | Status, ouvintes conectados, música atual, artista, capa, bitrate e mais |
/api-v2/now-playing/SUA_KEY | Só o "tocando agora": artista, música, capa e próxima música |
/api-v2/historico/SUA_KEY | As últimas músicas tocadas (até 50) |
/api-v2/uptime/SUA_KEY | Responde normal com a rádio no ar e com erro 503 fora do ar, para serviços de monitoramento |
O endereço completo é o da documentação seguido do caminho, por exemplo https://beta.xcast.com.br/api-v2/now-playing/SUA_KEY. Uma resposta resumida:
{
"sucesso": true,
"status": "Ligado",
"artista": "Nome do Artista",
"musica": "Nome da Música",
"capa_musica": "https://...",
"proxima_musica": "",
"titulo": "Nome da Rádio"
}Exemplo em PHP: mostrar os ouvintes conectados
<?php
$url = 'https://beta.xcast.com.br/api-v2/status/SUA_KEY';
$json = @file_get_contents($url);
$dados = $json ? json_decode($json, true) : null;
if ($dados && isset($dados['ouvintes_conectados'])) {
echo 'Ouvintes agora: ' . (int) $dados['ouvintes_conectados'];
} else {
echo 'Rádio indisponível no momento';
}Em vez de consultar a API a cada visita, guarde a resposta por alguns segundos no seu site. As respostas já são mantidas em cache por cerca de 10 segundos, então consultar mais rápido que isso não traz dado mais novo.
Exemplo em JavaScript: "tocando agora" na página
<div id="tocando">Carregando...</div>
<script>
async function atualizarTocando() {
try {
const r = await fetch('https://beta.xcast.com.br/api-v2/now-playing/SUA_KEY');
const d = await r.json();
document.getElementById('tocando').textContent =
d.sucesso ? d.artista + ' - ' + d.musica : 'Fora do ar';
} catch (e) {
document.getElementById('tocando').textContent = 'Fora do ar';
}
}
atualizarTocando();
setInterval(atualizarTocando, 20000);
</script>A API aceita chamadas direto do navegador (CORS liberado) e até 120 consultas por minuto por IP.
Sem programar: o widget de uma linha
Cole esta linha no HTML do site, trocando SUA_KEY pela KEY da rádio. Ela mostra a capa, a música e o artista e se atualiza sozinha:
<script src="https://beta.xcast.com.br/xc-nowplaying.js" data-key="SUA_KEY" async></script>Já usa a API antiga?
Ela continua funcionando: os endereços em XML e em JSON que aparecem na página de API do painel seguem no ar, e o endpoint status da v2 usa os mesmos nomes de campo, como status, ouvintes_conectados, musica_atual e plano_bitrate. Para migrar, basta trocar o endereço pelo da v2 e ler JSON em vez de XML. A v2 responde bem mais rápido.
Segurança
- A KEY só dá acesso a informações públicas da rádio. Pode ir no código do site.
- Chaves privadas de leitura liberam dados de audiência: use no servidor, não no navegador.
- Chaves de controle executam comandos na rádio, como ligar e desligar. Trate como senha, restrinja por IP no painel e nunca coloque no código de um site ou app.
Problemas comuns
A resposta diz que a KEY é inválida
Copie a KEY de novo na página de API do painel, sem espaços. Ela é diferente da porta e da senha da rádio.
A resposta diz que precisa de chave
O dado pedido é de audiência ou de programação. Crie uma chave privada de leitura no painel BETA e use no lugar da KEY.
Erro 429
Consultas demais em pouco tempo. Aumente o intervalo entre as chamadas ou guarde a resposta em cache no seu site.
