Föderierte Suche

Überblick

/v2/search/federated durchsucht alle drei Sammlungen des Kulturpools in einer Anfrage — Digitalisate, redaktionelle Seiten und die Wissensdatenbank — und liefert Treffer, die sich mit einer einzigen Darstellung rendern lassen.

Basis-URL

https://api.kulturpool.at/v2/search/federated

Parameter

Parameter	Typ	Standard	Beschreibung
q	string	–	Pflicht. Der Suchbegriff
collections	string	chos,editorial,knowledge	Sammlungen, kommagetrennt, in Antwortreihenfolge
per_page	integer	10	Treffer je Sammlung (1–250)
filter_by	string	–	Filterausdruck, auf alle Sammlungen angewandt
facet_by	string	–	Facetten; standardmäßig aus
max_facet_values	integer	50	Facettenwerte je Facette

curl "https://api.kulturpool.at/v2/search/federated?q=Klimt&per_page=5"

Antwort

Ein Ergebnis je Sammlung, in der angefragten Reihenfolge:

{
  "results": [
    {"found": 1529, "hits": [/* chos */]},
    {"found": 15,   "hits": [/* editorial */]},
    {"found": 5,    "hits": [/* knowledge */]}
  ]
}

Jedes Element hat dasselbe Format wie eine Antwort der Suche.

Die gemeinsamen Felder

Der Sinn der föderierten Suche ist, dass ein Treffer darstellbar ist, ohne zu wissen, welche Sammlung geantwortet hat. Dafür tragen alle drei dieselben Kernfelder:

Feld	Typ	Beschreibung
docType	string	Was für ein Treffer das ist — siehe unten
title	string	Überschrift
description	string[]	Kurztext
url	string	Die Seite, die ein Klick öffnen soll
docLanguage	string	Sprache des Dokuments
updatedAt	int64	Zeitpunkt der letzten Änderung
previewImage	string	Vorschaubild, sofern vorhanden

docType unterscheidet die Trefferarten:

docType	Sammlung	Was es ist
cho	chos	Ein Digitalisat
institution	editorial	Ein Institutionsprofil
contentPage	editorial	Eine redaktionelle Seite
wikiPage	knowledge	Eine Seite der Wissensdatenbank

Darüber hinaus trägt jede Sammlung ihre eigenen Felder — dataProvider und die Rechteangaben bei chos, place und legalName bei Institutionen, book und chapter bei der Wissensdatenbank.

const {results} = await fetch(
  'https://api.kulturpool.at/v2/search/federated?q=Klimt&per_page=5',
).then((r) => r.json());

for (const result of results) {
  for (const {document} of result.hits) {
    console.log(document.docType, '·', document.title, '→', document.url);
  }
}

Nach Sprache eingrenzen

docLanguage sagt, in welcher Sprache ein Dokument verfasst ist. Redaktionelle Seiten und Wiki-Seiten sind de oder en — je Sprache ein eigenes Dokument.

Digitalisate tragen mul („mehrere“, ISO 639-2): ein Objektdatensatz ist nicht in einer Sprache geschrieben, sondern trägt mehrsprachige Metadaten.

Eine deutschsprachige Suche filtert deshalb auf beides:

curl "https://api.kulturpool.at/v2/search/federated?q=Klimt&filter_by=docLanguage:%5Bde,mul%5D"

filter_by=docLanguage:[de,mul]

Einzelne Sammlungen

collections bestimmt Auswahl und Reihenfolge:

# Nur redaktionelle Inhalte und Wissensdatenbank
curl "https://api.kulturpool.at/v2/search/federated?q=IIIF&collections=editorial,knowledge"

Eine einzelne Sammlung durchsuchen Sie einfacher über die Suche mit collection=… — dort stehen auch Facetten und Sortierung zur Verfügung.

Fehlerbehandlung

Code	Bedeutung
422	q fehlt, oder collections nennt eine unbekannte Sammlung
502	Die Suchmaschine ist nicht erreichbar

{
  "detail": "Unbekannte Sammlung(en): buecher. Erlaubt: chos, editorial, knowledge."
}

Facetten über Sammlungen hinweg

Facetten sind hier standardmäßig aus, weil sie je Sammlung getrennt gezählt werden und sich nicht sinnvoll zu einer Liste zusammenfassen lassen. Wenn Sie Facetten brauchen, fragen Sie die betreffende Sammlung über die Suche einzeln ab.