PlumXMetrics() implements the PlumX Metrics API. It provides metrics in five categories: captures, citations, usage, mentions, and social media (background information). It works for 33 different types of media.

Table of Contents


class pybliometrics.scopus.PlumXMetrics(identifier, id_type, refresh=False)[source]

Interaction with the PlumX Metrics API.

  • identifier (str) – The identifier of a document.

  • id_type (str) – The type of used ID. Allowed values are: - ‘airitiDocId’ - ‘arxivId’ - ‘cabiAbstractId’ - ‘citeulikeId’ - ‘digitalMeasuresArtifactId’ - ‘doi’ - ‘elsevierId’ - ‘elsevierPii’ - ‘facebookCountUrlId’ - ‘figshareArticleId’ - ‘githubRepoId’ - ‘isbn’ - ‘lccn’ - ‘medwaveId’ - ‘nctId’ - ‘oclc’ - ‘pittEprintDscholarId’ - ‘pmcid’ - ‘pmid’ - ‘redditId’ - ‘repecHandle’ - ‘repoUrl’ - ‘scieloId’ - ‘sdEid’ - ‘slideshareUrlId’ - ‘smithsonianPddrId’ - ‘soundcloudTrackId’ - ‘ssrnId’ - ‘urlId’ - ‘usPatentApplicationId’ - ‘usPatentPublicationId’ - ‘vimeoVideoId’ - ‘youtubeVideoId’

  • refresh (Union[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


ValueError – If the parameter refresh is not one of the allowed values.

Return type



The directory for cached results is {path}/ENHANCED/{identifier}, where path is specified in your configuration file.

property category_totals

A list of namedtuples representing total metrics as categorized by PlumX Metrics in the form (capture, citation, mention, socialMedia, usage).

Note: For Citation category a maximum citation count across sources is shown. For details on PlumX Metrics categories see

property capture

A list of namedtuples representing metrics in the Captures category.

Note: For details on Capture metrics see

property citation

A list of namedtuples representing citation counts from different sources.

Note: For details on Citation metrics see

property mention

A list of namedtuples representing metrics in Mentions category.

Note: For details on Mention metrics see

property social_media

A list of namedtuples representing social media metrics.

Note: For details on Social Media metrics see

property usage

A list of namedtuples representing Usage category metrics.

Note: For details on Usage metrics see


Return the age of the cached file in days.

Return type



Return the modification date of the cached file.

Return type



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

Return type



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

Return type



You initialize the class with the identifier of a document and its type:

>>> from pybliometrics.scopus import PlumXMetrics
>>> plum = PlumXMetrics("10.1016/j.softx.2019.100263", id_type='doi')

You can obtain basic information just by printing the object:

>>> print(plum)
Document with doi 10.1016/j.softx.2019.100263 received:
- 104 citation(s) in category 'capture'
- 7 citation(s) in category 'citation'
- 1 citation(s) in category 'mention'
- 42 citation(s) in category 'socialMedia'
- 4 citation(s) in category 'usage'
as of 2021-01-04

To each of the five categories, there is one property storing number and origin of the metrics in namedtuples. If in a category there are no entries the property is simply None:

>>> >>> plum.capture
[Metric(name='READER_COUNT', total=93),
 Metric(name='WATCHER_COUNT', total=7),
 Metric(name='FORK_COUNT', total=4)]
>>> plum.citation
[Metric(name='Scopus', total=7)]
>>> plum.mention
[Metric(name='ALL_BLOG_COUNT', total=1)]
>>> plum.social_media
[Metric(name='TWEET_COUNT', total=42)]
>>> plum.usage
[Metric(name='LINK_OUTS', total=3),
 Metric(name='ABSTRACT_VIEWS', total=1)]

Finally there is a property to total all metrics on an aggregated level:

>>> plum.category_totals
[Category(name='capture', total=104),
 Category(name='citation', total=7),
 Category(name='mention', total=1),
 Category(name='socialMedia', total=42),
 Category(name='usage', total=4)]

There are no bibliometric information such as title or author.

Downloaded results are cached to speed up subsequent analysis. This information may become outdated. To refresh the cached results if they exist, set refresh=True, or provide an integer that will be interpreted as maximum allowed number of days since the last modification date. For example, if you want to refresh all cached results older than 100 days, set refresh=100. Use source.get_cache_file_mdate() to get the date of last modification, and source.get_cache_file_age() the number of days since the last modification.