Institutionen API

Überblick

Die Institutionen API liefert Informationen über teilnehmende Museen, Bibliotheken, Archive und andere Kultureinrichtungen des Kulturpools. Jede Institution wird durch eine eindeutige String-ID identifiziert und enthält mehrsprachige Übersetzungen, Standortdaten und verknüpfte Medien.

Basis-URL

https://api.kulturpool.at/institutions

Endpunkte

Alle Institutionen abrufen

GET /institutions

Ruft alle registrierten Institutionen mit ihren Metadaten, Standortinformationen und mehrsprachigen Beschreibungen ab.

Vollständige Liste, keine Paginierung

Der Endpunkt liefert alle veröffentlichten Institutionen in einer einzigen Antwort — derzeit rund 170 Einträge (etwa 0,5 MB). Es gibt keine Paginierungsparameter, und die Antwort wird serverseitig drei Stunden lang gecacht.

Sortiert wird nach id. Die Sortierung folgt der Kollation der Datenbank, die Bindestriche ignoriert — museumsmanagement-… steht daher vor museum-st-…. Verlassen Sie sich nicht auf eine bytegenaue Sortierreihenfolge.

Beispiel

curl -X GET "https://api.kulturpool.at/institutions"

Antwort

{
  "data": [
    {
      "id": "naturhistorisches-museum-wien",
      "legal_name": "Naturhistorisches Museum Wien",
      "location": {
        "type": "MultiPoint",
        "coordinates": [[16.35976, 48.20527]]
      },
      "parent_institution": null,
      "cultural_sector": 3,
      "cultural_subsector": 18,
      "date_created": "2024-01-15T10:00:00.000Z",
      "date_updated": "2025-03-20T14:30:00.000Z",
      "favicon": {
        "id": "12345678-1234-5678-9abc-123456789abc"
      },
      "hero_image": {
        "id": "87654321-8765-4321-9def-987654321fed",
        "title": "Naturhistorisches Museum Wien",
        "author": "Max Mustermann",
        "license": "CC BY-SA",
        "license_url": "https://creativecommons.org/licenses/by-sa/4.0/deed.de"
      },
      "logo": {
        "id": "11111111-2222-3333-4444-555555555555"
      },
      "translations": [
        {
          "id": 1,
          "place": "Wien",
          "title": "Naturhistorisches Museum Wien",
          "languages_code": "de",
          "web_links": [
            {"display_name": "website", "url": "https://www.nhm.at"},
            {"display_name": "web_collection", "url": "https://divina.nhm.at/search"}
          ],
          "slugs": [{"slug": "nhmw"}],
          "summary": "Das Naturhistorische Museum Wien ist eines der bedeutendsten naturwissenschaftlichen Museen der Welt.",
          "content": "<p>Das NHM Wien beherbergt rund 30 Millionen Sammlungsobjekte.</p>"
        },
        {
          "id": 2,
          "place": "Vienna",
          "title": "Natural History Museum Vienna",
          "languages_code": "en",
          "web_links": [
            {"display_name": "website", "url": "https://www.nhm.at/en"}
          ],
          "slugs": [{"slug": "nhmw"}],
          "summary": "The Natural History Museum Vienna is one of the most important natural science museums in the world.",
          "content": "<p>The NHM Vienna houses around 30 million collection objects.</p>"
        }
      ],
      "provider_names": [
        {"name": "Naturhistorisches Museum Wien", "canonical": true}
      ],
      "child_institutions": []
    }
  ]
}

Einzelne Institution abrufen

GET /institutions/{institution_id}

Ruft detaillierte Informationen zu einer spezifischen Kulturinstitution ab.

Parameter

Parameter	Typ	Beschreibung
`institution_id`	string	Die eindeutige String-ID der Institution (Pfad-Parameter)

String-IDs statt Zahlen

Institutionen werden über sprechende String-IDs adressiert (z.B. albertina, naturhistorisches-museum-wien) — nicht über numerische IDs.

Beispiel

curl -X GET "https://api.kulturpool.at/institutions/naturhistorisches-museum-wien"

Antwort

