Aller au contenu
radioonair

API et applications

L'API publique de radioonair alimente les applications Roku, Fire TV, Android TV, Apple TV, iOS et Android, ainsi que les sites partenaires : annuaire des radios, flux, pré-roll vidéo et statistiques d'écoute. Les réponses sont en JSON (UTF-8), sauf la publicité qui suit le standard VAST 4.2.

Démarrer

Adresse de base : https://radioonair.fr/api/v1

Chaque application s'identifie avec l'en-tête X-Api-Key. Les clés sont délivrées par radioonair, une par application : demandez la vôtre à contact@radioonair.fr. L'en-tête est facultatif pour l'instant, il deviendra obligatoire : envoyez-le dès maintenant. Quand vous ne pouvez pas ajouter d'en-tête (URL VAST confiée à un SDK publicitaire), ajoutez api_key=VOTRE_CLE à l'adresse.

Les erreurs renvoient un code HTTP et un message en français : 401 pour une clé manquante ou invalide (quand la clé est exigée), 404 pour une radio ou un article introuvable. L'API accepte les appels depuis un navigateur (CORS ouvert).

curl -H "X-Api-Key: VOTRE_CLE" "https://radioonair.fr/api/v1/stations?genre=jazz-blues&perPage=20"

Annuaire

GET/stations

Liste et recherche des radios publiées, les plus écoutées d'abord.
q
recherche dans le nom, la ville et le slogan
genre
slug d'un genre (voir /genres), par exemple jazz-blues
country
code pays ISO à deux lettres, par exemple BE
region
slug d'une région, par exemple fr-bretagne
sort
popular (par défaut), recent ou name
page, perPage
pagination, 24 radios par page par défaut, 100 au plus
slugs
liste de slugs séparés par des virgules (favoris) : renvoie ces radios dans cet ordre, sans pagination

Exemple de réponse

