laut.fm Search-API

Dies ist eine kurze Übersicht über die öffentliche laut.fm Search-API. Sie ergänzt die normale laut.fm-API. Alles, was in der Dokumentation der normalen API über das Dokument-Format(JSON; UTF-8), Cache-Control Headers und den Zugriff per Javascript gesagt wird, gilt auch hier.

Im Moment existiert nur ein Endpunkt für die Search-API: http://api.laut.fm/search/stations?query…. Diese Dokumentation erklärt die möglichen Queries, weitere Parameter und die Struktur der Suchergebnisse.

Einfache Queries

Der Query-Parameter kann ein oder mehrere Wörter enthalten. Zum Beispiel /search/stations?query=Queen oder /search/stations?query=Foo Fighters. Werden mehrere Such-Wörter angegeben, wird eine UND-Suche durchgeführt. Das heißt im Fall von /search/stations?query=Foo Fighters wird nach Stationen gesucht, die sowohl für “Foo” also auch für “Fighters” in einer der Kategorien (siehe “Kategorien”) im Index sind.

Such-Wörter sind Case-Insensitive, ignorieren also Groß- und Kleinschreibung.

Kategorien

Der Index der Suche kennt verschiedene Kategorien. In diesen Kategorien kann gezielt gesucht werden (siehe “Kategorisierte Queries”) und die Suchergebnisse sind in diese Kategorien unterteilt (siehe “Suchergebnisse”). Dies sind die Kategorien in der Reihenfolge ihrer Gewichtung:

Der Bequemlichkeit halber gibt es eine Suche in allen Artist-Feldern:

Kategorisierte Queries

Die Suche kann auf eine oder mehrere Kategorien eingeschränkt werden. So liefert zum Beispiel /search/stations?query=name:foo alle Stationen, deren Name mit “foo” anfängt. Wird nach mehreren Wörtern gesucht, kann die Kategorieangabe für jedes einzelne Wort gemacht werden: /search/stations?query=genre,format:Lieblingssong genre,format:Indie findet Stationen, die als Genre oder im Format “Lieblingssongs” oder “Indie” eingetragen haben.

Für einige der Kategorien gibt es Kürzel, so zum Beispiel n für name (in der Kategorienliste in Klammern angegeben).

Such-Parameter

Die Suche kann mit weiteren Parametern verändert werden:

Suchergebnisse

In der Regel werden die Ergebnis-Kategorien in der oben angegebenen Reihenfolge zurückgegeben. Innerhalb der Kategorien sind die Stationen nach dem laut.fm-Rang sortiert. Zwei Ausnahmen sind current_artist und next_artist. Hier kommen Stationen zuerst, bei denen der Liedwechsel nicht lange zurückliegt. Top-Treffer sind also (im Wesentlichen) Stationen, bei denen das aktuelle Lied noch möglichst lange läuft.

Die Suchergebnisse sind kategorisiert, das heißt es ist ersichtlich, in welcher Kategorie eine Station gefunden wurde. Beispielhaft hier die Suche nach Foo Fighters

