pybliometrics.sciencedirect.ScienceDirectSearch

ScopusSearch() implements the ScienceDirect Search API. It executes a query to search for documents and retrieves the resulting records. Any query that works in the Advanced Document Search on sciencedirect.com will work. For a complete guide on how to query check the documentation.

Documentation

class pybliometrics.sciencedirect.ScienceDirectSearch(query, refresh=False, view=None, verbose=False, download=True, integrity_fields=None, integrity_action='raise', subscriber=True, **kwds)[source]

Interaction with the ScienceDirect Search API. This represents a search against the ScienceDirect cluster, which contains serial/nonserial full-text articles. Note that this API replicates the search experience on ScienceDirect.

Parameters:

  • query (str) – A string of the query as used in the ScienceDirect Search.

  • refresh (bool | int, optional) – Whether to refresh the cached file if it exists or not. If int is passed, cached file will be refreshed if the number of days since last modification exceeds that value.

    Default: False

  • view (str | None, optional) – Which view to use for the query, see the documentation. Allowed values: STANDARD.

    Default: None

  • verbose (bool, optional) – Whether to print a download progress bar.

    Default: False

  • download (bool, optional) – Whether to download results (if they have not been cached).

    Default: True

  • integrity_fields (list[str] | tuple[str, ...] | None, optional) – A list or tuple with the names of fields whose completeness should be checked. ArticleMetadata will perform the action specified in integrity_action if elements in these fields are missing. This helps to avoid idiosynchratically missing elements that should always be present (e.g., doi or authors).

    Default: None

  • integrity_action (str, optional) – What to do in case integrity of provided fields cannot be verified. Possible actions: - “raise”: Raise an AttributeError - “warn”: Raise a UserWarning

    Default: 'raise'

  • subscriber (bool, optional) – Whether you access ScienceDirect with a subscription or not. For subscribers, ScienceDirect’s cursor navigation will be used. Sets the number of entries in each query iteration to the maximum number allowed by the corresponding view.

    Default: True

  • kwds (str) – Keywords passed on as query parameters. Must contain fields and values mentioned in the API specification.

Raises:

  • ScopusQueryError – For non-subscribers, if the number of search results exceeds 5000.

  • ValueError – If any of the parameters integrity_action, refresh or view is not one of the allowed values.

Notes

The directory for cached results is {path}/{view}/{fname}, where path is specified in your configuration file and fname is the md5-hashed version of query.

The ScienceDirect Search API V2 has two available interfaces: PUT and GET. This library uses the GET interface.

property results: list[Document] | None

A list of namedtuples in the form (authors first_author doi title link load_date openaccess_status pii coverDate endingPage publicationName startingPage api_link volume).

Field definitions correspond to the ScienceDirect Search Views and return the values as-is, except for authors which are joined on “;”.

Raises:

ValueError – If the elements provided in integrity_fields do not match the actual field names (listed above).

Notes

The list of authors and the list of affiliations per author are deduplicated.

get_dois()[source]

DOIs of retrieved documents.

get_cache_file_age()

Return the age of the cached file in days.

Return type:

int

get_cache_file_mdate()

Return the modification date of the cached file.

Return type:

str

get_key_remaining_quota()

Return number of remaining requests for the current key and the current API (relative on last actual request).

Return type:

str | None

get_key_reset_time()

Return time when current key is reset (relative on last actual request).

Return type:

str | None

get_results_size()

Return the number of results (works even if download=False).

Return type:

int

Examples

The class is initialized with a search query. To see the download progress, set verbose=True.

>>> from pybliometrics.sciencedirect import ScienceDirectSearch, init
>>> init()
>>> # Retrieve documents based on the search query
>>> sds = ScienceDirectSearch('"neural radiance fields" AND "3D" AND YEAR(2024)', verbose=True)
Downloading results for query ""neural radiance fields" AND "3D" AND YEAR(2024)":
100%|██████████| 8/8 [00:05<00:00,  1.39it/s]

