Suche API

Überblick

/v2/search durchsucht den Kulturpool über die Suchmaschine Typesense. Die API reicht die Anfrage an den Suchindex weiter und ergänzt den Schlüssel serverseitig — Sie suchen ohne Authentifizierung.

Basis-URL

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

Sammlungen

Der Index besteht aus drei Sammlungen. collection wählt aus, welche durchsucht wird:

`collection`	Inhalt
`chos` (Standard)	Digitalisate — Objekte, Werke, Dokumente
`editorial`	Redaktionelle Seiten und Institutionsprofile
`knowledge`	Die Wissensdatenbank (wissen.kulturpool.at)

Für eine Suche über alle drei in einer Anfrage siehe Föderierte Suche.

Parameter

Pflicht

Parameter	Typ	Beschreibung
`q`	string	Der Suchbegriff, z.B. `Wien`, `Porträt`, `Albertina`. `*` liefert alles.

Optional

Parameter	Typ	Standard	Beschreibung
`collection`	string	`chos`	Zu durchsuchende Sammlung
`query_by`	string	je Sammlung	Kommagetrennte Liste der zu durchsuchenden Felder
`filter_by`	string	–	Filterausdruck, z.B. `dataProvider:=Albertina`
`sort_by`	string	–	Sortierung, z.B. `titleKey:asc`
`page`	integer	`1`	Seitennummer
`per_page`	integer	`20`	Treffer pro Seite (1–250)
`facet_by`	string	je Sammlung	Kommagetrennte Facetten; leerer Wert schaltet sie ab
`max_facet_values`	integer	`50`	Facettenwerte je Facette (max. 1000)
`highlight_full_fields`	string	`title,description,creator,subject`	Felder für vollständiges Highlighting
`use_cache`	boolean	`true`	Typesense-internen Cache verwenden

Standard für query_by und facet_by je Sammlung:

chos

query_by=title,description,creator,subject,dataProvider,alternative,contributor,
         publisher,medium,spatial,temporal,dcType,isPartOf,identifier,coverage,
         provenance

facet_by=dataProvider,creator,edmType,dcType,subject,medium,isPartOf,edmRightsName,
         edmRightsReusePolicy,dateMin,intermediateProvider,pipelineId,mediaTypes,
         imageOrientation,hasIiifManifest,hasInstitutionalIiifManifest

editorial

query_by=title,body,description,legalName,providerNames
facet_by=docType,docLanguage,category,place,providerNames

knowledge

query_by=title,body,description
facet_by=docType,docLanguage,book,chapter

Weitere Typesense-Parameter

Alle nicht aufgeführten Parameter werden unverändert an Typesense durchgereicht. Damit steht die gesamte Suchoptionen-Palette zur Verfügung:

Parameter	Beispiel	Beschreibung
`prefix`	`prefix=false`	Präfix-Suche ein-/ausschalten
`num_typos`	`num_typos=1`	Erlaubte Tippfehler
`infix`	`infix=always`	Treffer innerhalb von Wörtern
`group_by`	`group_by=dataProvider`	Treffer gruppieren
`include_fields`	`include_fields=uuid,title`	Nur diese Felder liefern

Eine vollständige Liste finden Sie in der Typesense Search Parameters Referenz.

Standardmäßig ausgeschlossene Felder

sourceRecord und die beiden Embedding-Vektoren werden nicht mitgeliefert — zusammen rund 8,6 KB pro Treffer, also etwa 170 KB auf einer Seite mit 20 Treffern. Mit exclude_fields oder include_fields lässt sich das überschreiben; sourceRecord liefert die Objekt API ohnehin einzeln aus.

Felder

Beschreibung und Anzeige

Feld	Typ	Beschreibung
`uuid`	string	Die Kulturpool-ID. Schlüssel für Objekt und Ähnlichkeitssuche
`title`	string	Titel des Objekts
`description`	string[]	Beschreibungen, je Wert auf 1024 Zeichen gekürzt
`alternative`	string[]	Alternativtitel
`provenance`	string[]	Provenienz: frühere Eigentümer:innen, Art der Erwerbung. Durchsuchbar, nicht facettierbar
`previewImage`	string	Vorschaubild (400 px)
`url`	string	Die Objektseite auf kulturpool.at

