This is the first version of the EconBiz API, tagged "v1".
Document version 1.00 as of 2017-03-17
Please consider the following points:
The EconBiz API follows a RESTful API design. The base URL is
https://api.econbiz.de/v1/
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.
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.
/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.
/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"
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.
/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:
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:
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.
knowledge management | API
| portal
knowledge AND management | API
| portal
Search for records that contain both words anywhere in a single record.
Boolean AND is the default operator in EconBiz.
knowledge OR management | API
| portal
Matches if either of the terms exists in a record.
knowledge NOT management | API
| portal
knowledge AND NOT management | API
| portal
Matches if knowledge is contained anywhere, but management nowhere in the same record.
"knowledge management" | API
| portal
Exact phrase must exist anywhere in the record.
title:knowledge management | API
| portal
Find records which contain knowledge in the title field and management anywhere.
Use the 'fields' method as shown above to learn the available
search fields.
title:(knowledge management) | API
| portal
title:knowledge AND title:management | API
| portal
Both words must be contained in the title.
title:"knowledge management" | API
| portal
The exact phrase must exist in the record's title.
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).
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
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.
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.
/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
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
Henning Manske h.manske@zbw.eu
Kim Plassmeier k.plassmeier@zbw.eu