To access the results, use the attribute results which contains a list of Document namedtuples.

>>> # Access the results
>>> results = sds.results
[Document(authors='Dong He;Wenhua Qian;Jinde Cao', first_author='Dong He', doi='10.1016/j.cag.2025.104181', title='GEAST-RF: Geometry Enhanced 3D Arbitrary Style Transfer Via Neural Radiance Fields', link='https://www.sciencedirect.com/science/article/pii/S0097849325000202?dgcid=api_sd_search-api-endpoint', load_date='2025-02-16T00:00:00.000Z', openaccess_status=False, pii='S0097849325000202', coverDate='2025-02-16', endingPage=None, publicationName='Computers & Graphics', startingPage='104181', api_link='https://api.elsevier.com/content/article/pii/S0097849325000202', volume=None),
 Document(authors='Qicheng Xu;Min Hu;Xitao Zhang', first_author='Qicheng Xu', doi='10.1016/j.asr.2025.01.065', title='A neural radiance fields method for 3D reconstruction of space target', link='https://www.sciencedirect.com/science/article/pii/S0273117725000973?dgcid=api_sd_search-api-endpoint', load_date='2025-02-01T00:00:00.000Z', openaccess_status=False, pii='S0273117725000973', coverDate='2025-02-01', endingPage=None, publicationName='Advances in Space Research', startingPage=None, api_link='https://api.elsevier.com/content/article/pii/S0273117725000973', volume=None),
 Document(authors='Jian Liu;Zhen Yu', first_author='Jian Liu', doi='10.1016/j.neucom.2025.129420', title='SA3D-L: A lightweight model for 3D object segmentation using neural radiance fields', link='https://www.sciencedirect.com/science/article/pii/S092523122500092X?dgcid=api_sd_search-api-endpoint', load_date='2025-01-14T00:00:00.000Z', openaccess_status=False, pii='S092523122500092X', coverDate='2025-03-28', endingPage=None, publicationName='Neurocomputing', startingPage='129420', api_link='https://api.elsevier.com/content/article/pii/S092523122500092X', volume='623'),
 ...]

The list of results can be cast into a Pandas DataFrame.

>>> import pandas as pd
>>> # Cast results to a pandas DataFrame
>>> df = pd.DataFrame(sds.results)
>>> # Display available fields
>>> df.columns
Index(['eid', 'filename', 'height', 'mimetype', 'ref', 'size', 'type', 'url',
   'width'],
  dtype='object')
>>> # Get shape of the DataFrame (rows x columns)
(200, 14)
>>> # Display the first 3 rows
>>> df.head(3)
authors first_author doi title link load_date openaccess_status pii coverDate endingPage publicationName startingPage api_link volume
0 Dong He;Wenhua Qian;Jinde Cao Dong He 10.1016/j.cag.2025.104181 GEAST-RF: Geometry Enhanced 3D Arbitrary Style... https://www.sciencedirect.com/science/article/... 2025-02-16T00:00:00.000Z False S0097849325000202 2025-02-16 None Computers & Graphics 104181 https://api.elsevier.com/content/article/pii/S... None
1 Qicheng Xu;Min Hu;Xitao Zhang Qicheng Xu 10.1016/j.asr.2025.01.065 A neural radiance fields method for 3D reconst... https://www.sciencedirect.com/science/article/... 2025-02-01T00:00:00.000Z False S0273117725000973 2025-02-01 None Advances in Space Research None https://api.elsevier.com/content/article/pii/S... None
2 Jian Liu;Zhen Yu Jian Liu 10.1016/j.neucom.2025.129420 SA3D-L: A lightweight model for 3D object segm... https://www.sciencedirect.com/science/article/... 2025-01-14T00:00:00.000Z False S092523122500092X 2025-03-28 None Neurocomputing 129420 https://api.elsevier.com/content/article/pii/S... 623