Skip to end of metadata
Go to start of metadata

Description

The method search is providing an interface to the search engine of the 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. dd

The resulting JSON object is made up of several parts. Each part will be described separately. The described parts are properties of the search result object and can be joined to form a complete result object.

First the number of results is in the property numberOfResults. This gives the total number of found results independent of the rows returned.

numberOfResults  Expand source
Content of this page

Another part is the hightlightedTerms. This contains an array of all terms that should be highlighted. In the preview they are already highlighted. But this array can be transferred to the detail view where the terms could be highlighted as well.

highlightedTerms  Expand source

If the random sorting is activated this property will contain a value that can be used as subsequent sort-parameter. The value should be used as is. If the random sorting is deactivated or the query was not a get-all-objects-query (* or *:*) the property will be empty. See below for a set property:

randomSeed  Expand source

If the query is mistyped, i.e. there are more hits for an alternative spelling of one of the query terms a corrected query will be returned with the search result. This property correctedQuery contains the entered query with all terms corrected. The corresponding JSON property is noted below:

correctedQuery  Expand source

One lengthier part are the facets and their values. Each facet defined to have a displayType of SEARCH will always be returned with the search results. If no value is given for the query parameter facet the facets will look like this:

facets  Expand source

The property field will contain the name of the facet. The numberOfFacets is the number of distinct facet values found for this facet. If the facet.limit parameter is set in the query the number of facets will be equal to this number. The facetValues array will contain all found values and the number of documents having this facet if this facet is asked for. As in the example given below:

numberOfFacets  Expand source

At last the search results matching the query are returned. The actual results are again made up of several parts. The results property contains an array of clusters. Each cluster is again a object containing a name and an array of documents related to this cluster. In the case of an unclustered search, there will only be one cluster named single. Each document contains its ID, a label with a short description of the item, a preview that contains the HTML snippet that should be used for the list view of the item. The link to the image in the thumbnail div can be a absolute link or a link to a binary on the backend. In this case it is relative to the backend host. The category property gives the type of the item. The two possible values are “Institution” and “Kultur”. This is a repetition of the data-type attribute in the first div of the preview. So it could be removed if no longer needed. At last the location as longitude and latitude of this item are given. For most items the values will be null. This value is used in the institution map to locate the institutions. The last property of a cluster is the numberOfDocs this cluster contains.

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.

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

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.

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.

Samples

Request 1

Search for all data in the DDB which contain “Johann Wolfgang Goethe” using query authorization.

The search result is limited by 1000 entries for each search result. To get all entries it is necessary to use the Query Parameters offset, rows and sort (see Request 2).

Request 2

Search over all information in the data sets which contain the term “Johann+Wolfgang+G*”, but give me all documents after the 21st most relevant results and only up to two results at all. Authorization over HTTP Request Header is used.

Request 3

Search for all documents which contain the term “Romanorum et Germanorum” in any field and include the facet place_fct in the result retaining all values of the facets which are part of at least one documents or more. Authorization over HTTP Request Header is used.

Request 4

Search for all documents which contain the term “Romanorum et Germanorum” in any field and contribute to the facet type_fct with the mediatype value “Text”. The result contains the values of type_fct. Authorization over HTTP Request Header is used.

Request 5

Search for all documents which are located in Berlin. The result will be sorted ascending by their label.

 

 

  • No labels