Automate

Search-query can be used to automate different steps of the search process, such as searching for records in an API, storing the results, and creating a search file.

To run API searches, it is often necessary to represent a query in the form of a URL as opposed to a query string. Using the Crossref API as an example, the following illustrates how to construct such a URL to retrieve and store records.

Tip

The example below requires the colrev package to be installed. You can install it via pip:

pip install colrev==0.16.1

Important: colrev version 0.16.1 requires Python 3.10 or higher. If you’re on a different Python version, create a Python 3.10 environment (e.g., via uv, venv, or conda) before installing.

 1import datetime
 2from pathlib import Path
 3from colrev.packages.crossref.src import crossref_api
 4from colrev.writer.write_utils import write_file
 5
 6from search_query.constants import Fields, Operators
 7from search_query.query_or import OrQuery
 8from search_query.search_file import SearchFile
 9
10def to_crossref_url(query):
11    """Translate query into a Crossref-compatible URL."""
12    if query.value != Operators.OR:
13        raise ValueError("Crossref serializer only supports OR queries.")
14
15    query_parts = []
16    for child in query.children:
17        if child.operator:
18            raise ValueError("Nested operators are not supported in Crossref serializer.")
19        if child.field.value != Fields.TITLE:
20            raise ValueError(f"Only title field is supported in Crossref serializer ({child.field})")
21        query_parts.append(child.value.strip())
22
23    # Crossref uses '+' for spaces in query values
24    query_string = "+".join(query_parts)
25    return f"https://api.crossref.org/works?query.title={query_string}"
26
27if __name__ == "__main__":
28
29    query = OrQuery(["microsourcing", "lululemon"], field="title")
30
31    url = to_crossref_url(query)
32    api_crossref = crossref_api.CrossrefAPI(url=url)
33    records = api_crossref.get_records()
34
35    sf = SearchFile(
36        search_string=query.to_string(),
37        platform="crossref",
38        authors=[{"name": "Gerit Wagner"}],
39        record_info={"source": "manual", "url": url},
40        date={"data_entry": datetime.datetime.now().strftime("%Y-%m-%d %H:%M")},
41        field="title",
42        description="Search for research on microsourcing"
43    )
44
45    sf.save("test/microsourcing_search.json")
46
47    records_dict = {record.get_value("doi"): record.get_data() for record in records}
48    write_file(records_dict=records_dict, filename=Path("test/crossref_records.bib"))