{
  "data": {
    "id": "naturhistorisches-museum-wien",
    "legal_name": "Naturhistorisches Museum Wien",
    "location": {
      "type": "MultiPoint",
      "coordinates": [[16.35976, 48.20527]]
    },
    "translations": [
      {
        "id": 1,
        "place": "Wien",
        "title": "Naturhistorisches Museum Wien",
        "languages_code": "de",
        "web_links": [
          {"display_name": "website", "url": "https://www.nhm.at"}
        ],
        "slugs": [{"slug": "nhmw"}],
        "summary": "Das Naturhistorische Museum Wien ist eines der bedeutendsten naturwissenschaftlichen Museen der Welt.",
        "content": "<p>Das NHM Wien beherbergt rund 30 Millionen Sammlungsobjekte.</p>"
      }
    ]
  }
}

Datenstruktur

Institution

Feld	Typ	Beschreibung
`id`	string	Eindeutige String-ID der Institution (z.B. `"albertina"`, `"naturhistorisches-museum-wien"`)
`legal_name`	string \| null	Offizieller juristischer Name
`location`	Location \| null	GeoJSON-Standort
`parent_institution`	string \| null	ID der übergeordneten Institution
`cultural_sector`	integer \| null	Kultureller Sektor (für Europeana-Weiterleitung)
`cultural_subsector`	integer \| null	Kultureller Untersektor
`date_created`	string \| null	Erstellungsdatum (ISO 8601)
`date_updated`	string \| null	Letztes Änderungsdatum (ISO 8601)
`favicon`	File \| null	Favicon-Datei (Asset-ID)
`hero_image`	HeroImage \| null	Hintergrundbild mit Metadaten
`logo`	File \| null	Logo-Datei (Asset-ID)
`translations`	Translation[]	Mehrsprachige Übersetzungen
`provider_names`	ProviderName[] \| null	Alternative Anzeigenamen der Institution
`child_institutions`	string[] \| null	IDs von untergeordneten Institutionen

Translation

Feld	Typ	Beschreibung
`id`	integer	Übersetzungs-ID
`place`	string \| null	Standort/Ort
`title`	string \| null	Anzeigename der Institution
`languages_code`	string	Sprachcode (ISO 639-1, z.B. `"de"`, `"en"`)
`web_links`	WebLink[] \| null	Web-Links (Website, Sammlung etc.)
`slugs`	Slug[] \| null	URL-Slugs
`summary`	string \| null	Kurzbeschreibung
`content`	string \| null	Ausführliche Beschreibung (HTML)
`items`	any[] \| null	Verknüpfte Content-Blöcke

WebLink

Feld	Typ	Beschreibung
`display_name`	string	Bezeichnung (z.B. `"website"`, `"web_collection"`)
`url`	string	URL

Slug

Feld	Typ	Beschreibung
`slug`	string	URL-Slug

HeroImage

Feld	Typ	Beschreibung
`id`	string	Asset-UUID
`title`	string	Bildtitel
`author`	string \| null	Fotograf/Urheber
`license`	string \| null	Lizenzbezeichnung
`license_url`	string \| null	URL zur Lizenz

Location (GeoJSON)

Feld	Typ	Beschreibung
`type`	string	GeoJSON-Typ (z.B. `"MultiPoint"`)
`coordinates`	number[][]	Koordinaten [Längengrad, Breitengrad]

ProviderName

Feld	Typ	Beschreibung
`name`	string	Name des Providers
`canonical`	boolean	Ob dies der kanonische Name ist

File

Feld	Typ	Beschreibung
`id`	string	UUID des Assets im CMS — auflösbar über die Assets API

Beispiel-Code

JavaScript/Fetch

// Alle Institutionen abrufen
const response = await fetch('https://api.kulturpool.at/institutions');
const {data: institutions} = await response.json();

// Einzelne Institution abrufen
const institutionResponse = await fetch('https://api.kulturpool.at/institutions/naturhistorisches-museum-wien');
const {data: institution} = await institutionResponse.json();

const de = institution.translations.find((t) => t.languages_code === 'de');
console.log(`Institution: ${de?.title ?? institution.legal_name}`);
console.log(`Ort: ${de?.place}`);

Python/requests

import requests

# Alle Institutionen abrufen
response = requests.get("https://api.kulturpool.at/institutions")
institutions = response.json()["data"]

# Einzelne Institution abrufen
institution = requests.get(
    "https://api.kulturpool.at/institutions/naturhistorisches-museum-wien"
).json()["data"]

de = next(
    (t for t in institution["translations"] if t["languages_code"] == "de"),
    None,
)

print(f"Institution: {de['title'] if de else institution['legal_name']}")
print(f"Ort: {de['place'] if de else 'N/A'}")

