BASE Interface Guide – Version 1.

27 (March 2023)

BASE HTTP Interface

BASE (Bielefeld Academic Search Engine, https://www.base-search.net/) indexes web

resources and harvests metadata of scientific repositories via OAI-PMH. It is based on the open
source search engine software Lucene/SOLR. Currently more than 10700 content providers
and 320 million documents are covered in BASE. The data structure related to the index
structure is based on Dublin Core with several extensions.

BASE supplies a HTTP API. It can be used for non-commerical purposes only. The interface is
IP controlled or with an apikey and interested users have to register at https://www.base-
search.net/about/en/contact.php.

The interface is located at:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi

Once registered (i.e. an ip address or ip range or apikey has been configured) the interface can
be easily tested by editing the url in a browser (located in the activated ip range or the url is
appended with the apikey) and looking for the delivered xml responses.
Example for an apikey: apikey=54351320c8100da640f222b653977182

Rate limiting: One request per second (1 QPS).

Currently the following methods are supported:

Method Description

ListRepositories This method lists all available repositories or the member

repositories of a certain collection. The method delivers an xml list
of internal string identifiers for the repository.

ListProfile This method lists basic information about the requested repository
included in BASE (defined by the internal BASE string identifier)

PerformSearch This is the interface core function. It performs queries and delivers
the corresponding results. The BASE interface supports the SOLR
query term syntax.

I. ListRepositories

Syntax:
<interface-url>?func=ListRepositories&coll=<collection_name>

Parameter Value Status Description

func ListRepositories mandatory
coll <collection_name> optional Existing pre-defined collections: see Appendix,
section „Collection-related queries“. The
collection name must exist, otherwise all BASE
repositories will be listed.
format json optional Set response format to JSON
Default: XML
apikey <apikey> mandatory if access with apikey is granted

-1-
BASE Interface Guide – Version 1.27 (March 2023)

Examples:

1. Repositories located in Europe:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=ListRepositories&coll=ceu

Response:
<?xml version="1.0" encoding="utf-8"?>
<collection>
<collection_name>ceu</collection_name>
<list_repositories>
<repository>
<activation_date>2020-08-26</activation_date>
<name>OPUS - Publikationsserver der Hochschule Augsburg</name>
<name_en>OPUS - Publication Server of Hochschule Augsburg</name_en>
<internal_name>fthsaugsburg</internal_name>
</repository>
<repository>
<activation_date>2020-08-26</activation_date>
<name>Publikationsserver der Hochschule Landshut</name>
<name_en>Publication Server of Hochschule Landshut</name_en>
<internal_name>fthslandshut</internal_name>
</repository>
(...)
</list_repositories>
</collection>

2. Repositories located in Germany:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=ListRepositories&coll=de

3. Repositories located in North Rhine-Westphalia, Germany:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=ListRepositories&coll=denw

II. ListProfile

This method delivers metadata information about a specific repository.

Syntax:
<interface-url>?func=ListProfile&target=<internal_name>

Parameter Value Status Description

func ListProfile mandatory
target <internal_name> mandatory Internal name of a single repository as
delivered by ListRepositories.
format json optional Set response format to JSON
Default: XML

-2-
BASE Interface Guide – Version 1.27 (March 2023)

Example:

1. Basic information of the repository „ftubbiepub“ including number of all documents, Open
Access documents, Non-Open Access documents, documents with Creative Commons license
and documents with Public Domain license:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=ListProfile&target=ftubbiepub

Response:

<?xml version="1.0" encoding="utf-8"?>

<repository>
<activation_date>2011-10-07</activation_date>
<country>de</country>
<name>PUB - Publikationen an der Universität Bielefeld</name>
<name_en>PUB - Publications at Bielefeld University</name_en>
<num_non_oa_records>56424</num_non_oa_records>
<num_oa_cc_records>1525</num_oa_cc_records>
<num_oa_pd_records>118</num_oa_pd_records>
<num_oa_records>12790</num_oa_records>
<num_records>69223</num_records>
</repository>

III. PerformSearch

PerformSearch is the essential method to search and retrieve BASE data. As a new feature the
current version supports the usage of facets.

Syntax:
<interface-url>?func=PerformSearch&coll=<collection>&query=<queryterm>&(...)
<interface-url>?func=PerformSearch&target=<internal_name>&query=<queryterm>&(…)

Parameter Value Status Description

func PerformSearch mandatory
query <queryterm> mandatory Search term
For syntax details see Appendix, section „Query
syntax“. Max. 1000 characters are allowed.
coll <collection> optional For existing, pre-defined collections see
Appendix, section „Collection-related queries“
target <internal_name> optional Internal name of a single repository as
delivered in ListRepositories
hits <number> optional Maximum number of records per response
(0 is allowed)
Default: 10; max.: 120
offset <number> optional Starting position in the result set
Default: 0; max.: 999

-3-
BASE Interface Guide – Version 1.27 (March 2023)

sortby <field+asc|desc> optional Sorting

A sort ordering must include a single field
name (see Appendix, section „Fields“, table
column „Sorting“.), followed by a whitespace
(escaped as + or %20 in URL strings), followed
by sort direction (asc or desc).
Default: sort by relevance
boost oa optional Push open access documents upwards in the
result list.
Default: without boosting
format json optional Set response format to JSON
Default: XML
fields <field1,field2,...> optional The result records only contain fields listed in
the comma-separated field list.
For existing, pre-defined fields see Appendix,
section „Fields“.
facets <field1,field2,...> optional The response contains an extra section
"facet_counts/facet_fields" with fields from the
comma-separated facets list. This section
provides a breakdown or summary of the
results. From the user's perspective, faceted
search breaks up search results into multiple
categories, typically showing counts for each,
and allows the user to "drill down" or further
restrict their search results based on those
facets. Use of faceting does not affect the
results section of a search response.
For existing, pre-defined facet fields see
Appendix, section „Fields“, table column
„Facet“.
facet_limit <number> optional Maximum number of constraint counts that
should be returned for the facet fields.
Default: 100; min:1; max: 500
facet_sort count|index optional Ordering of the facet field constraints:
count - sort by count (highest count first)
index – alphabetical sorting
Default: count
f_<field> <search_term> optional Search term for the facet field.
e.g. The results can be refined by certain criteria
f_dcsubject (facets), such as subject.
For existing, pre-defined facet fields see
Appendix, section „Fields“, table column
„Facet“.

If the arguments „target“ or „coll“ are missing or the value for „target“ does not exist, the
query addresses all BASE repositories.

-4-
BASE Interface Guide – Version 1.27 (March 2023)

Examples:

For query syntax details see Appendix, section „Query syntax“.

1. Documents from the repository „ftubbiepub“ containing the terms „lossau“ and
„summann“ (search in the whole document):

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&target=ftubbiepub&query=lossau+summann

2. Documents from Italian repositories containing the term „manghi“ in the dccreator field
(author). The flag „boost“ pushes open access documents upwards in the result list:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&coll=it&query=dccreator:manghi&boost=oa

3. Documents containing the terms („algebra“ and „linear“) or („algebra“ and „numerical“) or
(„algebra“ and „linear“ and „numerical“):

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=algebra+AND+(linear+OR+numerical)

4. Documents containing the terms („operator“ or „algorithms“) and („linear“ or „numerical“):

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=(operator+OR+algorithms)+AND+(linear+OR+numerical)

5. Documents containing the terms „linear“ and „algebra“ but not „numerical“:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=linear+algebra+NOT+numerical

6. Documents containing the terms „schmidt“ in dccreator field (author) and „biology“ in
dctitle. The response starts after record 5 (offset=5) and contains max. 5 hits with the fields
dctitle, dccreator and dcyear:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=dccreator:schmidt+dctitle:biology&hits=5&offset=5&field
s=dctitle,dccreator,dcyear

7. Documents containing the term „unix“ and published between 1983 and 2009, sorted by
year of publication (dcyear) in descending order:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=unix+dcyear:[1983+TO+2009]&sortby=dcyear+desc

-5-
BASE Interface Guide – Version 1.27 (March 2023)

8. Documents containing the term „unix“ with facets dcsubject and dcyear each with max. 10
hits (default facet sorting „count“):

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=unix&facets=dcsubject,dcyear&facet_limit=10

9. Documents containing the term „unix“ and the exact terms "computer science" in dcsubject
and „2008“ in dcyear; with facets „dcsubject“ and „dcyear“ each with max. 10 hits:

https://api.base-search.net/cgi-bin/BaseHttpSearchInterface.fcgi?
func=PerformSearch&query=unix&facets=dcsubject,dcyear&f_dcsubject=%22computer%20
science%22&f_dcyear=2008&facet_limit=10

Please note:
Results of the search „query=unix+dcsubject:education“ can differ from results of the faceted
search „query=unix&f_dcsubject=education“. Facets search for the exact term „education“ in
the dcsubject field, while the pure query search delivers records with dcsubject fields
containing the term „education“ also as a single keyword of a field's contents, e.g. "higher
education".

Example Response Format:

<?xml version="1.0" encoding="UTF-8"?>

<response>
<lst name="responseHeader">
<bool name="zkConnected">true</bool>
<int name="status">0</int>
<int name="QTime">128</int>
<lst name="params">
<str name="q">creator:summann</str>
<str name="facet">true</str>
<arr name="facet.field">
<str>f_dcsubject</str>
<str>f_dcyear</str>
</arr>
<str name="facet.limit">10</str>
<str name="facet.mincount">1</str>
<str name="facet.sort">count</str>
<str name="fl">
dccollection,dccontenttype,dccontinent,dccountry,dccreator,dcdate,dc
description,dcdocid,dcdoi,dcformat,dcidentifier,dclang,dclanguage,dc
link,dcperson,dcpublisher,dcrights,dcsource,dcsubject,dctitle,dcyear
,dctype,dcclasscode,dctypenorm,dcdeweyfull,dcdeweyhuns,dcdeweytens,d
cdeweyones,dcautoclasscode,dcrelation,dccontributor,dccoverage,dchda
te,dcoa,dcrightsnorm</str>
<str name="fq">collection:ftubbiepub</str>
</lst>
</lst>
<result name="response" numFound="70" start="0" maxScore="8.910765">
<doc>
<date name="dchdate">2019-09-23T12:46:37Z</date>

-6-
BASE Interface Guide – Version 1.27 (March 2023)

<str name="dcdocid">
a3e98a979171fc179135968f2e5bbf5d7e8696f2ff964b6f02050bb479bcdf8b
</str>
<str name="dccontinent">ceu</str>
<str name="dccountry">de</str>
<str name="dccollection">ftubbiepub</str>
<str name="dcprovider">PUB - Publications at Bielefeld
University</str>
<str name="dctitle">10 years BASE: A contribution to the worldwide
development of repositories</str>
<arr name="dccreator">
<str>Pieper, Dirk</str>
<str>Summann, Friedrich</str>
</arr>
<arr name="dcperson">
<str>Pieper, Dirk</str>
<str>Summann, Friedrich</str>
</arr>
<arr name="dcauthorid">
<str>Pieper, Dirk | orcid:0000-0002-6083-9348</str>
<str>Summann, Friedrich | orcid:0000-0002-6297-3348</str>
</arr>
<arr name="dcsubject">
<str>Bielefeld Academic Search Engine</str>
<str>ddc:020</str>
</arr>
<str name="dcdate">2014</str>
<int name="dcyear">2014</int>
<arr name="dctype">
<str>info:eu-repo/semantics/conferenceObject</str>
<str>doc-type:conferenceObject</str>
<str>text</str>
</arr>
<arr name="dctypenorm">
<str>13</str>
</arr>
<arr name="dcidentifier">
<str>https://pub.uni-bielefeld.de/record/2710028</str>
</arr>
<str name="dclink">https://pub.uni-bielefeld.de/record/2710028</str>
<str name="dcsource">Pieper D, Summann F. 10 years BASE: A
contribution to the worldwide development of repositories. Presented
at the China IR Seminar 2014.</str>
<arr name="dclanguage">
<str>eng</str>
</arr>
<str name="dcrights">info:eu-repo/semantics/openAccess</str>
<arr name="dcdeweyfull">
<str>020</str>
</arr>
<arr name="dcdeweyhuns">
<str>0</str>

-7-
BASE Interface Guide – Version 1.27 (March 2023)

</arr>
<arr name="dcdeweytens">
<str>02</str>
</arr>
<arr name="dcdeweyones">
<str>020</str>
</arr>
<arr name="dcclasscode">
<str>020</str>
</arr>
<int name="dcoa">1</int>
<arr name="dclang">
<str>eng</str>
</arr>
</doc>
(...)
</result>
<lst name="facet_counts">
<lst name="facet_queries"/>
<lst name="facet_fields">
<lst name="f_dcsubject">
<int name="ddc:020">42</int>
<int name="Bielefeld Academic Search Engine">12</int>
<int name="ddc:004">9</int>
<int name="Repositories">3</int>
<int name="Bibliothek">2</int>
<int name="Communication">2</int>
<int name="Comunicazione">2</int>
<int name="Informatica">2</int>
<int name="Informatics">2</int>
<int name="Informatik">2</int>
</lst>
<lst name="f_dcyear">
<int name="1994">5</int>
<int name="2009">5</int>
<int name="2014">5</int>
<int name="2017">5</int>
<int name="2004">4</int>
<int name="2005">4</int>
<int name="2006">4</int>
<int name="2013">4</int>
<int name="2015">4</int>
<int name="2016">4</int>
</lst>
</lst>
<lst name="facet_ranges"/>
<lst name="facet_intervals"/>
<lst name="facet_heatmaps"/>
</lst>
</response>

-8-
BASE Interface Guide – Version 1.27 (March 2023)

Appendix

1. Collection-related queries:

Supported values for the request parameter „coll“ and as contents of response fields
„dccontinent“ and „dccountry“.

Continents
caf Africa
cas Asia
cau Australia/Oceania
ceu Europe
cna North America
csa South America
cww Web server without geographic relation (org)
Countries
(Country code ISO 3166)
de German repositories
nl Dutch repositories
uk British repositories
etc. (...)
German Country states
debw Baden-Württemberg
deby Bayern
debe Berlin
debb Brandenburg
dehb Bremen
dehh Hamburg
dehe Hessen
demv Mecklenburg-Vorpommern
deni Niedersachsen
denw Nordrhein-Westfalen
derp Rheinland-Pfalz
desl Saarland
desn Sachsen
dest Sachsen-Anhalt
desh Schleswig-Holstein
deth Thüringen
Austrian Country states

-9-
BASE Interface Guide – Version 1.27 (March 2023)

atbgld Burgenland
atktn Kärnten
atnö Niederösterreich
atoö Oberösterreich
atsbg Salzburg
atstmk Steiermark
att Tirol
atvbg Vorarlberg
atw Wien
Swiss Country states
chag Aargau
chai Appenzell Innerrhoden
char Appenzell Ausserrhoden
chbe Bern
chbl Basel-Landschaft
chbs Basel-Stadt
chfr Freiburg
chge Genf
chgl Glarus
chgr Graubünden
chju Jura
chlu Luzern
chne Neuenburg
chnw Nidwalden
chow Obwalden
chsg St. Gallen
chsh Schaffhausen
chso Solothurn
chsz Schwyz
chtg Thurgau
chti Tessin
chur Uri
chvd Waadt
chvs Wallis
chzg Zug
chzh Zürich

- 10 -
BASE Interface Guide – Version 1.27 (March 2023)

2. Fields (used for search and response)

Used as request parameters in „query“, „fields“, „facets“, „sortby“ and as contents of response
fields. Please note that only fields marked with „x“ are allowed in the respective parameters.

Internal fields
Field Description Status Query Facet Sorting
dccollection internal BASE repository name single x x
dchdate date of harvesting/updating single x x
Bibliographic DC fields (as defined in the Dublin Core definition)
Field Description Status Query Facet Sorting
dccontributor contributor multi x
dccoverage coverage single x
dccreator author multi x x
dcdate date of publication single x
dcdescription abstract single x
dcformat format multi x
dcidentifier urls multi x
dclanguage language multi x
dcpublisher publisher multi x
dcrelation relation multi x
dcrights rights single x
dcsource source single x
dcsubject subject headings multi x x
dctitle title single x x
dctype publication and document type multi x
Dublin Core similar extra fields
Field Description Status Query Facet Sorting
dcauthorid author and his identifiers multi x
dcautoclasscode DDC class code (internal automatic multi x
categorization)
dcclasscode DDC class code derived from the multi x
document metadata
dccontenttype type of content multi x x
dccontinent continent (internal code, see section single x
„Collections“)
dccountry country code (ISO 3166) single x
dcdeweyfull DDC class code (original + automatic) multi x
dcdeweyhuns DDC class code (original + automatic): multi x x
the hundreds value

- 11 -
BASE Interface Guide – Version 1.27 (March 2023)

dcdeweytens DDC class code (original + automatic): multi x x

the tens value
dcdeweyones DDC class code (original + automatic): multi x x
the ones value
dcdocid unique record identifier single x
dcdoi DOI multi x
dclang normalized form of the language multi x x
derived from dclanguage (ISO 639-2/B:
three-letter codes)
dclink preferred url for linking single x
dcoa open access document single x x x
(0=no, 1=yes, 2=unknown)
dcorcid ORCID (Open Researcher and multi x
Contributor ID)
dcperson creator + contributor multi x x
dcprovider content provider single
dcrightsnorm normalized form of the rights derived multi x x
from dcrights
dctypenorm normalized form of the publication and multi x x
document type derived from dctype
(internal code, see section „Document
types“)
dcyear normalized form of the year derived single x x x
from dcdate

3. Document types

Codes used in the query aspect and the response field „dctypenorm“

Code Description
1 Text
11 Book
111 Book part
12 Journal/Newspaper
121 Article contribution to journal/newspaper
122 Other non-article part of journal/newspaper
13 Conference object
14 Report
15 Review
16 Course material
17 Lecture

- 12 -
BASE Interface Guide – Version 1.27 (March 2023)

Code Description
18 Thesis
181 Bachelor thesis
182 Master thesis
183 Doctoral and postdoctoral thesis
19 Manuscript
1A Patent
2 Musical notation
3 Map
4 Audio
5 Image/Video
51 Still image
52 Moving image/Video
6 Software
7 Dataset
F Other/Unknown Material

4. Alphabetic list of error messages

Message
„'query' parameter is empty or not valid!"
„'query' parameter not defined!“
„Access denied for IP address xxx.xxx.xxx.xxx and user agent xyz."
„Collection 'xyz' not found!“
„Fork failed: fork table full or process limit reached.“
„Function 'xyz' is not supported!“
„IP address xxx.xxx.xxx.xxx incorrectly specified in the configuration file (+|- not defined).“
„No results found!“
„Parameter 'func' not found!“
„Problem with the opening 'xyz' file.“
„Repository not found!“
„The system is currently unavailable due to system maintenance.“

The default error messages of the HTTP 400 and 500 status code ranges are also supported (in
connection with the index), e.g. "503 Service Unavailable". (List of HTTP status codes.)

- 13 -
BASE Interface Guide – Version 1.27 (March 2023)

Example:

<error>Collection 'xyz' not found!</error>

5. Query syntax

Entering one or more search terms (separated by blanks) will produce hits, which include all
the entered terms in one document (AND conjunction). There are, however, more options to
combine terms and to search efficiently.

You search ... Example Hits (ca.)

A and B linear algebra 77,000
A and B as a phrase (directly adjoined) "linear algebra" 34,000
A and/or B linear OR algebra 1,100,000
A and B or A and C or A, B and C algebra AND (linear OR numerical) 98,000
A and not B algebra NOT linear 400,000
from A to B (only for numbers) dcyear:[1983 TO 2009] 34,000,000
Verbatim search textus:"linear algebra" 29,000

Plural, genitive case and other word forms will be searched automatically.

The * (asterisk) substitutes any number of characters whereas the ? (question mark) only
substitutes one character. They are used to find different spellings or wordings even in
different languages in one search. If the asterisk or question mark are used, the automatic
search for different word forms will be disabled. The asterisk and the question mark can not be
applied in phrase searches.

Examples:

A search for ho*e delivers records containing „home“, „horse“, „horticulture“ etc.
A search for ho?e delivers records containing „home“, „hole“, „hope“ etc.

//F. Summann, R. Mitrenga, B.Fehling 10.03.2023

- 14 -
BASE Interface Guide – Version 1.27 (March 2023)

Changelog

2023-03-10 [Version 1.27]

* Added:
- Parameter apikey

2023-02-15 [Version 1.26]

* Changed:
- Introduction
- Limit for offset

2022-05-17 [Version 1.25]

* Added:
- List of error messages

2022-05-06 [Version 1.24]

* Changed:
- Limit for offset

2021-10-12 [Version 1.23]

* Changed:
- Limit for hits

2021-09-27 [Version 1.22]

* Changed:
- Introduction
- Limit for hits
- Limit for offset
* Added:
- Character limit for query

2021-07-07 [Version 1.21]

* Added:
- Parameter target for ListRepositories
- Parameter target for ListProfile
- New examples for PerformSearch

2020-08-28 [Version 1.20]

* Changed:
- Example 1 for ListRepositories
- Example 1 for ListProfile

2020-05-12 [Version 1.19]

* Added:
- "dcorcid" in Dublin Core similar extra fields

2019-10-30 [Version 1.18]

* Added:
- "dcauthorid" in Dublin Core similar extra fields
* Changed:
- Example Response Format

- 15 -
BASE Interface Guide – Version 1.27 (March 2023)

2019-06-06 [Version 1.17]

* Changed:
- "dcrightsnorm" to multi-value field

2018-10-19 [Version 1.16]

* Added:
- "num_oa_cc_records", "num_oa_pd_records", "num_non_oa_records" in ListProfile method

2018-03-08 [Version 1.15]

* Added:
- "activation_date", "num_records", "num_oa_records" in ListProfile method
- "activation_date" in ListRepositories method
- Changelog

- 16 -