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.
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.
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:
name (n): Der Name einer Station.current_artist: Der aktuelle Artist einer Station.next_artists: Die nächsten drei Artists einer Station.format (n): Das Format einer Station.genres (g): Die Genres einer Station.all_artists: Die meist-genutzten Artist einer Station.Der Bequemlichkeit halber gibt es eine Suche in allen Artist-Feldern:
artists (a): Expandiert zu current_artist,next_artists,all_artists.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).
Die Suche kann mit weiteren Parametern verändert werden:
limit: Limitiert auf die angegebene Anzahl von Ergebnissen: /search/stations?query=Queen&limit:20offset: Liefert Ergebnis mit dem angegebenen Offset zurück: /search/stations?query=Queen&limit:20&offset:50just_names: Liefert nicht die kompletten Stations-Infos in den Ergebnissen, sondern nur Stations-Namen, wenn auf true gesetzt: /search/stations?query=Queen&just_names=trueIn 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 als Ergebnis aufgelistet werden kann, und zwar potentiell in jeder Suchwort-Kategorie-Kombination. Intern wird eine Station, gefunden aufgrund zwei verschiedener Kriterien (Treffer in current_artist, Treffer in all_artists) als zwei Suchtreffer gehandhabt. Will man dem Benutzer keine Doubletten anzeigen, muss man im Client filtern.