Description

The method entities is providing access to the the Lucene search index of entities used at DDB. This method provides response data only as application/json. It is a read-only service and must be accessed with a HTTP-GET-request.
GET /entities?<QueryParameters> HTTP/1.1

Request Header

NameValue(s)RequiredRepeatableDefault valueDescription
Acceptapplication/json
*/*
yesnoapplication/jsonSpecifies the format of the accepted data. Every request needs to be sent with a valid Accept Header defining the requested response format. Otherwise the response to the request will be a 406 - Not acceptable status code. If the request accepts every kind of data (Accept: */*) JSON will be returned.
AuthorizationOAuth oauth_consumer_key="<API key>"yesnoAn API key is mandatory for data access. You may enclose it by either sending it as Query Parameter or (as mentioned here) in the Request Header.
Hostapi.deutsche-digitale-bibliothek.deyesnoThe host is mandatory.

Back To Top

Parameters

Query

ParameterValue(s)RequiredRepeatableDefault valueDescription
facet<facet name>noyesThis is the name of a facet which will be taken into account. Only facets which are supplied via a query parameter will be included into the result.
<facet_name><query string>noyesThe value of a query parameter named like a valid, existing facet defines a search query on the given facet name. It allows to reduce the result by certain values of facets.
facet.limit<number>nonoLimits the number of values of a facet to the given amount.
minDocs<number>nonoThe amount of documents a facet must exceed to be included in the result set.
oauth_consumer_key<API key>yesnoAn API key is mandatory for data access. You may enclose it by either sending it as Query Parameter or (as mentioned here) in the Request Header.
offset<number>nonoThis is the number of the first entry of the result.
query<query string>yesno*:*Term(s) to be searched. Must be URL-encoded and compliant to the SOLR Query Syntax.
rows <number>nonoThis is the count of result entries to be shown in total.
sort<restricted values>nono

Defines the sorting order, which can be one of the following values. It requires the query parameter, otherwise the sort is always random_<seed>.

  • ALPHA_ASC
  • ALPHA_DESC
  • RANDOM_<seed>
  • RELEVANCE

Back To Top

Authorization

This method needs an API key for authentication (Who are you?) and authorization (What you are authorized to do?). For more information please read the Authorization How-To.

This method is offered over HTTP and HTTP Secure.

Back To Top

Errors

CodeTextDescription
404Not FoundEither the item does not exist or has no data.
406Not AcceptableThe Request Header is not acceptable. Please see section Request Header.
500Server ErrorSomething went terribly wrong. An error message will provide a meaningful description.

Back To Top

Samples

Request 1

Search for all entities on the entity index.

GET /entities?query=*:*&oauth_consumer_key=abcdefgh12345678 HTTP/1.1
Host: api.deutsche-digitale-bibliothek.de
Accept: application/json

Response

{
   "numberOfResults":127746,
   "results":[
      {
         "name":"single",
         "docs":[
            {
               "id":"http://d-nb.info/gnd/116901128",
               "dateOfBirth":"5. März 1871",
               "dateOfDeath":"2. August 1943",
               "placeOfBirth":[
                  "Schornbach"
               ],
               "placeOfDeath":[
                  "Vaihingen an der Enz"
               ],
               "preferredName":"Karl Grunsky",
               "variantName":[
                  "Karl Wilhelm Siegfried Grunsky"
               ],
               "professionOrOccupation":[
                  "Musikschriftsteller"
               ],
               "count":14,
               "type":"person"
            },

            ...

         ],
         "numberOfDocs":1000
      }
   ],
   "facets":[
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_name_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_place_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_gender_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_occupation_fct"
      }
   ],
   "correctedQuery":"",
   "highlightedTerms":[

   ],
   "randomSeed":""
}

Request 2

Search for all entities of type person.

