Occurrences-API

API to provide (co-)occurrences based on the K10plus catalog.

An occurrence gives information about how (often) a concept (or combination of concepts for co-occurrences) is used in a database.

Table of Contents

• Install
  • Configuration
  • Backends
• Usage
• API
  • GET /api
  • GET /api/voc
  • GET /databases
  • GET /status
• Maintainers
• Contributing
• License

Install

Requires Node.js v16 or later.

git clone https://github.com/gbv/occurrences-api.git
cd occurrences-api
npm i

Configuration

Optionally create a configuration file .env to change certain config options. Here are the default values:

PORT=3141
BACKEND=SQLite
DATABASE=./subjects.db
SCHEMES=./vocabularies.json
LINKS=./links.json

All vocabularies included in K10Plus Subjects are preconfigured via vocabularies.json.

Then full the backend database (SQLite by default) with subject indexing data from K10plus catalog. The script ./bin/import.js can be used to do so (not documented yet).

Backends

SQLite

This requires to start the application once to create SQLite database file under subjects.db. Then download data from https://doi.org/10.5281/zenodo.7016625 (given as tabulator separated file table with columns PPN, vocabulary key, and notation) and import into SQLite file:

URL=$(curl -sL "https://zenodo.org/api/records/7016625" | jq -r '.files[]|select(.key|endswith(".tsv.gz"))|.links.self')
curl -sL $URL | zcat | sqlite3 subjects.db -cmd ".mode tabs" ".import /dev/stdin subjects"

PostgreSQL

not documented yet

Usage

npm run start

API

GET /api

Returns a (possibly empty) array of JSKOS Concept Occurrences. Depending on query parameters the result consists of:

• the occurrence of a concept specified via member
• the occurrence of concepts in a record specified via record
• the co-occurrences of a concept specified via member in all records, when query parameter scheme is given

Occurrences contain deep links into K10plus catalog for selected vocabularies.

Query parameters:

• member - URI of a concept from supported vocabularies
• record - URI of a K10plus record
• scheme - URI of a target concept scheme (when given, co-occurrences are returned; when value * is given, all supported target schemes are used)
• threshold - a minimum threshold for co-occurrences to be included

GET /api/voc

Returns an array of supported vocabularies as JSKOS Concept Schemes.

GET /databases

Returns an array of supported databases. Return format is experimental.

GET /status

Returns information about the service. Return format is experimental.

Maintainers

• @stefandesu
• @nichtich

Contributing

PRs accepted against the dev branch.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2022 Verbundzentrale des GBV (VZG)