Dies ist eine kurze Übersicht über die öffentliche laut.fm API. Die verbindliche Referenz ist im JSON-Format verfügbar. Zum Browsen der Referenz empfehlen wir das JSONView-Plugin für Firefox oder für Chrome. Diese Plugins formatieren die Ergebnisse, inklusive Syntax-Highlighting. URLs werden verlinkt.
Die API exponiert allgemeine Informationen über laut.fm (“Welche Genres gibt es?”, “Wie ist der Status des Servers?”), Auflistungen von Stationen (alle, nach Anfangsbuchstaben, nach Genres) und Informationen über einzelne Stationen (allgemeine Infos, der aktuelle Track, das Netzwerk).
Ergänzt wird die normale laut.fm-API durch die laut.fm-Search-API.
Das Rückgabeformat der laut.fm API ist JSON. JSON Bibliotheken sind in allen gängigen Programmiersprachen verfügbar.
Das Encoding ist immer UTF-8.
Ausserdem exponieren wir die Daten der API in diesen weiteren Formaten:
Etag-/If-None-Match- und Last-Modified-/If-Modified-Since-Support)Der API-Server setzt korrekte Cache-Control Headers: Cache-Control, Expires, Age, Date. If-Modified-Since im Request wird unterstützt. Etag wird (noch) nicht unterstützt. Im Idealfall cached der Client entsprechend der vom Server gesetzten Header.
Um den API-Zugriff per Javascript so einfach, wie irgendwie möglich zu machen, haben wir eine Javascript-Bibliothek entwickelt. Diese Bibliothek ist – inklusive vieler einfacher Beispielen – bei Github gehostet. Sie ermöglich nicht nur die Benutzung der normalen API, sondern auch der Such-API und enthält sogar einen komplett per Javascript steuerbaren Player.
Wer trotzdem “zu Fuß” per Javascript zugreifen will, kann sich an unserer Javascript-Bibliothek orientieren.
Bei sämtlichen /stations.*-Requests werden die parameter limit und offset berücksichtigt. Wird nur ein limit-Parameter übergeben, ist das Rückgabeformat mit dem ohne Parameter identisch: Top-10 Stationen. Wird ein offset-Parameter angegeben, enthält die Antwort zusätzlich Metadaten für die Pagination:
total: die Gesamtanzahl der Ergebnisse.limit: das aktuell angegebene Limit.offset: das aktuell angegebene Offset.next_offset: das Offset für die nächste Seite. NULL, falls die letzte Seite schon erreicht ist.Unter dem Key items ist dann ein Array von Stationen abgelegt, dem dem Format einer Abfrage ohne offset entspricht.
Wird diese API im Kontext einer Website über Javascript genutzt, so können Besucher der Website mit diesem Passus in der Datenschutzerklärung über die API-Verbindung aufgeklärt werden:
Diese Website benutzt die öffentliche laut.fm-API. Die laut.fm-API ist ein Dienst der LAUT AG und exponiert allgemeine Informationen über laut.fm, Auflistungen von Stationen und Informationen über einzelne Stationen. Bei Zugriff auf die API werden automatisch Informationen allgemeiner Natur an laut.fm übertragen. Diese Informationen beinhalten etwa die IP-Adresse, die Art des Webbrowsers und des verwendete Betriebssystems, den Domainnamen Ihres Internet Service Providers und Ähnliches. Hierbei handelt es sich ausschließlich um Informationen, welche keine Rückschlüsse auf Ihre Person zulassen. Diese Informationen sind technisch notwendig, um beispielsweise den aktuell laufenden Titel korrekt auszuliefern und fallen bei Nutzung des Internets zwingend an. Anonyme Informationen dieser Art werden von der LAUT AG nur kurzfristig gespeichert und gegebenenfalls statistisch ausgewertet, um die API und die dahinterstehende Technik zu optimieren.