Personen und Institutionen

Feld	Typ	Facette
`dataProvider`	string	✓
`creator`	string[]	✓
`contributor`	string[]	durchsuchbar, nicht facettierbar
`publisher`	string[]	durchsuchbar, nicht facettierbar
`intermediateProvider`	string[]	✓
`pipelineId`	string	✓ — die Datenquelle

Klassifikation

Feld	Typ	Facette
`edmType`	string[]	✓ — `IMAGE`, `VIDEO`, `SOUND`, `TEXT`, `3D`
`dcType`	string[]	✓ — z.B. „Fotografie“, „Plakat“
`subject`	string[]	✓
`medium`	string[]	✓
`isPartOf`	string[]	✓
`identifier`	string[]	–

edmType kann mehrere Werte tragen, wenn die Dateien eines Objekts anderer Art sind als das Objekt selbst — etwa der Scan (IMAGE) eines Briefs (TEXT). Ein Filter auf einen der beiden Werte findet ihn. Der erste Wert ist der Typ des Objekts.

Zeit und Raum

Feld	Typ	Facette
`dateMin` / `dateMax`	int64	✓ — Unix-Zeitstempel (UTC), sortierbar
`date`	string[]	– — die genaueste Datierung im Originalwortlaut
`spatial`, `coverage`, `temporal`	string[]	–

date enthält die Entstehungsangabe des Datensatzes, sonst die Angabe zur Veröffentlichung, sonst ein allgemeines Datum. dateMin und dateMax beruhen auf derselben Angabe; fehlt sie, auf temporal.

Rechte

Feld	Typ	Facette	Beschreibung
`edmRightsName`	string[]	✓	`Public Domain`, `CC BY`, `CC BY-SA`, `InC`, `Andere`, …
`edmRightsReusePolicy`	string[]	✓	Die Regelungen der Rechteangaben: `OPEN`, `RESTRICTED`, `CLOSED`, jede höchstens einmal
`edmRights`	string[]	✗	Die Rechte-URIs. Wird mitgeliefert, ist aber nicht filterbar
`dcRights`	string[]	✗	Die Rechteinhaber, etwa für eine Quellenangabe. Wird mitgeliefert, ist aber nicht filterbar

Ein Objekt, mehrere Rechteangaben

Ein Datensatz kann mehrere Rechteangaben tragen — etwa ein gemeinfreier Scan eines urheberrechtlich geschützten Werks. Deshalb sind alle vier Felder Listen.

„Was darf ich nachnutzen?“ beantwortet filter_by=edmRightsReusePolicy:=OPEN: Es findet jeden Datensatz, bei dem mindestens eine Rechteangabe die freie Nachnutzung erlaubt. Für ein einzelnes Abzeichen zeigen Sie die freieste Regelung der Liste — OPEN vor RESTRICTED vor CLOSED.

Medien und IIIF

Feld	Typ	Facette	Beschreibung
`mediaCount`	int32	✓	Digitalisate am Datensatz
`imageCount`	int32	✓	Bilder darunter
`mediaTypes`	string[]	✓	z.B. `["image", "video"]`
`imageMegapixel`	float	–	Größe des Bilds, das das Vorschaubild zeigt, in Megapixeln, auf zwei Stellen gerundet
`imageAspectRatio`	float	–	Seitenverhältnis, Breite durch Höhe
`imageOrientation`	string	✓	`portrait`, `landscape`, `square`
`hasIiifManifest`	bool	✓	Ein IIIF-Manifest ist verfügbar
`hasInstitutionalIiifManifest`	bool	✓	Das Manifest stammt von der Institution selbst
`iiifManifest`	string	✗	Die Manifest-URL. Nicht filterbar — nutzen Sie `hasIiifManifest`

Fehlend ist nicht null

