Vitrine API

1. About

This documentation is part of the vitrine api.

https://api.vitrine.gesis.org

2. Available Endpoints

The api consists of two endpoints to be used to build simple search frontends upon.

Search Endpoint: _search

GET/POST https://api.vitrine.gesis.org/search/{indexFilter}/_search

Document Endpoint: _doc

GET https://api.vitrine.gesis.org/search/{indexFilter}/_doc/{documentId}

Valid values for {indexFilter} are:

The Search Endpoint allowes combinations of indexFilter like, e.g. dprex-soda,dprex-dbkapps-oai. Valid values for {documentId} are all identifiers that are part of a filtered request. To find more parameters for _search look into the elasticsearch 8 documentation. A general description of the response format can be found here

3. Index Format

This section describes the response format under /hits/hits/{count}/_source . It represents the content of one document in the index.

A formal definition of the index format can be found under

schema/v0.1.0/

Table 1. Table Index Fields
Fieldname	Note
abstract	A multilang label holding an abstract
availability	Typically holds an `availabilityType` and optional an `embargoData`. See Dara v4
collectionModes	An array of labeled types. See Dara v4
contributions	Contributions to the publication. A contribution consists of type, agent and role. An agent can be of type Institution or Person. For details follow the schema definition.
describedBy	DescribedBy refers to the actual metadata of the resource. The describedBy field contains information about the creation of the metadata.
documentId	It is string. It’s content is typically defined during ingest.
dprexConcepts	A list of dprexConcepts. Each dprexConcepts consists of a type,uri,notation,source,label.
dprexGroups	A list of dprexGroups. Each dprexGroups consists of a type,uri,notation,source,label.
dprexTypes	A list of dprexTypes. Each dprexType consists of a type,uri,notation,source,label.
geographicCoverages	A list of country codes. See Dara v4
handles	A handle is a persitent Identifier, e.g. a DOI. It has a type, a notation, an url, and a source.
issuers	A list of issuers. Each issuer is described by an URI and a multilang label.
natureOfContents	Basically a type.
otherTitleInformation	A string for additional Info.
publications	This field holds information about publication events.
publisher	This field holds information about the publisher as a simple string.
resourceLanguage	ISO 3166-1 alpha-3 string. See Dara v4
rights	Licensing. Dara v4
sampling	Information about the sampling method in form of a multilang string.
subjects	A list of subjects. Each subject consists of a type,uri,notation,source,label.
temporalCoverages	A labeled list of date ranges. See Dara v4
timeDimensions	Timespecific information. See Dara v4
title	The title of the resource as a multilang string.
universe	See Dara v4
uri	A uri for the resource. We preferre the doi here. See handles.
searchappPublisher	The field is filled at index time to identify the institution responsible for the ingested data.
calculatedTemporalCoverage	The field is calculated at index time. It contains a list of years that are covered by the resource.

4. Usage

The Vitrine API can be used directly by front end applications using the search-ui framework.

Live Examples

5. Datasources

The Vitrine-API provides and combines data from various sources of partner institutions.

To get your own {indexFilter} you can:

Become a partner of Sowidata. Each partner gets an {indexFilter} and a customizable live example under /ui
Become a partner in other GESIS projects and provide your data over a defined OAI-PMH endpoint or provide your dataset in a git repository.

6. OAI-PMH indexing

Vitrine-API can be enriched with external datasources provided via OAI-PMH. This section describes how to provide a proper OAI-PMH endpoint.

Provide a OAI-PMH Set that contains exactly the data you like to transfer into the Vitrine-API.
Provide a OAI-PMH metadataPrefix that serves metadata in da|ra Metadata Schema Version 4.0.
Provide as much data as possible. The table below shows the supported DARA-Fields as of today.

7. Git indexing

If you have no running OAI-PMH provider within your institution you can provide your data via a git repository.

The repo must be available over HTTPS and readable for everyone
The repo must contain a data directory (name == data)
The data directory must contain only xml files that are valid against da|ra Metadata Schema Version 4.0

8. Indexing Dataformat

Table 2. Table Supported Dara Fields
da-ra field	da-ra seq
resourceType	1
titles	4
creators	7
dataURLs	8
doiProposal	9
publicationDate	10
availability	13
classifications	17
descriptions	20
geographicCoverages	21
universes	22
samplings	23
temporalCoverages	24
timeDimensions	25
collectionModes	28

The da|ra Metadata will be mapped to our internal Index Format by the searchapp-indexer#DaraTransformer

Example OAI-PMH

https://dbkapps.gesis.org/dbkoai/?verb=ListRecords&metadataPrefix=oai_dara&set=DPREX

Example Git

https://github.com/jschnasse/dara4-xml-over-git-example/tree/master

or

https://gitlab.com/jschnasse/dara4-xml-over-git-example

8.1. The DPREX-Project

For DPREX we support a set of special vocabularies.

Controlled Vocabulary	Classification Scheme Id	License
https://vocabularies.cessda.eu/vocabulary/rexconcepts	rexconcepts/1.0.0
https://vocabularies.cessda.eu/vocabulary/rexgroups	rexgroups/1.0.0
https://vocabularies.cessda.eu/vocabulary/rexdatatype	rexdatatype/1.0.0

Controlled Vocabulary

Classification Scheme Id

License

https://vocabularies.cessda.eu/vocabulary/rexconcepts

rexconcepts/1.0.0

https://vocabularies.cessda.eu/vocabulary/rexgroups

rexgroups/1.0.0

https://vocabularies.cessda.eu/vocabulary/rexdatatype

rexdatatype/1.0.0

Example: Dara transport of DPREX specific vocabulary

<classification>
    <classificationExternal>
        <language>de</language>
        <classificationSchema>rexdatatype/1.0.0</classificationSchema>
        <terms>
            <term>Befragungsdaten</term>
            <term>Standardisierte Daten</term>
            <term>Numerische Daten</term>
        </terms>
    </classificationExternal>
</classification>
<classification>
    <classificationExternal>
        <language>de</language>
        <classificationSchema>rexconcepts/1.0.0</classificationSchema>
        <terms>
            <term>Rechtspopulismus</term>
            <term>Patriotismus</term>
            <term>Rechtsextremismus</term>
            <term>Nationalismus</term>
            <term>Autoritarismus</term>
            <term>Ethnozentrismus</term>
            <term>Soziale Dominanzorientierung</term>
            <term>Xenophobie</term>
            <term>Neonazismus</term>
            <term>Intergruppenkontakt</term>
            <term>Bedrohungswahrnehmungen </term>
            <term>Eigengruppenbevorzugung / Wohlfahrtschauvinismus</term>
            <term>Identität &amp; soziales Zugehörigkeitsgefühl</term>
            <term>Migrantisierte Gruppen</term>
        </terms>
    </classificationExternal>
</classification>
<classification>
    <classificationExternal>
        <language>de</language>
        <classificationSchema>rexgroups/1.0.0</classificationSchema>
        <terms>
            <term>BIPoC</term>
            <term>Herkunft</term>
            <term>(Spät-)Aussiedler*innen/Russlanddeutsche</term>
            <term>Türkei</term>
            <term>Religiöse Zugehörigkeit</term>
            <term>Jüd*innen</term>
            <term>Muslim*innen</term>
            <term>LGBTQIA+ Mitglieder</term>
            <term>Menschen mit Beeinträchtigung(en)/Behinderung(en)</term>
        </terms>
    </classificationExternal>
</classification>