Data

Tools

Indexes

Applications

Experiments

Open Source Science

search-query

Search Query: A Python package designed to load, lint, translate, save, improve, and automate academic literature search queries.

https://github.com/colrev-environment/search-query

Science Score: 36.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ✓
    Academic publication links
    Links to: joss.theoj.org
  • ○
    Academic email domains
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (15.2%) to scientific vocabulary

Keywords

openscience reproducible-research research systematic-literature-review systematic-review
Last synced: 6 months ago · JSON representation

Repository

Search Query: A Python package designed to load, lint, translate, save, improve, and automate academic literature search queries.

Basic Info
Statistics
  • Stars: 3
  • Watchers: 2
  • Forks: 6
  • Open Issues: 7
  • Releases: 4
Topics
openscience reproducible-research research systematic-literature-review systematic-review
Created over 2 years ago · Last pushed 6 months ago
Metadata Files
Readme Changelog Contributing License Citation

README.md

[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/CoLRev-Environment/search-query/.github%2Fworkflows%2Ftests.yml?label=tests)](https://github.com/CoLRev-Environment/search-query/actions/workflows/tests.yml) [![GitHub Release](https://img.shields.io/github/v/release/CoLRev-Environment/search-query)](https://github.com/CoLRev-Environment/search-query/releases/) ![Coverage](https://raw.githubusercontent.com/CoLRev-Environment/search-query/main/test/coverage.svg) [![PyPI - Version](https://img.shields.io/pypi/v/search-query?color=blue)](https://pypi.org/project/search-query/) [![GitHub License](https://img.shields.io/github/license/CoLRev-Environment/search-query)](https://github.com/CoLRev-Environment/search-query/releases/) [![status](https://joss.theoj.org/papers/ea1fcafb8f80fa98bcbd857cf1cfada9/status.svg)](https://joss.theoj.org/papers/ea1fcafb8f80fa98bcbd857cf1cfada9) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/CoLRev-Environment/search-query/HEAD?labpath=docs%2Fsource%2Fdemo.ipynb)

Search Query is a Python package designed to load, lint, translate, save, improve, and automate academic literature search queries. It is extensible and currently supports PubMed, EBSCOHost, and Web of Science. The package can be used programmatically, through the command line, or as a pre-commit hook. It has zero dependencies and integrates in a variety of environments. The parsers and linters are battle-tested on peer-reviewed searchRxiv queries.

Installation

To install search-query, run: commandline pip install search-query

Quickstart

Creating a query programmatically is simple: ```python from search_query import OrQuery, AndQuery

Typical building-blocks approach

digitalsynonyms = OrQuery(["digital", "virtual", "online"], field="abstract") worksynonyms = OrQuery(["work", "labor", "service"], field="abstract") query = AndQuery([digitalsynonyms, worksynonyms]) We can also parse a query from a string or a JSON search file (see the [overview of platform identifiers](https://colrev-environment.github.io/search-query/platforms/platform_index.html)) python from search_query.parser import parse

querystring = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])' query = parse(querystring, platform="pubmed") A useful feature of parsers is the built-in **linter** functionality, which helps us to validate the query by identifying syntactical errors: python from search_query.parser import parse

querystring = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract]' query = parse(querystring, platform="pubmed")

Output:

❌ Fatal: unbalanced-parentheses (PARSE_0002)

- Unbalanced opening parenthesis

Query: ("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract]

^^^

Once we have created a `query` object, we can translate it for different databases. Note how the syntax is translated and how the search for `Title/Abstract` is split into two elements: python from search_query.parser import parse

querystring = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])' pubmedquery = parse(querystring, platform="pubmed") wosquery = pubmedquery.translate(targetsyntax="wos") print(wosquery.tostring())

Output:

(AB="digital health" OR TI="digital health") AND (AB="privacy" OR TI="privacy")

``` For a more detailed overview of the package’s functionality, see the documentation.

Demo

A Jupyter Notebook demo (hosted on Binder) is available here: Binder

Encounter a problem?

If you find a bug or run into any issues while using the package, please open an issue or contact one of the developers.

How to cite

Eckhardt, P., Ernst, K., Fleischmann, T., Geßler, A., Schnickmann, K., Thurner, L., and Wagner, G. "search-query: An Open-Source Python Library for Academic Search Queries".

The package was developed as part of Bachelor's theses:

  • Fleischmann, T. (2025). Advances in literature search queries: Validation and translation of search strings for EBSCOHost. Otto-Friedrich-University of Bamberg.
  • Geßler, A. (2025). Design of an Emulator for API-based Academic Literature Searches. Otto-Friedrich-University of Bamberg.
  • Schnickmann, K. (2025). Validating and Parsing Academic Search Queries: A Design Science Approach. Otto-Friedrich-University of Bamberg.
  • Eckhardt, P. (2025). Advances in literature searches: Evaluation, analysis, and improvement of Web of Science queries. Otto-Friedrich-University of Bamberg.
  • Ernst, K. (2024). Towards more efficient literature search: Design of an open source query translator. Otto-Friedrich-University of Bamberg.

Not what you are looking for?

This Python package was developed with the purpose of integrating it into other literature management tools. If that isn't your use case, it might be useful for you to look at these related tools:

License

This project is distributed under the MIT License.

Owner

  • Name: CoLRev-Environment
  • Login: CoLRev-Environment
  • Kind: organization

JOSS Publication

search-query: An open source Python library for academic search queries
Published
February 19, 2026
DOI
Volume 11, Issue 118, Page 8775
Authors
Peter Eckhardt ORCID
Otto-Friedrich-Universität Bamberg
Katharina Ernst ORCID
Otto-Friedrich-Universität Bamberg
Thomas Fleischmann ORCID
Otto-Friedrich-Universität Bamberg
Anna Geßler ORCID
Otto-Friedrich-Universität Bamberg
Karl Schnickmann ORCID
Otto-Friedrich-Universität Bamberg
Laureen Thurner ORCID
Otto-Friedrich-Universität Bamberg
Gerit Wagner ORCID
Frankfurt School of Finance & Management
Editor
Claudia Solis-Lemus ORCID
Tags
Search query Literature search Literature review Meta-analysis
View PDF Review Thread Software Archive

GitHub Events

Total
  • Create event: 27
  • Release event: 2
  • Issues event: 18
  • Watch event: 1
  • Delete event: 27
  • Member event: 1
  • Issue comment event: 22
  • Push event: 247
  • Pull request review comment event: 1
  • Pull request event: 57
  • Fork event: 5
Last Year
  • Create event: 27
  • Release event: 2
  • Issues event: 18
  • Watch event: 1
  • Delete event: 27
  • Member event: 1
  • Issue comment event: 22
  • Push event: 247
  • Pull request review comment event: 1
  • Pull request event: 57
  • Fork event: 5

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 13
  • Total pull requests: 36
  • Average time to close issues: 9 days
  • Average time to close pull requests: 13 days
  • Total issue authors: 3
  • Total pull request authors: 5
  • Average comments per issue: 0.62
  • Average comments per pull request: 0.31
  • Merged pull requests: 10
  • Bot issues: 0
  • Bot pull requests: 15
Past Year
  • Issues: 13
  • Pull requests: 28
  • Average time to close issues: 9 days
  • Average time to close pull requests: 9 days
  • Issue authors: 3
  • Pull request authors: 5
  • Average comments per issue: 0.62
  • Average comments per pull request: 0.39
  • Merged pull requests: 8
  • Bot issues: 0
  • Bot pull requests: 7
View more stats
Top Authors
Issue Authors
  • geritwagner (6)
  • amcandio (6)
  • Peteer98 (1)
Pull Request Authors
  • github-actions[bot] (17)
  • geritwagner (13)
  • k-schnickmann (5)
  • ThomasFleischmann (2)
  • Peteer98 (1)
Top Labels
Issue Labels
codex (1)
Pull Request Labels
codex (1)

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 5,747 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 4
  • Total maintainers: 1
pypi.org: search-query

Package for managing literature search queries.

  • Versions: 4
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 5,747 Last month
Rankings
Dependent packages count: 7.3%
Average: 37.9%
Dependent repos count: 68.6%
Maintainers (1)
geritwagner
Last synced: 6 months ago

Dependencies

.github/workflows/publish.yml actions
  • actions/checkout v3 composite
.github/workflows/poetry_update.yml actions
  • actions/checkout v3 composite
  • repo-sync/pull-request v2 composite
pyproject.toml pypi
  • pylint ^3.0.0 develop
  • pytest ^7.4.2 develop
  • python ^3.8
.github/workflows/tests.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
poetry.lock pypi
  • astroid 3.0.3
  • colorama 0.4.6
  • dill 0.3.8
  • exceptiongroup 1.2.1
  • iniconfig 2.0.0
  • isort 5.13.2
  • mccabe 0.7.0
  • packaging 24.0
  • platformdirs 4.2.1
  • pluggy 1.5.0
  • pylint 3.0.1
  • pytest 7.4.4
  • tomli 2.0.1
  • tomlkit 0.12.4
  • typing-extensions 4.11.0