{
  "items": [
    {
      "id": "6f1c2a7e-4b1d-4c8e-9a51-0e3f7d2b9c10",
      "slug": "radio-exemple",
      "name": "Radio Exemple",
      "tagline": "La radio de la vallée",
      "logo": "https://radioonair.fr/media/logos/6f1c2a7e.webp",
      "url": "https://radioonair.fr/radio/radio-exemple",
      "city": "Annecy",
      "region": "Auvergne-Rhône-Alpes",
      "country": "FR",
      "genres": [
        "Hits",
        "Locale et proximité"
      ],
      "online": true,
      "nowPlaying": "Artiste - Titre"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

GET/stations/{slug}

Tout ce qu'il faut pour lire une radio (le slug ou l'identifiant). streams donne les flux dans l'ordre de préférence, en HLS (hls) ou en progressif (mp3, aac, ogg, opus, flac) : lisez le premier qui fonctionne. Les flux disponibles uniquement en http sont relayés en https par radioonair.

Exemple de réponse

{
  "station": {
    "id": "6f1c2a7e-4b1d-4c8e-9a51-0e3f7d2b9c10",
    "slug": "radio-exemple",
    "name": "Radio Exemple",
    "tagline": "La radio de la vallée",
    "logo": "https://radioonair.fr/media/logos/6f1c2a7e.webp",
    "url": "https://radioonair.fr/radio/radio-exemple",
    "city": "Annecy",
    "region": "Auvergne-Rhône-Alpes",
    "country": "FR",
    "genres": [
      "Hits",
      "Locale et proximité"
    ],
    "online": true,
    "nowPlaying": "Artiste - Titre",
    "streams": [
      {
        "id": "0b8e…",
        "url": "https://flux.radio-exemple.fr/live/playlist.m3u8",
        "format": "hls",
        "bitrate": 128
      },
      {
        "id": "51c4…",
        "url": "https://radioonair.fr/stream/51c4…",
        "format": "mp3",
        "bitrate": 128
      }
    ],
    "description": "…",
    "website": "https://radio-exemple.fr",
    "fm": "98.2 MHz (Annecy)",
    "dab": null
  }
}

GET/genres

Les genres, avec le nombre de radios publiées dans chacun.

Exemple de réponse

{
  "items": [
    {
      "slug": "hits",
      "name": "Hits",
      "count": 412
    },
    {
      "slug": "jazz-blues",
      "name": "Jazz et blues",
      "count": 57
    }
  ]
}

GET/home

L'écran d'accueil d'une application en un seul appel : radios mises en avant, les plus écoutées, les dernières inscrites, les genres et les derniers articles.

Exemple de réponse

{
  "featured": [
    {
      "id": "6f1c2a7e-4b1d-4c8e-9a51-0e3f7d2b9c10",
      "slug": "radio-exemple",
      "name": "Radio Exemple",
      "tagline": "La radio de la vallée",
      "logo": "https://radioonair.fr/media/logos/6f1c2a7e.webp",
      "url": "https://radioonair.fr/radio/radio-exemple",
      "city": "Annecy",
      "region": "Auvergne-Rhône-Alpes",
      "country": "FR",
      "genres": [
        "Hits",
        "Locale et proximité"
      ],
      "online": true,
      "nowPlaying": "Artiste - Titre"
    }
  ],
  "popular": [
    "…"
  ],
  "recent": [
    "…"
  ],
  "genres": [
    {
      "slug": "hits",
      "name": "Hits",
      "count": 412
    }
  ],
  "articles": [
    {
      "slug": "le-dab-arrive-dans-la-vallee",
      "title": "Le DAB+ arrive dans la vallée",
      "excerpt": "Douze radios rejoignent le multiplex local.",
      "category": "dab",
      "publishedAt": "2026-11-06T08:00:00.000Z",
      "aiGenerated": true,
      "url": "https://radioonair.fr/actu/le-dab-arrive-dans-la-vallee",
      "image": "https://radioonair.fr/actu/le-dab-arrive-dans-la-vallee/opengraph-image"
    }
  ]
}

Actu

GET/articles

Les derniers articles publiés. image est une image 1200 × 630 générée pour chaque article.
category
rubrique, par exemple audiences ou dab
page, perPage
pagination, 12 articles par page par défaut, 50 au plus

Exemple de réponse

{
  "items": [
    {
      "slug": "le-dab-arrive-dans-la-vallee",
      "title": "Le DAB+ arrive dans la vallée",
      "excerpt": "Douze radios rejoignent le multiplex local.",
      "category": "dab",
      "publishedAt": "2026-11-06T08:00:00.000Z",
      "aiGenerated": true,
      "url": "https://radioonair.fr/actu/le-dab-arrive-dans-la-vallee",
      "image": "https://radioonair.fr/actu/le-dab-arrive-dans-la-vallee/opengraph-image"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

GET/articles/{slug}

Un article complet. html ne contient que des balises simples (titres, paragraphes, listes, liens, citations).

Exemple de réponse

{
  "article": {
    "slug": "le-dab-arrive-dans-la-vallee",
    "title": "Le DAB+ arrive dans la vallée",
    "excerpt": "Douze radios rejoignent le multiplex local.",
    "category": "dab",
    "publishedAt": "2026-11-06T08:00:00.000Z",
    "aiGenerated": true,
    "url": "https://radioonair.fr/actu/le-dab-arrive-dans-la-vallee",
    "image": "https://radioonair.fr/actu/le-dab-arrive-dans-la-vallee/opengraph-image",
    "html": "<p>…</p><h2>…</h2><p>…</p>",
    "tags": [
      "DAB+",
      "Annecy"
    ],
    "sources": [
      {
        "title": "Communiqué du multiplex",
        "url": "https://exemple.fr/communique"
      }
    ],
    "author": "La rédaction",
    "updatedAt": "2026-11-06T08:00:00.000Z"
  }
}

Publicité et écoute

GET/ads/vast?station={id}&device={roku|firetv|androidtv|tvos|ios|android}

Le pré-roll à jouer avant la radio, au format VAST 4.2 : une vidéo MP4 1080p, ou un renvoi vers la régie d'un annonceur. Un <VAST/> vide signifie qu'il n'y a pas de publicité : lancez le flux directement. Appelez cette adresse à chaque lancement : le serveur choisit lui-même quand diffuser une publicité (au plus une toutes les 5 minutes pour un même auditeur).

Réponse sans publicité

<?xml version="1.0" encoding="UTF-8"?><VAST version="4.2" xmlns="http://www.iab.com/VAST"></VAST>

POST/sessions

Ouvre une session d'écoute quand le son démarre vraiment. preroll indique si une publicité a été jouée juste avant, platform le nom et la version de l'application. Si id vaut null, l'écoute n'est pas comptée : continuez sans envoyer de ping.

Corps de la requête, puis réponse

{
  "station": "6f1c2a7e-4b1d-4c8e-9a51-0e3f7d2b9c10",
  "device": "roku",
  "preroll": true,
  "platform": "radioonair-roku/1.0.0"
}

{
  "id": "a3f0c9d2-…"
}

POST/sessions/{id}/ping

À envoyer toutes les 60 secondes pendant l'écoute. Une session restée muette plus de 10 minutes est fermée : si la réponse est { "ok": false }, ouvrez-en une nouvelle.

Exemple de réponse

{
  "ok": true
}

POST/sessions/{id}/stop

À envoyer quand l'auditeur arrête la radio, change de station ou quitte l'application.

Exemple de réponse

{
  "ok": true
}

Intégrer le lecteur

Quand l'auditeur choisit une radio :

  1. récupérez la radio et ses flux avec GET /stations/{slug} ;
  2. demandez le pré-roll avec GET /ads/vast et jouez-le s'il y en a un ;
  3. lancez ensuite le premier flux qui fonctionne ;
  4. quand le son démarre, ouvrez une session (POST /sessions), envoyez un ping toutes les 60 secondes, puis stop à la fin.

Roku : passez l'adresse VAST au Roku Advertising Framework (setAdUrl(), puis getAds() et showAds()) et lancez le flux quand la publicité est terminée.

iOS, Android, Fire TV, Android TV et Apple TV : utilisez le SDK Google IMA avec l'adresse VAST comme adTagUrl, et lancez le flux quand le SDK demande la reprise du contenu (CONTENT_RESUME_REQUESTED) ou signale une erreur.

Ne déclenchez aucun suivi vous-même : impressions, quartiles, clics et erreurs sont décrits dans le VAST et le SDK les envoie. Si la publicité n'a pas démarré au bout de 4 secondes, abandonnez-la et lancez la radio : l'écoute passe avant la publicité.

https://radioonair.fr/api/v1/ads/vast?station=6f1c2a7e-4b1d-4c8e-9a51-0e3f7d2b9c10&device=roku&api_key=VOTRE_CLE

Description OpenAPI

La description complète de l'API au format OpenAPI 3.1 est disponible à l'adresse https://radioonair.fr/api/v1/openapi.json. Elle s'importe dans Postman, Insomnia ou un générateur de client.

Une question, une clé à demander ou un partenariat : contact@radioonair.fr.