API-Grundlagen

HTTP GET
/organisations/DE-6
Suche über alle Felder
/organisations/search?q=kunst
Suche mit Paginierung
/organisations/search?q=fundertype.label.de:land&from=2&size=2

Abfragemöglichkeiten

Einfache Feldsuche: "name"
/organisations/search?q=name:stadtbibliothek+berlin
Geschachtelte Feldsuche: "fundertype.label.de"
/organisations/search?q=fundertype.label.de:land

Eine detaillierte Beschreibung der Abfragemöglichkeiten finden Sie in der Dokumentation der Lucene query string syntax.

Bitte beachten Sie insbesondere, dass bei der Suche nach URLs Sonderzeichen wie Doppelpunkte, Schräg- und Bindestriche maskiert werden müssen:

URL-Suche: "classification.id:http\:\/\/purl.org\/lobid\/libtype%23n65"
/organisations/search?q=classification.id:http\:\/\/purl.org\/lobid\/libtype%23n65

Ortsbezogene Suche

Suche in Polygon ("location": Koordinaten der Polygon-Punkte im Format "Breite,Länge")
/organisations/search?q=fundertype.label.de:land&location=52,12+53,12+53,14+52,14
Suche über Distanz zu einem Punkt ("location": Koordinaten eines Punktes und Distanz in km im Format "Breite,Länge,Distanz")
/organisations/search?q=fundertype.label.de:land&location=52.52,13.39,25

Inhaltstypen

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

curl http://lobid.org/organisations/DE-6

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

curl --header "Accept: text/csv" http://lobid.org/organisations/search?q=kunst

curl --header "Accept: application/x-jsonlines" http://lobid.org/organisations/search?q=kunst > kunst.jsonl

Der Query-Parameter "format" kann verwendet werden, um den Accept-Header aufzuheben, z.B. zur Anzeige von JSON im Browser: /organisations/DE-6?format=json

Der Wert des Format-Parameters kann für Einzeltreffer auch in URLs als Dateiendung verwendet werden: /organisations/DE-6.json

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

curl --header "Accept-Encoding: gzip" "http://lobid.org/organisations/search?q=museum&format=bulk" > museum.gz

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

CSV-Export

Standardfelder ("format=csv")
/organisations/search?q=kunst&size=300&format=csv
Benutzerdefinierte Felder ("format": zu verwendende Felder, mit Punkten für geschachtelte Felder im Format "csv:feld1,feld2.unterfeld")
/organisations/search?q=kunst&size=300&format=csv:name,isil,url,classification.label.de

Autovervollständigung

Die API unterstützt ein spezielles Antwortformat mit Vorschlägen zur Vervollständigung aus einem angegebenen Feld:

Name vorschlagen: "format=json:name"
/organisations/search?q=name:dnb+OR+alternateName:dnb&format=json:name
Klassifikation vorschlagen: "format=json:classification"
/organisations/search?q=classification.label.de:Universit%C3%A4t&format=json:classification

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-organisations').autocomplete({
    source : function(request, response) {
        $.ajax({
            url : "http://lobid.org/organisations/search",
            dataType : "jsonp",
            data : {
                q : request.term,
                format : "json:name"
            },
            success : function(data) {
                response(data);
            }
        });
    },
    select: function(event, ui) {
        $('#id').val('id:"'+ui.item.id+'"');
    }
});

JSON-LD

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

JSON-LD Context
/organisations/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/organisations/DE-6

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/organisations/DE-6

curl --header "Accept: text/turtle" http://lobid.org/organisations/DE-6

curl --header "Accept: application/n-triples" http://lobid.org/organisations/DE-6

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

/organisations/DE-6.rdf

/organisations/DE-6.ttl

/organisations/DE-6.nt

Beispieldokument
Dieses Beispieldokument wurde mit hypothes.is annotiert, um den Einstieg in die Datenlage zu erleichtern. Bei Klick auf einen gelbmarkierten JSON-Key geht ein Popup-Fenster auf mit Informationen zu Name, Beschreibung, Abdeckung sowie Anwendungsbeispielen des Feldes.
{
  "linkedTo" : {
    "id" : "http://lobid.org/organisations/DE-605#!",
    "label" : "Hochschulbibliothekszentrum des Landes Nordrhein-Westfalen (hbz)"
  },
  "rs" : "053150000000",
  "telephone" : "0049 221 4 78-7070",
  "alternateName" : [ "ZB MED - Informationszentrum Lebenswissenschaften, Köln", "Köln ZB MED" ],
  "type" : "Library",
  "classification" : {
    "id" : "http://purl.org/lobid/libtype#n15",
    "type" : "Concept",
    "label" : {
      "de" : "Zentrale Fachbibliothek",
      "en" : "Central Subject Library"
    }
  },
  "@context" : "http://lobid.org/organisations/context.jsonld",
  "url" : "http://www.zbmed.de",
  "provides" : "http://www.livivo.de/?idb=ZBMED",
  "name" : "Deutsche Zentralbibliothek für Medizin - Informationszentrum Lebenswissenschaften, Köln",
  "containedIn" : "http://sws.geonames.org/6553049/",
  "location" : [ {
    "type" : "Place",
    "address" : {
      "postalCode" : "50931",
      "streetAddress" : "Gleueler Str. 60",
      "addressLocality" : "Köln",
      "addressCountry" : "DE",
      "type" : "PostalAddress"
    },
    "openingHoursSpecification" : {
      "type" : "OpeningHoursSpecification",
      "comment" : "Ausleihe/Allg. Information: Mo-Fr 9.00-21.00, Sa 9.00-12.00; Fachauskunft: Mo-Fr 9.00-16.00; weitere Schließtage s.Homepage",
      "description" : "Mo-Fr 9.00-21.00, Sa 9.00-17.00, So und Feiertags 12.00-17.00 (Lesesaal)"
    },
    "geo" : {
      "lat" : "50.92466",
      "lon" : "6.91666"
    }
  } ],
  "id" : "http://lobid.org/organisations/DE-38M#!",
  "isil" : "DE-38M",
  "fundertype" : {
    "id" : "http://purl.org/lobid/fundertype#n06",
    "type" : "Concept",
    "label" : {
      "de" : "Sonstige öffentliche Trägerschaft",
      "en" : "Other Public Sector Funder"
    }
  },
  "collects" : {
    "type" : "Collection",
    "extent" : {
      "id" : "http://purl.org/lobid/stocksize#n09",
      "type" : "Concept",
      "label" : {
        "de" : "300.001 - 1.000.000",
        "en" : "300,001 - 1,000,000"
      }
    },
    "subject" : [ "Medizin" ]
  },
  "email" : "mailto:info@zbmed.de",
  "dbsID" : "BJ038",
  "name_en" : "German National Library of Medicine - Information Centre for Life Sciences, Cologne",
  "sameAs" : [ "http://www.wikidata.org/entity/Q1204536", "http://ld.zdb-services.de/resource/organisations/DE-38M" ]
}

OpenRefine

Dieser Dienst bietet eine Implementierung der OpenRefine Reconciliation API an. Folgen Sie diesen Schritte um sie zu verwenden.

Metadaten-Anfrage ("callback": optionaler JSONP-Callback, in den die Antwort verpackt wird)
/organisations/reconcile?callback=jsonp
Reconciliation-Anfrage (erwartet Formulardaten per HTTP POST, verwenden Sie diese URL in OpenRefine)
/organisations/reconcile