Home Original page

api/doc/widgetapi-userguide/widgetapi-userguide.md at master · northdata/api

image alt text

North Data Widget API

Zur Einbindung der Visualisierungen (interaktiven Grafiken) von North Data.

Inhaltsverzeichnis

Übersicht

Folgende Widgets sind aktuell verfübar:

type Beschreibung Bild Beispiel-Seite
history Firmenhistorie (Timeline) https://www.northdata.de/widgetTestHistory.html
vita Personenhistorie https://www.northdata.de/widgetTestVita.html
graph Netzwerk einer Firma oder Person https://www.northdata.de/widgetTestGraph.html
pubTable Publikationen einer Firma oder Person https://www.northdata.de/widgetTestPubTable.html
barChart Balkendiagramm für finanzielle Kennzahlen https://www.northdata.de/widgetTestBarChart.html
sheet Tabellarische Darstellung der Bilanz oder GuV https://www.northdata.de/widgetTestSheet.html
financials Tabelle mit finanziellen Kennzahlen https://www.northdata.de/widgetTestFinancials.html
drillDown Darstellung der Größe der wichtigsten Jahresabschlussposten als unterteiltes Rechteck https://www.northdata.de/widgetTestDrillDown.html

Künftige Widgets

Folgende Widgets werden in Kürze verfügbar sein:

Beschreibung Status
Firmen-Stammdaten Abgeschlossen, Dokumentation fehlt
Personen-Stammdaten Abgeschlossen, Dokumentation fehlt
Firmensuche Abgeschlossen, Dokumentation fehlt
Powersuche In Entwicklung
Interaktive Karte In Entwicklung

Einbindung von Widgets

Zur Einbindung werden benötigt:

  1. North Data Widget Bibliothek northdata-viz
  2. Externes Stylesheet
  3. Initialisierungscode und Konfigurationscode pro Widget

1. North Data Widget Bibliothek:

Über externes Script

Die Widget Bibliothek kann über das Script eingebunden werden:

<script src="https://www.northdata.de/js/viz.min.js"></script>

Alternativ stehen verschiedene CDN-Dienste zur Verfügung, die das Einbinden des Scripts erleichtern wie zum Beispiel:

Über npm

Das Script kann ebenso mithilfe von npm bezogen werden:

npm install northdata-viz

Danach kann die Bibliothek wie folgt importiert werden:

import * as NorthData from "northdata-viz";

2. Externes Stylesheet:

Das externe Stylesheet wird über den folgenden Tag im <head> des HTML-Dokuments eingebunden.

<link
  href="https://www.northdata.de/viz.css?color1=%23ff0000&color2=%2300ff00&color3=%230000ff"
  rel="stylesheet"
/>