Die Felder mediaCount, imageCount und die Bildangaben (imageMegapixel, imageAspectRatio, imageOrientation) fehlen, wenn über die Medien eines Datensatzes nichts bekannt ist. 0 bedeutet „bekannt, und es gibt nichts“ — das ist eine andere Aussage. Prüfen Sie auf Vorhandensein, nicht auf Wahrheitswert.

Das gilt auch beim Filtern: Eine verneinte Bedingung trifft auf Datensätze ohne das Feld zu. imageCount:!=0 findet also auch Datensätze, deren Medien unbekannt sind — imageCount:>0 nur solche mit mindestens einem Bild.

Ein Bild in EDM object ist außerdem kein eigenes Digitalisat: es ist die Vorschau zu isShownBy. Ein Datensatz mit einer Fotografie und deren Vorschaubild meldet daher imageCount: 1, nicht 2.

Farben

Aus dem Vorschaubild bestimmt. Ein Datensatz ohne Vorschaubild trägt keines dieser Felder.

Feld	Typ	Facette	Beschreibung
`imageColor`	string	✓	Die Farbe, die den größten Teil des Bilds einnimmt: `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `white`, `gray`, `black`, `brown`
`imageColorIsGrayscale`	bool	✓	Ein Schwarz-Weiß-Bild. Ein kleiner farbiger Rest, etwa eine Farbkarte am Rand, ändert daran nichts
`imageColorScore`	float	–	Wie stark `imageColor` das Bild prägt, 0–1: wie viel Fläche sie einnimmt und wie kräftig sie ist. Zum Sortieren

Nach Farbe suchen

Ein Filter auf imageColor allein findet auch die graue Vase mit einem blassen blauen Stich. Sortieren Sie nach imageColorScore, damit die Bilder oben stehen, in denen die Farbe tatsächlich auffällt:

GET /v2/search?q=*&filter_by=imageColor:=blue&sort_by=imageColorScore:desc

Bei white, gray und black misst der Wert nur die Fläche.

Sammlungsübergreifende Felder

Diese vier tragen alle drei Sammlungen, damit ein Treffer ohne Kenntnis seiner Herkunft dargestellt werden kann — siehe Föderierte Suche.

Feld	Wert in `chos`
`docType`	`"cho"`
`docLanguage`	`"mul"` (mehrsprachige Metadaten)
`updatedAt`	Zeitpunkt der Veröffentlichung, sortierbar
`url`	Die Objektseite auf kulturpool.at

Filtern

# Nur Objekte einer Institution
filter_by=dataProvider:=Albertina

# Nur Bilder
filter_by=edmType:=IMAGE

# Nur Gemeinfreies
filter_by=edmRightsName:="Public Domain"

# Alles, was nachgenutzt werden darf
filter_by=edmRightsReusePolicy:=OPEN

# Nach 1900 entstanden
filter_by=dateMin:>=-2208988800

# Bilder ab 2 Megapixel
filter_by=imageMegapixel:>=2

# Grüne Bilder
filter_by=imageColor:=green

# Schwarz-Weiß
filter_by=imageColorIsGrayscale:=true

# Nur Datensätze mit echtem IIIF-Manifest der Institution
filter_by=hasInstitutionalIiifManifest:=true

# UND-Verknüpfung
filter_by=dataProvider:=Albertina && edmType:=IMAGE

# ODER-Verknüpfung
filter_by=dataProvider:=[Albertina,Belvedere]

# Enthält
filter_by=creator:*Mozart*

Bei Listenfeldern trifft := auf jedes Element zu: edmRightsName:="CC BY" findet jeden Datensatz, der diese Angabe unter mehreren trägt.

Werte mit Klammern

Typesense liest runde Klammern als Gruppierung. Filterwerte mit literalen Klammern werden von der API automatisch von Anführungszeichen auf Backticks umgeschrieben — Sie schreiben wie gewohnt:

filter_by=medium:="Papier (als Schreibmaterial)"

Ein leerer Wert (filter_by=) gilt als „kein Filter“.

Sortieren

Jeweils gefolgt von :asc oder :desc.

Feld	Beschreibung
`titleKey`	Alphabetisch nach Titel
`dateMin` / `dateMax`	Chronologisch
`dataProvider`	Nach Institution
`updatedAt`	Nach Aktualisierung
`imageColorScore`	Wie stark die Farbe das Bild prägt — zusammen mit einem Filter auf `imageColor`, siehe Farben
`_rand()`	Zufällige Reihenfolge

Ohne sort_by gilt die Relevanzsortierung der Suchmaschine.

warnung

titleKey ist nicht der Titel

titleKey ist ein undurchsichtiger Zahlenwert, der ausschließlich dazu dient, alphabetisch sortieren zu können: die ersten zehn Zeichen des Titels, auf Kleinbuchstaben normalisiert und zu einer Zahl gepackt, sodass numerische Reihenfolge alphabetischer entspricht. Nicht-lateinische Titel werden dafür umschriftet — Χάρτης sortiert unter „cha“.

Zeigen Sie ihn nicht an und interpretieren Sie ihn nicht. Für die Anzeige nutzen Sie title.

Datensätze ohne Titel tragen keinen Schlüssel und stehen aufsteigend am Ende, absteigend am Anfang.

Zufällige Reihenfolge

sort_by=_rand() wird automatisch zu _rand():asc ergänzt. Kombinieren Sie es mit use_cache=false, damit jeder Aufruf tatsächlich neu mischt:

GET /v2/search?q=*&sort_by=_rand()&use_cache=false

Beispielanfragen

# Einfache Suche
curl "https://api.kulturpool.at/v2/search?q=Wien"

# Mit Filter und Sortierung
curl "https://api.kulturpool.at/v2/search?q=Portr%C3%A4t&filter_by=dataProvider:=Albertina&sort_by=dateMin:asc"

# Mit Facetten
curl "https://api.kulturpool.at/v2/search?q=Landschaft&facet_by=creator,medium&max_facet_values=20"

# Redaktionelle Inhalte
curl "https://api.kulturpool.at/v2/search?q=Klimt&collection=editorial"

JavaScript

const params = new URLSearchParams({
  q: 'Porträt',
  filter_by: 'edmType:=IMAGE && edmRightsReusePolicy:=OPEN',
  facet_by: 'dataProvider,creator',
  per_page: '24',
});

const response = await fetch(`https://api.kulturpool.at/v2/search?${params}`);
const {found, hits, facet_counts} = await response.json();

