lobid-organisations

Technical and other guidance on the usage of lobid can be found in the API Usage Guidelines.

API basics

HTTP GET

/organisations/DE-6

Query all fields

/organisations/search?q=kunst

Query with pagination

/organisations/search?q=fundertype.label.de:land&from=2&size=2

Queries

Query "name" field

/organisations/search?q=name:stadtbibliothek+berlin

Query nested "fundertype.label.de" field

/organisations/search?q=fundertype.label.de:land

You can find a detailed description of the supported queries in the Lucene query string syntax documentation.

In particular note that when querying for URLs, special characters like colons, dashes, and slashes have to be escaped:

URL query: "classification.id:http\:\/\/purl.org\/lobid\/libtype%23n65"

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

Location based queries

Query with polygon ("location": coordinates of polygon points "lat,lon")

/organisations/search?q=fundertype.label.de:land&location=52,12+53,12+53,14+52,14

Query with distance ("location": coordinate of a point and a distance in km "lat,lon,distance")

/organisations/search?q=fundertype.label.de:land&location=52.52,13.39,25

Content types

By default, this service returns structured API responses (as JSON):

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

It supports content negotiation based on the "Accept" header to serve JSON (application/json), CSV (text/csv), TSV (text/tab-separated-values), JSON lines (application/x-jsonlines), or HTML (text/html):

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

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

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

An optional "format" query parameter can be used to override the "Accept" header, e.g. to display JSON in a browser: /organisations/DE-6?format=json

For individual organisations, the format parameter values can be used as file extensions in URLs: /organisations/DE-6.json

For larger requests, the response can be compressed as gzip:

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

Individual organisations additionally support different RDF serializations (see section on JSON-LD).

CSV export

Default fields ("format=csv")

/organisations/search?q=kunst&size=300&format=csv

Custom fields ("format": fields to use, with dots for nested fields "csv:field1,field2.subfield")

/organisations/search?q=kunst&size=300&format=csv:name,isil,url,classification.label.de

TSV export

Default fields ("format=tsv")

/organisations/search?q=kunst&size=300&format=tsv

Custom fields ("format": fields to use, with dots for nested fields "tsv:field1,field2.subfield")

/organisations/search?q=kunst&size=300&format=tsv:name,isil,url,classification.label.de

Auto-complete

The API supports a response format for auto-complete suggestions using a specified field:

Suggest name: "format=json:name"

/organisations/search?q=name:dnb+OR+alternateName:dnb&format=json:name

Suggest classification: "format=json:classification"

/organisations/search?q=classification.label.de:Universit%C3%A4t&format=json:classification

This can be used to set up an auto-complete search function that inserts an ID for the label that the user selected:

This sample is implemented with JavaScript and JQuery UI like this:

$('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 calls serve JSON-LD (JSON for Linking Data). You can experiment with that by pasting responses or URLs in the JSON-LD Playground.

JSON-LD Context

/organisations/context.jsonld

RDF conversion

Use a JSON-LD processor to convert responses to RDF, e.g. to N-Quads, an N-Triples superset, with jsonld-cli:

jsonld format --nquads http://lobid.org/organisations/DE-6

Using the Accept header, individual organisations can be requested directly as RDF/XML, Turtle, or N-Triples:

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

As described in the section on content types, these are also supported in the format query parameter and as file extensions in URLs:

/organisations/DE-6.rdf

/organisations/DE-6.ttl

/organisations/DE-6.nt

Sample document

The JSON-LD document below exemplifies the fields and content of an API response for a single organization.

{
  "rs" : "053150000000",
  "linkedTo" : {
    "id" : "http://lobid.org/organisations/DE-605#!",
    "label" : "Hochschulbibliothekszentrum des Landes Nordrhein-Westfalen (hbz)"
  },
  "telephone" : "0049 221 :4 78-5685",
  "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"
    }
  },
  "mainEntityOfPage" : {
    "id" : "http://lobid.org/organisations/DE-38M#!",
    "dateCreated" : "18-11-99",
    "dateModified" : "19-12-24",
    "wasGeneratedBy" : {
      "type" : "Activity",
      "used" : [ {
        "id" : "http://services.dnb.de/sru/bib?operation=searchRetrieve&query=isl%3DDE-38M&recordSchema=PicaPlus-xml&version=1.1",
        "sourceOrganization" : {
          "id" : "https://sigel.staatsbibliothek-berlin.de/vergabe/isil/",
          "label" : "Deutsche ISIL-Agentur und Sigelstelle an der Staatsbibliothek zu Berlin"
        }
      } ]
    }
  },
  "@context" : "http://lobid.org/organisations/context.jsonld",
  "url" : "https://www.zbmed.de",
  "picaPPN" : "009008853",
  "provides" : "https://www.livivo.de/?idb=ZBMED",
  "name" : "ZB MED - Informationszentrum Lebenswissenschaften, Köln",
  "containedIn" : "http://sws.geonames.org/6553049/",
  "location" : [ {
    "address" : {
      "streetAddress" : "Gleueler Str. 60",
      "addressLocality" : "Köln",
      "postalCode" : "50931",
      "addressCountry" : "DE",
      "type" : "PostalAddress"
    },
    "openingHoursSpecification" : {
      "description" : "Mo-Fr 9.00-19 (Lesesaal)",
      "comment" : "Ausleihe/Allg. Information: Mo-Fr 9.00-16.00, InfoCenter: Mo-Fr 9.00-15.00; weitere Schließtage s.Homepage",
      "type" : "OpeningHoursSpecification"
    },
    "geo" : {
      "lat" : "50.92466",
      "lon" : "6.91666"
    },
    "type" : "Place"
  } ],
  "id" : "http://lobid.org/organisations/DE-38M#!",
  "gndIdentifier" : "5149318-4",
  "isil" : "DE-38M",
  "fundertype" : {
    "id" : "http://purl.org/lobid/fundertype#n07",
    "type" : "Concept",
    "label" : {
      "de" : "Körperschaft oder Stiftung des öffentlichen Rechts",
      "en" : "Corporate Body or Foundation under Public Law"
    }
  },
  "sigel" : "38 M",
  "collects" : {
    "type" : "Collection",
    "extent" : {
      "id" : "http://purl.org/lobid/stocksize#n10",
      "type" : "Concept",
      "label" : {
        "de" : "1.000.001 und mehr",
        "en" : "1,000,001 and more"
      }
    },
    "subject" : [ "Medizin" ]
  },
  "email" : "mailto:info@zbmed.de",
  "dbsID" : "BJ038",
  "name_en" : "ZB MED - Information Centre for Life Sciences, Cologne",
  "sameAs" : [ "http://www.wikidata.org/entity/Q1204536", "https://d-nb.info/gnd/5149318-4", "https://ld.zdb-services.de/resource/organisations/DE-38M" ]
}

OpenRefine

The lobid-organisations service implements the OpenRefine Reconciliation API. Follow these instructions to use it.

Reconciliation metadata request ("callback": optional JSONP callback to wrap the response into)

/organisations/reconcile?callback=jsonp

Reconciliation multi query request (expects form data via HTTP POST, use this URL in OpenRefine)

/organisations/reconcile