Über die drei Parameter kann die Farbgebung in der Netzwerkdarstellung angepasst werden:

  • color1 - Farbe des primären Knoten (Farbwert im Beispiel #ff0000)
  • color2 - Farbe der anderen Knoten (Farbwert im Beispiel #00ff00)
  • color3 - Farbe der anderen Knoten bei Mouse-Hover (Farbwert im Beispiel #0000ff)

3. Initialisierung und Konfiguration der Widgets per Javascript:

Die Bibliothek muss vor der Erstellung von Visualisierungen einmalig initialisiert werden:

Für jede Visualisierung muss ein HTML-Element angelegt werden. Dieses HTML-Element dient als "Root-Element" für das Widget-Objekt und wird anschließend per Javascript konfiguriert.

Beispiel Initialisierung eines Graph-Widgets:

<figure
  id="myFigure"
  data-type="graph"
  data-name="Weiler Werkzeugmaschinen GmbH"
  data-address="Emskirchen"
  data-min-height="300"
></figure>
new NorthData.Widget(document.getElementById("myFigure"), {
  /* Konfiguration */
});

Konfiguration

Die Optionen können entweder als zweiter Parameter in Javascript übergeben werden, oder als Data-Attribute am HTML-Element gesetzt werden.

Beispiel Javascript:

new NorthData.Widget(document.getElementById("myFigure"), {
  type: "history",
  apiKey: "abcd-wxyz",
  name: "Weiler Werkzeugmaschinen GmbH",
  address: "Emskirchen",
  minHeight: 300,
  success: function () {
    console.info("ok");
  },
  error: function (error) {
    console.error(error);
  },
});

Beispiel HTML-Element:

<figure
  id="myFigure"
  data-type="graph"
  data-name="Weiler Werkzeugmaschinen GmbH"
  data-address="Emskirchen"
  data-min-height="300"
  data-api-key="abcd-wxyz"
></figure>

Wichtig: HTML-Data-Attributes werden mit Bindestrichen formatiert, nicht als Camel-Case. Also minHeight in Javascript entspricht data-min-height in HTML.

Javascript-Optionen und HTML-Data-Attribute können auch frei kombiniert werden. Die Javascript-Optionen überschreiben dabei die Data-Attribute.

Bei Javascript-Optionen vom Typ Zahl oder String können auch Funktionen verwendet werden, die passende Werte zurückliefern.

Liste Widget-übergreifender Optionen

Name Typ Erklärung
apiKey String API Key (siehe Autorisierung)
type String Auswahl der grafischen Darstellung:
  • graph: Netzwerk der Person bzw. der Firma
  • history: Historie (Timeline)
  • barChart: Balkendiagramm
  • sheet: tabellarische Darstellung der Bilanz/GuV
  • drillDown: Darstellung der Größe der wichtigsten Jahresabschlussposten als unterteiltes Rechteck
  • pubTable: Tabelle der neuesten Publikationen
  • dendrogram: Horizontale Baumdarstellung (auf northdata.de verwendet zur Darstellung der Publikationsgliederung)
language String Sprache
  • de: Deutsch (default)
  • en: Englisch (experimentell, wird ggf. noch nicht von allen Widgets unterstützt)
domain String Typ des dargestellten Objekts (optional)
  • company: Firma (default)
  • person: Person (in diesem Fall ist zudem die Option birthday notwendig)
  • hrb: Handelsregisterbekanntmachung
name String Name des Objekts, z.B. Firmenname, bei Personen im Format "Nachname, Vorname"
address String optional, aber verbessert die Wahrscheinlichkeit eines eindeutigen Suchergebnis Bsp: Strasse Nr. 123, 12345 Stadt oder auch nur Hamburg
registerCity String Sitz des Amtsgericht, optional, aber verbessert die Wahrscheinlichkeit eines eindeutigen Suchergebnis
registerId String Handelsregister in der Form HRA 12345
birthDay String Geburtstag im Format "YYYY-MM-TT" z.B. 1970-12-26
minHeight Zahl minimale Höhe der Darstellung in Pixel
maxHeight Zahl maximale Höhe in Pixel
ratio Zahl fixes Verhältnis von Höhe zu Breite
success Funktion wird aufgerufen, wenn das Widget erfolgreich erstellt wurde
error Funktion wird im Fehler-Fall aufgerufen. Erhält als Argument eine Fehlermeldung oder ein Error-Objekt
censor Boolean sollte auf true gesetzt werden, falls die Darstellung öffentlich erfolgt.

Firmen-Identifikation

Die Firma wird über die Konfigurationsoptionen name, address, registerCity und registerName identifiziert.

  1. Es muss mindestens die Kombination Name/Ort oder Amtsgericht/HR angegeben werden – idealerweise beide.

  2. Verwenden Sie als Adresse einfach nur den Ort. Dies ist absolut ausreichend zur Identifikation: kleine Fehler der Adresse (Hausnummern!) können dazu führen, dass eine Firma nicht identifiziert wird.

  3. Die Identifikation der Firma ist ansonsten weitgehend tolerant gegenüber verschiedenen Schreibweisen der Firma, früheren Namen/Orten, unterschiedlichen Schreibweisen des Orts, alten Formen des HR-Zeichen, etc.

Personen-Identifikation

Eine Person wird über die Konfigurationsoptionen name, address und birthDay identifiziert.

Autorisierung

Die Autorisierung erfolgt per API-Key (wie beim Daten-API), oder über die Freischaltung der Domain, wo die Widgets eingebunden werden. Um einen API-Key zu erhalten bzw. eine Domain freischalten zu lassen, wenden Sie sich bitte an North Data.

Der API-Key sollte nur beim Testen verwendet werden. Beim Testen ist der API Key meistens erforderlich, da die beim Testen verwendete Domain nicht freigeschaltet ist.

Im Produktionsbetrieb sollte der API-Key nicht verwendet werden, da er im HTML-Source-Code sichtbar ist.

Abmessungen

Widgets nutzen immer die vorgegebene Breite des HTML-Elements. Die Höhe passen sie aber zur optimalen Darstellung dynamisch an.

Navigation / Click Handler

Interaktivität und User Engagement der Netzwerk- und Historiendarstellung werden maßgeblich verbessert, wenn die Knoten anklickbar sind und weitere Seiten verlinken. Dazu können Click Event Handler über die Optionen companyClick, personClick und publicationClick definiert werden:

function handleCompanyClick(node) {
  var hr = node.registerCity + " " + node.registerId  
  var url = "/companies.html?hr=" + encodeURIComponent(hr)
  window.location.assign(url)
}

new NorthData.Widget( myFigure, { 
  companyClick: handleCompanyClick,
  // personClick: …,
  // publicationClick: ...
})

Die Optionen companyClick, personClick und publicationClick sollten nur gesetzt werden, wenn der Click tatsächlich behandlelt wird! (Grund: korrekte Darstellung des Mauszeigers.)

Die Attribute des der Funktion übergebenen Knoten (im Beispiel: node) sind in der folgenden Tabelle zusammengestellt.

Attribut Erläuterung
name Name (z.B. Name der Firma oder der Person)
text Beschriftung des Knotens (ggf. gekürzter Name)
address Adresse (Firmen, Personen - falls bekannt)
registerName Sitz des Amtsgericht (nur Firmen)
registerId Handelsregister in der Form HRA 12345 (nur Firmen)
firstName bei Personen
lastName bei Personen
birthDate bei Personen (falls bekannt)
id interne North Data ID
url bei Publikationen (in der Regel keine öffentliche URL, da die Publikationen nicht öffentlich sind. Kann aber als eindeutiger Schlüssel für eine Publikationen verwendet werden)
hash bei Publikationen (Hashwert über den Publikationstext. Kann als Schlüssel verwendet werden)

Layout von Mehrfach-Grafiken / Item Handler

Verschiedene Widgets können mehrere Grafiken zu einer Firma erzeugen: Balkendiagramme (Widget-Type barChart) für Umsatz, Gewinn, usw., die tabellarische Darstellung der Bilanz neben der Bilanz auch eine Gewinn- und Verlustrechnung.

image alt text

Es gibt in diesem Fall viele Möglichkeiten der Darstellung: nebeneinander, untereinander, oder - häufig die eleganteste Lösung - in Tabs. Die Darstellung kann angepasst werden über einen Item-Handler:

function wrapChart(title, element) {
  // wrap title and element in figure and legend tags
  var figure = document.createElement("figure")
  var legend = document.createElement("legend")
  legend.textContent = title
  figure.appendChild(legend)
  figure.appendChild(element)
  var chart = document.createElement("div")
  chart.className = "chart"
  chart.appendChild(legend)
  chart.appendChild(figure)
  return chart
}

new NorthData.Widget( myFigure, { 
  type: "barChart",
  handleItem: wrapChart
})

Dem Item-Handler werden die Überschrift der Grafik (z.B. "Gewinn") und das jeweilige Grafikelement übergeben. Der Rückgabewert ist das "neue Element", was dann in das Dokument eingefügt wird, oder null, falls nichts eingefügt wird (d.h., das komplette DOM-Handling von der Funktion übernommen wird). Beispiel siehe hier: https://www.northdata.de/widgetTestBarChart.html

Ist kein Item-Handler definiert, wird nur die Überschrift in einen <h2>-Tag gesetzt.

Widget-Referenz

Im folgenden werden die verschiedenen Widgets im Detail vorgestellt, und die nur für sie jeweils verfügbaren Konfigurations-Optionen aufgelistet.

Widget-Typ "history"

Stellt die wichtigsten Ereignisse zu einer Firma als Timeline dar. Beispielseite: https://www.northdata.de/widgetTestHistory.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: history
rootColor Farbe Farbe, auf deren Basis eine passende Farbpalette für die Färbung der Ereignisse erstellt wird.
maxEvents Zahl Maximale Anzahl der angezeigten Ereignisse. Default: 25
companyClick Funktion siehe Abschnitt Navigation / Click Handler
personClick Funktion siehe Abschnitt Navigation / Click Handler
publicationClick Funktion siehe Abschnitt Navigation / Click Handler

Widget-Typ "vita"

Stellt die wichtigsten Stationen einer Person in einer Timeline dar. Beispielseite: https://www.northdata.de/widgetTestVita.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: vita
maxLines Zahl Maximale Anzahl der angezeigten Zeilen. Default: 15
companyClick Funktion siehe Abschnitt Navigation / Click Handler

Widget-Typ "graph"

Stellt das Netzwerk einer Firma oder Person, d.h. die Verflechtungen mit Firmen (Beherrschungen, Komplementäre, etc.) und Personen (Geschäftsführer, Vorstände, etc.) als Graph dar.

Beispielseite: https://www.northdata.de/widgetTestGraph.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: graph
maxNodes Zahl bei Layouts "graph", "dendrogram": Maximale Anzahl der angezeigten Knoten. Default: 12
companyClick Funktion siehe Abschnitt Navigation / Click Handler
personClick Funktion siehe Abschnitt Navigation / Click Handler

Widget-Typ "pubTable"

Interaktive Liste von Publikationen (Handelsregister, Insolvenzregister) zur jeweiligen Firma.

Beispielseite: https://www.northdata.de/widgetTestPubTable.html

Die einzelnen Publikationen können durch Klick auf der Überschrift ein- und ausgeklappt werden. Semantische Konzepte wie Firmen oder Personen sind im HTML-Text markiert, und können per CSS in der Darstellung verändert werden.

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: pubTable
maxRows Zahl Maximale Anzahl der angezeigten Elemente. Default: 25

Widget-Typ "barChart"

Stellt finanzielle Kennzahlen als Balkendiagramm dar.

Beispielseite: https://www.northdata.de/widgetTestBarChart.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: barChart
items Array of String Gewünschte Kennzahlen: Liste der IDs. Default: ["earnings", "revenue", "tax", "employees"]. zu den möglichen IDs siehe Finanzielle Kennzahlen
handleItem Funktion siehe Abschnitt Layout von Mehrfach-Grafiken / Item Handler
colors Array von Farben 3 Farbangaben, Nr. 1 für absolute Werte (z.B. Umsatz), Nr. 2 für positive (z.B. Gewinn), Nr. 3 für negative (z.B. Verlust)
maxYears Zahl Maximale Anzahl der angezeigten Jahre. Default: 8
chronology String Zeitliche Reihenfolge: Wert "normal" für aufsteigend, Wert "reverse" für absteigend. Default: "normal"

Widget-Typ "financials"

Stellt finanzielle Kennzahlen (soweit verfügbar) als Tabelle dar.

Beispiel: https://www.northdata.de/widgetTestFinancials.html

Das Tabellen-"Basis-Styling" ist nur rudimentär, so dass Sie es problemlos nach Ihren Bedürfnissen anpassen können. Möchten Sie das nicht tun, kann ein erweitertes Styling über folgende CSS-Datei eingebunden werden:

https://www.northdata.de/css/styling.css

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: financials
maxYears Zahl Maximale Anzahl der angezeigten Jahre. Default: 2
chronology String Zeitliche Reihenfolge: Wert "normal" für aufsteigend, Wert "reverse" für absteigend. Default: "normal"
sourceClick Funktion Durch Angabe einer Funktion function(source) kann das Standardverhalten beim Klick auf die Quellenangabe überschrieben werden.

Widget-Typ "sheets"

Stellt Bilanz und Gewinn-/Verlustrechnung (soweit verfügbar) als interaktive Tabelle dar. Summen-Zeilen können per Klick ein- und aufgeklappt werden.

Beispielseite: https://www.northdata.de/widgetTestSheet.html

Das Tabellen-"Styling" ist nur rudimentär, so dass sie es problemlos nach Ihren Bedürfnissen anpassen können. Möchten Sie das nicht tun, kann ein erweitertes Styling kann über folgende CSS-Datei eingebunden werden:

https://www.northdata.de/css/styling.css

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: financials
maxYears Zahl Maximale Anzahl der angezeigten Jahre. Default: 2
chronology String Zeitliche Reihenfolge: Wert "normal" für aufsteigend, Wert "reverse" für absteigend. Default: "normal"
items Array of String Gewünschte Tabellen als Liste von Strings. Default: ["balance", "income"]. Mögliche Angaben: balance - Bilanz income - Gewinn- und Verlustrechnung
handleItem Funktion siehe Abschnitt Layout von Mehrfach-Grafiken / Item Handler
sourceClick Funktion Durch Angabe einer Funktion function({ publication }) kann das Standardverhalten beim Klick auf die Quellenangabe überschrieben werden.

Widget-Typ "drillDown"

Stellt die größten Positionen in den Ausgaben, Aktiva und Passiva des neuesten verfügbaren Jahresabschluss als untergliedertes Rechteck dar. Die Fläche der jeweiligen Boxen entspricht der Größe der Position, so dass die Größenverhältnisse auf den ersten Blick ersichtlich sind. In der Bilanz zusammengehörige Position erhalten "ähnliche" Farben.

Beispielseite: https://www.northdata.de/widgetTestDrillDown.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: drillDown
rootColor Farbe Farbe, auf deren Basis eine passende Farbpalette erstellt wird.
items Array of String Gewünschte Grafiken als Liste von Strings. Default: ["cost", "assets", "liabilities"]. Mögliche Angaben: cost - Ausgaben assets - Aktiva liabilities - Passiva
handleItem Funktion siehe Abschnitt Layout von Mehrfach-Grafiken / Item Handler