console.log(`${found} Treffer`);
for (const hit of hits) {
  const doc = hit.document;
  console.log(doc.title, '—', doc.dataProvider);
}

Python

import requests

response = requests.get(
    "https://api.kulturpool.at/v2/search",
    params={
        "q": "Porträt",
        "filter_by": "edmType:=IMAGE && edmRightsReusePolicy:=OPEN",
        "facet_by": "dataProvider,creator",
        "per_page": 24,
    },
)
result = response.json()

print(f"{result['found']} Treffer")
for hit in result["hits"]:
    doc = hit["document"]
    print(doc["title"], "—", doc["dataProvider"])

Antwortformat

Die API gibt die Antwort der Suchmaschine unverändert zurück.

{
  "found": 1529,
  "out_of": 2542449,
  "page": 1,
  "search_time_ms": 12,
  "hits": [
    {
      "document": {
        "uuid": "5a86fa63-198a-4468-b6e5-6f7d71d30c2a",
        "title": "Klimt",
        "dataProvider": "MAK - Museum für angewandte Kunst, Wien",
        "pipelineId": "mak-core",
        "contributor": ["Verlagsanstalt Brüder Rosenbaum <Wien>"],
        "dcType": ["Plakat"],
        "medium": ["Papier", "Flachdruck"],
        "isPartOf": ["Bibliothek und Kunstblättersammlung"],
        "identifier": ["PI 9200", "64920"],
        "coverage": ["1965-1965"],
        "edmType": ["IMAGE"],
        "edmRights": ["http://creativecommons.org/licenses/by-nc-nd/4.0/"],
        "edmRightsName": ["CC BY-NC-ND"],
        "edmRightsReusePolicy": ["RESTRICTED"],
        "dcRights": ["MAK - Museum für angewandte Kunst"],
        "isShownAt": "https://sammlung.mak.at/de/collect/collect_64920",
        "isShownBy": "https://mak-media.azureedge.net/l/81a5fecc078c02f46f694b4b5df43515.jpg",
        "previewImage": "https://media.kulturpool.at/images/mak-media.azureedge.net/1a36d5199acb0f71a1dae08d29cba0b952c1f0f3_small.webp",
        "iiifManifest": "https://media.kulturpool.at/api/iiif/5a86fa63-198a-4468-b6e5-6f7d71d30c2a/prod/manifest.json",
        "hasIiifManifest": true,
        "hasInstitutionalIiifManifest": false,
        "mediaCount": 1,
        "imageCount": 1,
        "mediaTypes": ["image"],
        "imageMegapixel": 0.42,
        "imageAspectRatio": 0.7026,
        "imageOrientation": "portrait",
        "imageColor": "brown",
        "imageColorIsGrayscale": false,
        "imageColorScore": 0.412,
        "docType": "cho",
        "docLanguage": "mul",
        "updatedAt": 1765980973,
        "url": "https://kulturpool.at/objekte/5a86fa63-198a-4468-b6e5-6f7d71d30c2a"
      },
      "highlight": {
        "title": {
          "matched_tokens": ["Klimt"],
          "snippet": "<mark>Klimt</mark>"
        }
      },
      "text_match": 578730123365187700
    }
  ],
  "facet_counts": [
    {
      "field_name": "dataProvider",
      "counts": [
        {"count": 448, "highlighted": "Wien Museum", "value": "Wien Museum"},
        {"count": 226, "highlighted": "Albertina", "value": "Albertina"}
      ]
    }
  ],
  "request_params": {"collection_name": "chos", "q": "Klimt", "per_page": 1}
}

