adsfolio.api.search

Search API wrapper for ADS.

Provides access to: - /search/query - Standard search - /search/qtree - Query parsing - /search/bigquery - Bulk bibcode search

class adsfolio.api.search.SearchAPI(client)[source]

Bases: object

Search API for querying ADS.

Examples

>>> api = SearchAPI(client)
>>> results = api.query("author:Einstein", fl=["bibcode", "title"], rows=10)
>>> for doc in results:
...     print(doc["bibcode"], doc["title"])

Parameters:: client (BaseClient)

FIELDS: ClassVar[list[str]] = ['abstract', 'ack', 'aff', 'alternate_bibcode', 'alternate_title', 'arxiv_class', 'author', 'bibcode', 'bibgroup', 'bibstem', 'citation_count', 'copyright', 'data', 'date', 'database', 'doi', 'doctype', 'first_author', 'grant', 'id', 'identifier', 'indexstamp', 'issue', 'keyword', 'orcid_pub', 'orcid_user', 'orcid_other', 'page', 'property', 'pub', 'pubdate', 'read_count', 'title', 'vizier', 'volume', 'year']

bigquery(bibcodes, fl=None, rows=None)[source]

Search by a list of bibcodes (max 2000).

Parameters:

bibcodes (list[str]) – List of bibcodes to retrieve.
fl (list[str], optional) – Fields to return.
rows (int, optional) – Number of results. Default: len(bibcodes).

Returns:

Search results for requested bibcodes.

Return type:

SearchResult

qtree(q)[source]

Parse a query and return its Abstract Syntax Tree.

Useful for understanding how queries are interpreted.

Parameters:: q (str) – Query string to parse.
Returns:: Query tree structure.
Return type:: dict

query(q, fl=None, rows=10, start=0, sort=None, fq=None)[source]

Search the ADS database.

Parameters:

q (str) – Search query string (Solr syntax).
fl (list[str], optional) – Fields to return. Default: [“bibcode”, “title”, “author”, “year”].
rows (int, optional) – Number of results to return. Default: 10, max: 2000.
start (int, optional) – Starting index for pagination. Default: 0.
sort (str, optional) – Sort order, e.g., “citation_count desc” or “date asc”.
fq (str, optional) – Filter query to narrow results.

Returns:

Search results with docs and metadata.

Return type:

SearchResult

Examples

>>> results = api.query("author:Einstein year:1905", rows=5)
>>> results = api.query("black holes", fq="database:astronomy",
...                     sort="citation_count desc")

query_all(q, fl=None, page_size=2000, sort=None, fq=None, max_records=None)[source]

Search all pages and return aggregated results.

Parameters:

q (str) – Search query string (Solr syntax).
fl (list[str], optional) – Fields to return.
page_size (int, optional) – Number of records per request. Default: 2000 (ADS max).
sort (str, optional) – Sort order.
fq (str, optional) – Filter query.
max_records (int, optional) – Maximum number of docs to collect. If None, collect all.

Returns:

Aggregated search result from all fetched pages.

Return type:

SearchResult

class adsfolio.api.search.SearchResult(num_found, start, docs, query_time=None)[source]

Bases: object

Container for search results.

Parameters:

num_found (int)
start (int)
docs (list[dict])
query_time (int | None)

property bibcodes: list[str][source]: Extract bibcodes from results.

docs: list[dict]: List of document records.

classmethod from_response(response)[source]

Create SearchResult from API response.

Parameters:: response (dict)
Return type:: adsfolio.api.search.SearchResult

num_found: int: Total number of matching documents.

query_time: int | None = None: Query execution time in ms.

start: int: Starting index of returned results.

adsfolio.api.search.escape_query_phrase(value)[source]

Escape a value interpolated inside an ADS quoted query phrase.

Parameters:: value (str)
Return type:: str