AffiliationRetrieval() implements the Affiliation Retrieval API. It provides basic information on registered affiliations, like city, country, its members, and more.

Table of Contents


class pybliometrics.scopus.AffiliationRetrieval(aff_id, refresh=False, view='STANDARD', **kwds)[source]

Interaction with the Affiliation Retrieval API.

  • aff_id (Union[int, str]) – Scopus ID or EID of the affiliation profile.

  • 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

  • view (str, optional) – The view of the file that should be downloaded. Allowed values: LIGHT, STANDARD, where STANDARD includes all information of the LIGHT view. For details see Note: Neither the BASIC view nor DOCUMENTS or AUTHORS views are active, although documented.

    Default: 'STANDARD'

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


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

Return type



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

property address

The address of the affiliation.

property affiliation_name

The name of the affiliation.

property author_count

Number of authors associated with the affiliation.

property city

The city of the affiliation.

property country

The country of the affiliation.

property date_created

Date the Scopus record was created.

property document_count

Number of documents for the affiliation.

property eid

The EID of the affiliation.

property identifier

The Scopus ID of the affiliation.

property name_variants

A list of namedtuples representing variants of the affiliation name with number of documents referring to this variant.

property org_domain

Internet domain of the affiliation. Requires the STANDARD view.

property org_type

Type of the affiliation. Requires the STANDARD view and only present if profile is org profile.

property org_URL

Website of the affiliation. Requires the STANDARD view.

property postal_code

The postal code of the affiliation. Requires the STANDARD view.

Link to the Scopus web view of the affiliation.

Link to the affiliation’s API page.

URL to the API page listing documents of the affiliation.

property state

The state (country’s administrative sububunit) of the affiliation. Requires the STANDARD view.

property sort_name

The name of the affiliation used for sorting. Requires the STANDARD view.

property url

URL to the affiliation’s API page.


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 Scopus’ Affiliation ID:

>>> from pybliometrics.scopus import AffiliationRetrieval
>>> aff = AffiliationRetrieval(60000356)

You can obtain basic information just by printing the object:

>>> print(aff)
University of Cape Town in Cape Town in South Africa,
has 13,033 associated author(s) and 75,695 associated document(s) as of 2021-07-12

The object has a number of attributes but no methods. For example, information regarding the affiliation itself:

>>> aff.affiliation_name
'University of Cape Town'
>>> aff.sort_name
'Cape Town, University of'
>>> aff.org_type
>>> aff.postal_code
'Cape Town'
>>> aff.state
'Western Cape'
'South Africa'
>>> aff.org_domain
>>> aff.org_URL

There are meta information, too:

>>> aff.author_count
>>> aff.document_count

Scopus also collects information on different names affiliated authors use for this affiliation, which pybliometrics returns as list of namedtuples:

>>> aff.name_variants
[Variant(name='University Of Cape Town', doc_count=60095),
 Variant(name='Univ. Cape Town', doc_count=1659),
 Variant(name='Univ Of Cape Town', doc_count=772),
 Variant(name='Univ. Of Cape Town', doc_count=392)]

Using pandas you can easily turn this into a DataFrame:

>>> import pandas as pd
>>> print(pd.DataFrame(aff.name_variants))
                      name doc_count
0  University Of Cape Town     60095
1          Univ. Cape Town      1659
2        Univ Of Cape Town       772
3       Univ. Of Cape Town       392

More on different types of affiliations in section tips.

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 aff.get_cache_file_mdate() to get the date of last modification, and aff.get_cache_file_age() the number of days since the last modification.