hinweis

title ist ein einzelner Wert

title ist ein String, kein Array — auch in highlight. Trägt ein Datensatz in EDM mehrere Titel, werden die ersten drei zu einem Wert verbunden. Das betrifft rund 2,5 % der Sammlung.

Fehlerbehandlung

Code	Bedeutung
`400`, `404`	Die Suchmaschine hat die Anfrage abgelehnt — die Meldung nennt das Feld
`422`	`q` fehlt, oder `collection` ist unbekannt
`502`	Die Suchmaschine ist nicht erreichbar

Ein Feld, das es nicht gibt, führt zu einem klaren Fehler statt zu stillschweigend ignoriertem Filter — in filter_by mit 400, in facet_by oder query_by mit 404:

{
  "detail": "Could not find a facet field named `issued` in the schema."
}

Tipps

Facetten zur Eingrenzung großer Ergebnismengen nutzen.
edmRightsReusePolicy:=OPEN beantwortet „Was darf ich verwenden?“.
Zeiträume über dateMin/dateMax eingrenzen, nicht über Textfelder.
hasInstitutionalIiifManifest unterscheidet ein von der Institution veröffentlichtes IIIF-Manifest von einem für den Kulturpool erzeugten.

Die Suchmaschine gleicht unscharf ab und liefert auch bei Tippfehlern relevante Treffer.

Große Datenmengen

Für den systematischen Abzug vieler Datensätze ist die Suche nicht der richtige Weg. Nutzen Sie OAI-PMH oder die Datensets zum Herunterladen.

Basis-URL​

Sammlungen​

Parameter​

Pflicht​

Optional​

Weitere Typesense-Parameter​

Felder​

Beschreibung und Anzeige​

Personen und Institutionen​

Klassifikation​

Zeit und Raum​

Rechte​

Medien und IIIF​

Farben​

Sammlungsübergreifende Felder​

Filtern​

Sortieren​

Beispielanfragen​

JavaScript​

Python​

Antwortformat​

Fehlerbehandlung​

Tipps​