GET /entities?query=type:person HTTP/1.1
Host: api.deutsche-digitale-bibliothek.de
Accept: */*
Authorization: OAuth oauth_consumer_key="abcdefgh12345678"

Response

 {
   "numberOfResults":127746,
   "results":[
      {
         "name":"single",
         "docs":[
            {
               "id":"http://d-nb.info/gnd/116901128",
               "dateOfBirth":"5. März 1871",
               "dateOfDeath":"2. August 1943",
               "placeOfBirth":[
                  "Schornbach"
               ],
               "placeOfDeath":[
                  "Vaihingen an der Enz"
               ],
               "preferredName":"Karl Grunsky",
               "variantName":[
                  "Karl Wilhelm Siegfried Grunsky"
               ],
               "professionOrOccupation":[
                  "Musikschriftsteller"
               ],
               "count":14,
               "type":"person"
            },

            ...

         ],
         "numberOfDocs":1000
      }
   ],
   "facets":[
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_name_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_place_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_gender_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_occupation_fct"
      }
   ],
   "correctedQuery":"",
   "highlightedTerms":[

   ],
   "randomSeed":""
}

Request 3

Search for the entity with the identifier http://d-nb.info/gnd/118540238.

GET /entities?query=id:"http://d-nb.info/gnd/118540238" HTTP/1.1
Host: api.deutsche-digitale-bibliothek.de
Accept: application/json
Authorization: OAuth oauth_consumer_key="abcdefgh12345678"

Response

{
   "numberOfResults":1,
   "results":[
      {
         "name":"single",
         "docs":[
            {
               "id":"http://d-nb.info/gnd/118540238",
               "thumbnail":"https://commons.wikimedia.org/wiki/Special:FilePath/Goethe_(Stieler_1828).jpg?width=270",
               "dateOfBirth":"28. August 1749",
               "dateOfDeath":"22. März 1832",
               "placeOfBirth":[
                  "Frankfurt am Main"
               ],
               "placeOfDeath":[
                  "Weimar"
               ],
               "preferredName":"Johann Wolfgang von Goethe",
               "variantName":[
                  "Johann Wolfgang v. Goethe",
                  "Johann Wolfgang Goethe",
                  "Johann W. von Goethe",
                  ...
               ],
               "professionOrOccupation":[
                  "Schriftsteller",
                  "Publizist",
                  "Politiker",
                  "Jurist",
                  "Naturwissenschaftler",
                  "Theaterintendant",
                  "Maler",
                  "Zeichner"
               ],
               "count":1164,
               "type":"person"
            }
         ],
         "numberOfDocs":1
      }
   ],
   "facets":[
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_name_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_place_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_gender_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_occupation_fct"
      }
   ],
   "correctedQuery":"",
   "highlightedTerms":[

   ],
   "randomSeed":""
}

Request 4

Search for all entities which contain the term frank in any field and value Bauingenieur in the facet person_occupation_fct.

GET /entities?query=frank&facet=person_occupation_fct&person_occupation_fct=Naturwissenschaftler HTTP/1.1
Host: api.deutsche-digitale-bibliothek.de
Accept: application/json
Authorization: OAuth oauth_consumer_key="abcdefgh12345678"

Response

{
   "numberOfResults":2,
   "results":[
      {
         "name":"single",
         "docs":[
            {
               "id":"http://d-nb.info/gnd/1023901528",
               "dateOfBirth":"1969",
               "placeOfBirth":[
                  "Enkenbach-Alsenborn"
               ],
               "preferredName":"Frank Schmidt",
               "variantName":[

               ],
               "professionOrOccupation":[
                  "Naturwissenschaftler",
                  "Studienrat"
               ],
               "count":1,
               "type":"person"
            },
            {
               "id":"http://d-nb.info/gnd/104115300",
               "dateOfBirth":"1648",
               "dateOfDeath":"1728",
               "preferredName":"Johann Francke",
               "variantName":[
                  "Johannes Francke",
                  "Johannes Francus",
                  "Joannes Francus",
                  "Johann Franco",
                  "Johann Franke",
                  "Johann Frank"
               ],
               "professionOrOccupation":[
                  "Arzt",
                  "Naturwissenschaftler"
               ],
               "count":14,
               "type":"person"
            }
         ],
         "numberOfDocs":2
      }
   ],
   "facets":[
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_name_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_place_fct"
      },
      {
         "facetValues":[

         ],
         "numberOfFacets":0,
         "field":"person_gender_fct"
      },
      {
         "facetValues":[
            {
               "count":2,
               "value":"Naturwissenschaftler"
            },
            {
               "count":1,
               "value":"Arzt"
            },
            {
               "count":1,
               "value":"Studienrat"
            }
         ],
         "numberOfFacets":3,
         "field":"person_occupation_fct"
      }
   ],
   "correctedQuery":"",
   "highlightedTerms":[

   ],
   "randomSeed":""
}

 

 

 

Back To Top