cURL

# Alle Institutionen abrufen
curl -X GET "https://api.kulturpool.at/institutions" \
  -H "Accept: application/json"

# Einzelne Institution abrufen
curl -X GET "https://api.kulturpool.at/institutions/naturhistorisches-museum-wien" \
  -H "Accept: application/json"

Anwendungsfälle

Institutionen-Verzeichnis erstellen

async function createInstitutionDirectory(language = 'de') {
  const response = await fetch('https://api.kulturpool.at/institutions');
  const {data: institutions} = await response.json();

  return institutions.map((institution) => {
    const t = institution.translations.find(
      (t) => t.languages_code === language,
    );

    return {
      id: institution.id,
      name: t?.title ?? institution.legal_name,
      place: t?.place,
      slug: t?.slugs?.[0]?.slug,
      website: t?.web_links?.find((l) => l.display_name === 'website')?.url,
      collection: t?.web_links?.find((l) => l.display_name === 'web_collection')
        ?.url,
    };
  });
}

Karte mit Institutionen

async function getInstitutionLocations(language = 'de') {
  const response = await fetch('https://api.kulturpool.at/institutions');
  const {data: institutions} = await response.json();

  return institutions
    .filter((institution) => institution.location)
    .map((institution) => ({
      id: institution.id,
      coordinates: institution.location.coordinates[0], // [lng, lat]
      title:
        institution.translations.find((t) => t.languages_code === language)
          ?.title ?? institution.legal_name,
    }));
}

Institution mit Assets

async function getInstitutionWithImages(institutionId) {
  const response = await fetch(
    `https://api.kulturpool.at/institutions/${institutionId}`,
  );
  const {data: institution} = await response.json();

  return {
    ...institution,
    faviconUrl: institution.favicon
      ? `https://api.kulturpool.at/assets/${institution.favicon.id}?format=png&width=32&height=32`
      : null,
    logoUrl: institution.logo
      ? `https://api.kulturpool.at/assets/${institution.logo.id}?format=png&width=200&height=100&fit=contain`
      : null,
    heroImageUrl: institution.hero_image
      ? `https://api.kulturpool.at/assets/${institution.hero_image.id}?format=webp&width=1200&height=400&fit=cover`
      : null,
  };
}

Institutionen mit Suchergebnissen verknüpfen

Das Feld dataProvider in den Suchergebnissen enthält den Anzeigenamen der liefernden Institution. Über provider_names lässt sich die passende Institution auflösen:

async function buildProviderIndex() {
  const {data: institutions} = await fetch(
    'https://api.kulturpool.at/institutions',
  ).then((r) => r.json());

  const index = new Map();

  for (const institution of institutions) {
    for (const provider of institution.provider_names ?? []) {
      index.set(provider.name, institution);
    }
  }

  return index;
}

Fehlerbehandlung

404 — Institution nicht gefunden

{
  "detail": "Error fetching data from upstream API"
}

500 — Server-Fehler

{
  "detail": "Error fetching data from upstream API"
}

Basis-URL​

Endpunkte​

Alle Institutionen abrufen​

Beispiel​

Antwort​

Einzelne Institution abrufen​

Parameter​

Beispiel​

Antwort​

Datenstruktur​

Institution​

Translation​

WebLink​

Slug​

HeroImage​

Location (GeoJSON)​

ProviderName​

File​

Beispiel-Code​

JavaScript/Fetch​

Python/requests​

cURL​

Anwendungsfälle​

Institutionen-Verzeichnis erstellen​

Karte mit Institutionen​

Institution mit Assets​

Institutionen mit Suchergebnissen verknüpfen​

Fehlerbehandlung​

404 — Institution nicht gefunden​

500 — Server-Fehler​

Basis-URL

Endpunkte

Alle Institutionen abrufen

Beispiel

Antwort

Einzelne Institution abrufen

Parameter

Beispiel

Antwort

Datenstruktur

Institution

Translation

WebLink

Slug

HeroImage

Location (GeoJSON)

ProviderName

File

Beispiel-Code

JavaScript/Fetch

Python/requests

cURL

Anwendungsfälle

Institutionen-Verzeichnis erstellen

Karte mit Institutionen

Institution mit Assets

Institutionen mit Suchergebnissen verknüpfen

Fehlerbehandlung

404 — Institution nicht gefunden

500 — Server-Fehler