EconBiz API

Version

This is the first version of the EconBiz API, tagged "v1".

Document version 1.00 as of 2017-03-17

Terms of Use

Please consider the following points:

API calls

The EconBiz API follows a RESTful API design. The base URL is

https://api.econbiz.de/v1/

Common parameters

pretty      boolean  Enable pretty printing of response. Default is false.
profile     string   Name of user profile. The default profile enables
                     everything used in EconBiz portal.

Hint: If you learn the API by calling the sample URLs from a browser, the Firefox extension JSONView renders the responses much nicer than a pretty-printed but plain text view.

Response format

Common properties

message     string   Error message if an error occurred.
status      integer  Status code of response. Always matches the status
                     sent in the HTTP header.
                     200 indicates a successfully processed request.
                     4xx codes are used for client-side errors,
                     5xx are server-side errors.

Methods

fields

/v1/fields
/v1/fields?scope={scope}

Use the 'fields' method to get lists of available fields and their scopes.

The scopes ("use cases") are:

display     Field is contained in responses and can be displayed.
facet       Field can be used in facets.
search      Field can be used for a fielded search.
sort        Result can be ordered by this field.
suggest     Field can be used as source for suggestions.

record

/v1/record/{id}
/v1/record/{id}/avail/{client}

The 'record' method retrieves the metadata details of a single record.

The parameters are:

id          integer    EconBiz record id. Mandatory.
client      string     Client identification, e.g. IP address, library id
mlt         string     Similarity measures for display of "More like this"

More like this (MLT)

The API provides an option to extend the response of the 'record' method by metadata snippets of more records similar to the requested one.

Currently these similarity measures are available:

author      similarity based on personal and corporate creators
subject     similarity based on subjects/keywords and classifications

MLT is toggled by setting the desired similarity measure with the mlt parameter:

Multiple lists based on different similarity measures can be requested in a single call:

To build searches for similar records like those linked in the EconBiz portal (sample record), use the 'search' method with the mlt parameter. For more details on search see the next section.

Note: MLT searches must be based on a single similarity measure.

search

/v1/search/{query}
/v1/search?q={query}

The 'search' method delivers the hits for a given query with a subset of metadata suitable to build list responses. Use the 'record' method from above to display detailed metadata and advanced availability options.

The parameters are:

query       string     Search query.
q                      Alias for query.
fulltext    boolean    Search full texts (partially available). Default is off.
size        integer    Maximum number of records to be returned. Defaults to 10.
from        integer    First record to be returned. Defaults to 1.
facets      string     Fields that should be faceted.
facet_size  integer    Maximum number of items per facet. Defaults to 40.
facet       string     Filter query by facet values.
ff                     Alias for facet.
sort        string     Sort order. Default is 'score desc' (relevance ranking).
mlt         string     A similarity measure for a "More like this" search
spellcheck  boolean    Check spelling of search query. Default is off.
echo        boolean    Echo query and facet values in response. Default is off.

To learn the available fields for search, facets and sorting, use the 'fields' method:

Query syntax

The search engine behind EconBiz API v1 is currently based on Apache Solr 3.5.0, so basically Lucene's Query Parser Syntax is effective – though AND is the default conjunction operator in EconBiz, not OR.

Important note: We do not guarantee long-term availability of all of Lucene 3.5.0 parser's features through the EconBiz API. But the following subset should be considered stable for the v1 API's lifetime:

Query examples

The linked 'API' calls are sized to zero records on purpose. Watch the number of hits in response field total changing when you try the examples. See how the query field echoes the query string.

The links to 'portal' execute the same query in EconBiz portal where it's easier to see the hits changing – and where you can directly modify the sample queries in the search box.

Make sure the query string is properly URL-escaped, e.g. the last example looks like this:

Also be aware of Escaping Special Characters that are part of Lucene's query syntax before URL-escaping the query string.

Note: The requirement of handling the special characters is likely to be removed in a future API version.

All strings are expected to be encoded in UTF-8, e.g. the query for Ökonomie looks like this:

Remember you can set &echo=on to check the echoed query in the response which displays the URL-unescaped query string (example).

Facets and filtering by facet values

Specify the desired fields for faceting by concatenating the field names with a blank as separator or repeating the facets parameter. These queries both add the date and person facets to the search for knowledge management:

To apply a value from the facets, the facet parameter (or ff) is used. Again multiple values can be selected by concatenation with a blank or repetition of the parameter.

The syntax is like in fielded search, field:value. The value must be put in quotes when it contains blanks, commas or other special characters.

These queries both filter the result by the date 2007 and the person Nonaka, Ikujiro:

Available fields: https://api.econbiz.de/v1/fields?scope=facet

Spell Checker

Query spell checking can be enabled by setting the parameter spellcheck=on.

A suggestion consists of the corrected query (collation) and the corresponding number of hits, that will be matched by this query (hits). Currently, there can only be no or one suggestion. If no suggestion is available an empty array will be returned.

Currently, no further options are exposed to tweak the spell checker behavior.

More like this

Searches for "More like this" (MLT) originating from a single record and a similarity measure are explained in the MLT subsection of the 'record' method's description. See above.

suggest

/v1/suggest/{prefix}
/v1/suggest/{field}/{prefix}
/v1/suggest/?field={field}&q={prefix}

Use the 'suggest' method to get suggestions for a partial input ("prefix").

The parameters are:

field       string     Name of suggest field. Defaults to 'text'.
prefix      string     String to be completed by suggestions.
q                      Alias for prefix.
oid         string
opensearch  boolean    Trigger OpenSearch response format.

Available fields: https://api.econbiz.de/v1/fields?scope=suggest

See also

Changes

1.00 2017-03-17

0.05 2013-03-11

0.04 2013-02-20

0.03 2012-07-12

0.02 2012-06-05

0.01 2012-04-05

Author

Henning Manske h.manske@zbw.eu

Contributor

Kim Plassmeier k.plassmeier@zbw.eu