{
  total: 156,
  offset: 0,
  next_offset: 10,
  limit: 10,
  results: [
    {
      categories: [ [ "current_artist", "foo" ], [ "current_artist", "fighters" ] ],
      total: 2,
      items: [
        {
          station: {
            name: "antenne",
            page_url: "http://www.laut.fm/antenne",
            format: "Antenne Düsseldorf lauter:Rock",
            [... weitere Stations-Infos]
          }
          current_song: {
            id: 70805,
            title: "Rebell Yell",
            album: "New Wave & Pop Songs",
            created_at: "2008-08-08 17:03:50 +0200",
            started_at: "2011-11-24 13:49:19 +0100",
            length: 289,
            ends_at: "2011-11-24 13:54:08 +0100",
            type: "song",
            [weitere Song-Infos...]
          }
        },
        {
          station: {
            name: "stonerock",
            page_url: "http://www.laut.fm/stonerock",
            format: "",
            [... weitere Stations-Infos]
          },
          current_song: {
            id: 6239,
            title: "Goodbye",
            album: "Beautiful Morning",
            created_at: "2008-03-27 11:48:11 +0100",
            started_at: "2011-11-24 13:47:42 +0100",
            length: 202,
            ends_at: "2011-11-24 13:51:04 +0100",
            type: "song",
            [weitere Song-Infos...]
          }
        }
      ]
    },
    {
      categories: [ [ "next_artists", "foo" ], [ "next_artists", "fighters" ] ],
      total: 2,
      items: [
        {
          station: {
            name: "rockmag",
            page_url: "http://www.laut.fm/rockmag",
            format: "Rockmag-Radio",
            [... weitere Stations-Infos]
          },
          next_artists: "Foo Fighters, Dead By April, Wolfmother"
        },
        {
          station: {
            name: "rockvibes",
            page_url: "http://www.laut.fm/rockvibes",
            format: "Rock, Gothic, Indie, Medivial, NDH",
            [... weitere Stations-Infos]
          },
          next_artists: "Foo Fighters, Lake, L'Âme Immortelle"
        }
      ]
    },
    {
      categories: [ [ "all_artists", "foo" ], [ "all_artists", "fighters" ] ],
      total: 144,
      items: [
        {
          station: {
            name: "germanyfm",
            page_url: "http://www.laut.fm/germanyfm",
            format: "Der neue Pop Mix!",
            [... weitere Stations-Infos]
          }
        },
        {
          station: {
            name: "papa-mike",
            page_url: "http://www.laut.fm/papa-mike",
            format: "Metal, Punk-, Postrock, Indie, Klassiker & Aktuelles",
            [... weitere Stations-Infos]
          }
        },
        [4 weitere Stationen...]
      ]
    },
    {
      categories: [ [ "current_artist", "foo" ], [ "all_artists", "fighters" ] ],
      total: 2,
      items: [ ]
    },
    {
      categories: [ [ "next_artists", "foo" ], [ "all_artists", "fighters" ] ],
      total: 2,
      items: [ ]
    },
    {
      categories: [ [ "all_artists", "foo" ], [ "current_artist", "fighters" ] ],
      total: 2,
      items: [ ]
    },
    {
      categories: [ [ "all_artists", "foo" ], [ "next_artists", "fighters" ] ],
      total: 2,
      items: [ ]
    }
  ]
}

Das Suchergebnis ist ein Hash, der zuerst allgemeine Angaben zur Anzahl der Ergebnisse (total), den Parametern limit und offset und next_offset gibt.

Dann folgt der results-Array. Jedes Ergebnis ist wiederum ein Hash. Dieser enthält als erstes die Information darüber, in welcher Kategorie welche Suchbegriff gefunden wurde. Also z.B. categories: [["current_artist", "foo"], ["current_artist", "fighters"]]. Hier wurde sowohl der Begriff foo, als auch fighters in der Kategorie current_artist gefunden. Nach den Kategorien kommt die Anzahl Ergebnisse in dieser Suchwort-Kategorien-Kombination.

Und schließlich: die eigentlichen Ergebnisse im Array items. Die Ergebnisse selbst enthalten nicht nur die Stations-Informationen, sondern auch – wenn verfügbar – zusätzliche Informationen in Bezug auf die Ergebnis-Kategorie. Also z.B. der current_song in eben dieser Kategorie. So kann bei der Darstellung der Ergebnisse dem Benutzer auch vermittelt werden, warum etwas gefunden wurde.

Standardmäßig hat eine Suche ein limit von 10, das kann aber per Parameter verändert werden (siehe oben). Nach dem 10. Ergebnis werden alle weiteren Kategorien mit Treffern zwar angezeigt (auch inklusive der Angabe wie viele Treffer die Kategorie enthält), das items-Array jedoch ist einfach leer. So kann auch beim ersten Suchergebnis schon herausgefunden werden, in welchen Kategorien Treffer sind und wie viele.

Zu beachten ist, dass eine Station mehrfach