lobid-gnd API

Suche: /gnd/search?q=text

Alles
/gnd/search?q=*&format=json
Alle Felder
/gnd/search?q=london&format=json
Feldsuche
/gnd/search?q=preferredName:Twain&format=json
Filter
/gnd/search?q=preferredName:Twain&filter=type:Person&format=json
Paginierung
/gnd/search?q=london&from=50&size=100&format=json
Sortierung
/gnd/search?q=scholl&sort=preferredName.keyword:asc&format=json

Direktzugriff: /gnd/<id>.json

London
/gnd/4074335-4.json
hbz
/gnd/2047974-8.json
Goethe
/gnd/118540238.json

Inhaltstypen

Standardmäßig liefert dieser Dienst strukturierte API-Antworten (als JSON):

curl http://lobid.org/gnd/4074335-4

Er unterstützt Content-Negotiation über den Accept-Header für JSON (application/json), JSON lines (application/x-jsonlines) oder HTML (text/html):

curl --header "Accept: application/json" http://lobid.org/gnd/search?q=london

Der Query-Parameter "format" (Werte: html,json,jsonl) kann verwendet werden, um den Accept-Header aufzuheben, z.B. zur Anzeige von JSON im Browser:

/gnd/4074335-4?format=json

Der Wert des Format-Parameters kann für Einzeltreffer auch in URLs als Dateiendung verwendet werden:

/gnd/4074335-4.json

Einzeltreffer unterstützen zudem verschiedene RDF-Serialisierungen (siehe Abschnitt zu JSON-LD).

Bulk-Downloads

Bulk-Downloads können im Format JSON lines (Accept: application/x-jsonlines oder format=jsonl) bezogen werden:

curl --header "Accept: application/x-jsonlines" "http://lobid.org/gnd/search?q=type:Country" > countries.jsonl

Für größere Anfragen kann die Antwort als gzip komprimiert werden:

curl --header "Accept-Encoding: gzip" "http://lobid.org/gnd/search?q=type:Company&format=jsonl" > companies.gz

Siehe auch diesen Abschnitt zu Bulk-Downloads in unserem Blog.

Autovervollständigung

Die API unterstützt ein spezielles Antwortformat mit Vorschlägen zur Autovervollständigung.

Standardformat für Vorschläge verwenden: "format=json:suggest"
/gnd/search?q=Twain&format=json:suggest
Bestimmtes Feld für Vorschläge verwenden: "format=json:preferredName"
/gnd/search?q=Twain&format=json:preferredName
Vorschläge aus mehreren Feldern zusammenbauen: "format=json:preferredName,professionOrOccupation"
/gnd/search?q=Twain&format=json:preferredName,professionOrOccupation

Damit kann z.B. eine Autovervollständigung umgesetzt werden, bei der zur Suche an Stelle des gewählten Labels die entsprechende ID verwendet werden kann:

Dieses Beispiel ist folgendermaßen mit JavaScript und jQuery UI implementiert:

$('input.search-gnd').autocomplete({
  source : function(request, response) {
    $.ajax({
      //  use full URL in your code, i.e. http://lobid.org/gnd/search
      url : "/gnd/search",
      dataType : "jsonp",
      data : {
        q : request.term,
        format : "json:preferredName,professionOrOccupation"
      },
      success : function(data) {
        response(data);
      }
    });
  },
  select: function(event, ui) {
    $('#id').val('id:"'+ui.item.id+'"');
  }
});

JSON-LD

JSON-API-Anfragen liefern JSON-LD. Um damit zu experimentieren können sie das JSON-LD oder URLs im JSON-LD Playground einfügen.

JSON-LD Context
/gnd/context.jsonld
RDF-Konvertierung
Mit einem JSON-LD-Prozessor können sie API-Antworten in andere RDF-Serialisierungen umwandeln, z.B. in N-Quads mit jsonld-cli:

jsonld format --nquads http://lobid.org/gnd/4074335-4

Einzeltreffer können per Accept Header auch direkt als RDF/XML, Turtle oder N-Triples angefordert werden:

curl --header "Accept: application/rdf+xml" http://lobid.org/gnd/4074335-4

curl --header "Accept: text/turtle" http://lobid.org/gnd/4074335-4

curl --header "Accept: application/n-triples" http://lobid.org/gnd/4074335-4

Dabei werden wie im Abschnitt zu Inhaltstypen beschrieben neben dem Format-Parameter auch URLs mit Formatendungen unterstützt:

/gnd/4074335-4.rdf

/gnd/4074335-4.ttl

/gnd/4074335-4.nt

OpenRefine

Dieser Dienst bietet eine Implementierung der OpenRefine Reconciliation API an:

https://test.lobid.org/gnd/reconcile/ (diese URL in OpenRefine verwenden).

Wir beteiligen uns an der Standardisierung dieser Schnittstellen im Rahmen der W3C Reconciliation Community Group. Die im Rahmen dieser Gruppe entwickelte reconciliation service test bench gibt einen Überblick über die von lobid-gnd unterstützten Reconciliation APIs und bietet die Möglichkeit zur direkten Interaktion mit diesen APIs.

Allgemeine API (spec)

Service
/gnd/reconcile/
JSONP callback
/gnd/reconcile/?callback=jsonp

CORS header

curl --head https://test.lobid.org/gnd/reconcile/ | grep Access-Control-Allow-Origin

View API

Preview entities (spec)
/gnd/118624822.preview
View entities (spec)
/gnd/118624822

Query API (spec)

Query: GET
/gnd/reconcile/?queries={"q1":{"query":"Twain, Mark"}}

Query: POST

curl --data 'queries={"q1":{"query":"Twain, Mark"}}' https://test.lobid.org/gnd/reconcile/

Suggest API (spec)

Suggest entities
/gnd/reconcile/suggest/entity?prefix=hbz
Suggest types
/gnd/reconcile/suggest/type?prefix=werk
Suggest properties
/gnd/reconcile/suggest/property?prefix=beruf
Flyout entities
/gnd/reconcile/flyout/entity?id=2047974-8
Flyout types
/gnd/reconcile/flyout/type?id=Work
Flyout properties
/gnd/reconcile/flyout/property?id=professionOrOccupation

Data extension API

Property proposal (spec)
/gnd/reconcile/properties?type=Work
Extend: GET (spec)
/gnd/reconcile/?extend={"ids":["1081942517","4791358-7"],"properties":[{"id":"preferredName"},{"id":"firstAuthor"}]}

Extend: POST

curl --data 'extend={"ids":["1081942517","4791358-7"],"properties":[{"id":"preferredName"},{"id":"firstAuthor"}]}' https://test.lobid.org/gnd/reconcile/