CitationMap

<h1 align="center"> &#127759; <code>CitationMap</code>: Google Scholar Citation World Map </h1> <p align="center"> <strong>CitationMap: A Python Tool to Identify and Visualize Your Google Scholar Citations Around the World</strong> [<a href="https://openreview.net/pdf?id=BqJgCgl1IA">PDF</a>] </p> <p align="center">English | <a href="README.zh.md">中文</a></p> <div align="center">

<br>

</div>

🏆 The world's first free tool to visualize your Google Scholar citations on a world map.

⭐ There is NO NEED to clone or fork this repo unless you want to make custom changes.

🚀 It only takes 1 line to install and 4 lines to run!

🌐 A properly installed Chrome browser is required to run this successfully, since CAPTCHA checks will be redirected to a pop-up Chrome browser.

👉 Due to personal reasons, I am no longer able to run CitationMap for you if you run into problems. Apologies.

<br>

I am Chen Liu, a Computer Science PhD Candidate at Yale University.

Purpose

This is a simple Python tool to generate an HTML citation world map from your Google Scholar ID.

It is easy to install (available on PyPI) and easy to use (see the User Guide).

Minimalistic User Guide

This is for users familiar with python. Otherwise, please read the User Guide.

Long story short: DO NOT CLONE OR FORK if you just want to use it! Just installing and running in a single pythin script is enough! Otherwise it will only make things complicated unless you know what you are doing.

🚀 1 line to install.

pip install citation-map

If you want to install the latest version, run pip install citation-map --upgrade.

🚀 4 lines to run.

Please copy and paste this to an empty .py file (name it something like run.py), replace my scholar ID with yours, and run it using python run.py.

from citation_map import generate_citation_map

if __name__ == '__main__':
    scholar_id = '3rDjnykAAAAJ'  # This is my Google Scholar ID. Replace this with your ID.
    generate_citation_map(scholar_id)

Expected Outcome

You will be given an HTML file as the output of the script.

If you open it on a browser, you will see your own version of the following citation world map.

<img src = "assets/citation_world_map.png" width=800>

Besides, there will be a CSV file recording citation information (citing author, citing paper, cited paper, affiliation, detailed location).

Disclaimer: It is reasonable for this tool to make some minor mistakes: missing a few citing authors, dropping a couple of pins in wrong locations, etc. If you care a lot about ensuring all citing authors' affiliations are included and accurately marked, you could try manually annotating on Google My Maps instead. This tool is meant to help people who cannot tolerate this painful process, especailly when they have a decent number of citations.

NOTE: Now you can trade off between affiliation precision and recall with the affiliation_conservative option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list. Many thanks to Zhijian Liu for the helpful discussion.

Citation

BibTeX

@article{citationmap,
  title={CitationMap: A Python Tool to Identify and Visualize Your Google Scholar Citations Around the World},
  author={Liu, Chen},
  journal={Authorea Preprints},
  year={2024},
  publisher={Authorea}
}

MLA

Liu, Chen. "CitationMap: A Python Tool to Identify and Visualize Your Google Scholar Citations Around the World." Authorea Preprints (2024).

APA

Liu, C. (2024). CitationMap: A Python Tool to Identify and Visualize Your Google Scholar Citations Around the World. Authorea Preprints.

Chicago

Liu, Chen. "CitationMap: A Python Tool to Identify and Visualize Your Google Scholar Citations Around the World." Authorea Preprints (2024).

News

[Asking for advice]

1. This is my first time dealing with webscraping/crawling. Users have reported stability issues, and I suspect the major problems are (1) being caught by CAPTCHA or robot check, and (2) being flagged for blacklist by Google Scholar. If you are experienced in these areas and have good advice, I would highly appreciate a GitHub issue or a pull request.

[Oct 14, 2025] Version 5.0 released >>> Better handling of CAPTCHA.

[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument affiliation_conservative. If set to True, we will use a very conservative approach to identify affiliations which leads to much higher precision and lower recall. Many thanks to Zhijian Liu for the helpful discussion.

[Jul 28, 2024] Version 3.10 released >>> Logic update. Tested on a professor's profile with 10,000 citations!

[Jul 27, 2024] Version 2.0 released >>> 10x speedup with multiprocessing (1 hour to 5 minutes for my profile).

[Jul 26, 2024] Version 1.0 released >>> First working version for my profile with 100 citations.

User Guide

0. If you are new to Python, you probably want to start with a distribution of Python that also helps with environment management (such as anaconda). Once you have set up your environment (for example, when you reach the stage of conda activate env39 in this tutorial), you can move on to the next step.

1. Install this tool by running the following line in your conda-accessible command line.

   pip install citation-map --upgrade
   

2. Find your Google Scholar ID.

   • Open your Google Scholar profile. The URL should take the form of https://scholar.google.com/citations?user=GOOGLE_SCHOLAR_ID. In this case, your Google Scholar ID is just the string GOOGLE_SCHOLAR_ID.
   • Please kindly ignore configuration strings such as &hl=en (host language is English) or &sortby=pubdate (sort the works by date of publication).
   • NOTE: If you have publications/patents that you manually added into the Google Scholar page, you might want to temporarily delete them while you run this tool. They might cause errors due to incompatibility.

3. In an empty Python script, run the following.

   • NOTE 1: Please DO NOT name your script citation_map.py which would cause circular import as this package itself shares the same name. Call it something else: e.g., run_citation_map.py, run.py, etc. See Issue #2.
   • NOTE 2: Protecting with if __name__ == '__main__' seems necessary to avoid multiprocessing problems, and it is a good practice anyways.

   from citation_map import generate_citation_map
   
   if __name__ == '__main__':
       # This is my Google Scholar ID. Replace this with your ID.
       scholar_id = '3rDjnykAAAAJ'
       generate_citation_map(scholar_id)
   

   Note that in Version 4.5, we support manual edit of the csv. You can run generate_citation_map first, and get the csv and HTML. Then, you can manually modify the csv content, and generate an updated HTML by running generate_citation_map again with parse_csv=True.

   Note that in Version 4.0, we will cache the results before identifying affiliations. So if you want to rerun the same author from scratch, you need to delete the cache (default location is 'cache').

   More input arguments are shown in the demo script.

   You can take a look at the input arguments (listed below) of the function generate_citation_map in case you need those functionalities.

   Parameters
   ----
   scholar_id: str
       Your Google Scholar ID.
   output_pa