CitationMap plots your Google Scholar citations on a world map

A one line install and a four line script

The design goal is stated bluntly in the README: there is no need to clone or fork the repository unless you want custom changes, and the tool takes one line to install and four lines to run. The package is on PyPI under the name citation-map.

pip install citation-map

To take the newest release instead of the one pip resolves by default, the README gives the upgrade form pip install citation-map --upgrade. Then a small script with your own Google Scholar ID in place of the author's.

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)

That is the whole interface, one function with one argument. The package metadata shows the dependency set, which is where the real shape of the tool appears: scholarly for the Scholar side, selenium for driving a browser, folium for the map, geopy and pycountry for turning affiliation strings into coordinates and country names, bs4 for parsing, pandas for the tabular output, and tqdm for progress bars. The classifier in setup.py marks the package as Development Status 3 - Alpha, and the version there is 5.0.

Chrome and a CAPTCHA window are part of the workflow

The runtime requirements are not optional extras. The README states that a properly installed Chrome browser is required to run this successfully, since CAPTCHA checks will be redirected to a pop-up Chrome browser. That is the mechanism in one sentence: the tool drives a real browser, and when Google Scholar asks whether a human is present, a Chrome window appears and the person has to answer it. The Selenium dependency is what makes that possible, and the same browser session is presumably what carries the Scholar session cookies that make the scraping possible at all. It also means the tool is interactive in a way most Python packages are not. There is no batch mode described, no headless flag documented, and no way in the README to say that a run is unattended. For a researcher who wants a map once, that is a small cost. For a scheduled job that refreshes a map every month, it is a structural problem, and the README gives no answer to it.

What comes out: an HTML map and a CSV of affiliations

The expected outcome is an HTML file as the output of the script, which you open in a browser to see your own version of the citation world map, with the map image the author generated stored in the assets directory of the repository as the reference. Alongside the map there is a CSV file recording citation information, and the README lists the fields: citing author, citing paper, cited paper, affiliation and detailed location. So the tool produces two things with two different uses. The HTML is the shareable artifact, the picture you put on a slide or a personal page. The CSV is the working artifact, the thing you filter and pivot when you want to know which countries cite you or which institutions are the largest source of citations. The CSV is the more valuable of the two in practice, and it is worth noting that the tool's real analysis happens in that table rather than in the map, since the map is a rendering of a result you could also produce with any mapping library once you have the rows.

The precision and recall trade off is explicit

The most useful documentation in the README concerns a single option, affiliation_conservative, and the reasoning behind it is careful enough to quote the structure of the argument. If it is set to True, the tool uses the Google Scholar verified official organization name from the citing authors, which the README describes as a very conservative approach, because the author needs to self-report it in the affiliation panel, the author needs to verify it with the matching email address, and the organization needs to be recorded by Google Scholar. The example given is that Meta, the company, is not in the list, which is the point: the conservative mode returns verified academic and institutional names, not the large employers that show up in self-reported affiliation strings. The result is much higher precision and lower recall. The credit for the discussion goes to Zhijian Liu in an issue on the repository, which is a good sign about how the project handles design disagreements. The trade off is that the default mode gives you the broad picture with some noise, and the conservative mode gives you fewer, more reliable rows, and the choice is a parameter rather than a fork.

The scraper is the weak point, and the author says so

The README carries two admissions that any evaluation has to take seriously. The first is that the author is no longer able to run CitationMap for users who run into problems, for personal reasons, with an apology attached. The second is more technical: the author was told that recently Google Scholar has updated the traffic-blocking and made CitationMap much less reliable than before, with pull requests to fix the issue explicitly welcomed. The News section adds the author's own diagnosis of the difficulty, which is that this is a first attempt at dealing with web scraping and crawling, that users have reported stability issues, and that the suspected major problems are being caught by CAPTCHA or robot check and being flagged for blacklist by Google Scholar. A release note from Oct 14, 2025 records version 5.0 with better handling of CAPTCHA, and an earlier note from Aug 2, 2024 records version 4.0 with the logic update that introduced affiliation_conservative. The pattern is clear. This is a scraper of a site that actively defends against scrapers, and the defence is winning. The repository is not archived and the last push was on 2026-06-15, so the code is still being touched, but the fragility is in the target rather than in the code.

What the tool gets wrong on purpose

The disclaimer is unusually honest and should be read before anyone uses the output. The README says it is reasonable for this tool to make some minor mistakes: missing a few citing authors, dropping a couple of pins in wrong locations. Then it names the alternative for anyone who cares a lot about ensuring all citing authors' affiliations are included and accurately marked, which is to annotate manually on Google My Maps, and it says the tool is meant to help people who cannot tolerate that painful process, especially when they have a decent number of citations. So the position is a deliberate one. The tool trades accuracy for coverage, and the recommended alternative is manual work for the accuracy minded. A second limitation follows from the architecture. Because the affiliations are recovered from the citing authors' own affiliation strings and then geocoded, the map is a picture of what people said about themselves, and a student who typed a different city than their institution will place a pin in the wrong country. A third is that the tool reads a public profile, so it inherits the visibility rules of Google Scholar, where an author who has not made their profile public will not appear as a citing author even when they cite you.

How this differs from doing it yourself or using a reference manager

Three alternatives exist, and they differ in where the work goes. Writing your own scraper against the Scholar pages gives you full control over the session handling, the retry logic and the parsing, and it costs you the weeks of debugging that the author already did, plus the ongoing maintenance as Google changes its markup. A commercial citation analytics service gives you the same geographic view with support behind it and a data pipeline, at the cost of a subscription and of uploading your profile to a third party. A reference manager gives you a local, complete bibliography with export formats and notes, and no map at all, so if your actual question is which papers cite you rather than where those authors are, a reference manager answers it better and CitationMap adds an unnecessary scraping step. The case for CitationMap is narrow and specific. It is the fastest path from a scholar ID to a picture and a table, for someone who wants to see the shape of their readership and is content with an approximate answer.

Licensing: non commercial, and the metadata is inconsistent

The licence needs a note. The README badges and the setup.py metadata both state CC BY-NC-SA 4.0, with the non commercial clause in the name, and the setup.py license field reads CC BY-NC-SA, and the package is classified as License :: Other/Proprietary License. The repository metadata on the other hand lists the licence as a custom one that GitHub cannot classify, with a LICENSE.md file at the root, so the authoritative text is the file in the repository rather than the badge. In practical terms, a CC BY-NC-SA 4.0 licence lets you share and adapt the work, including the generated maps, provided you attribute the author, do not use it commercially, and license adaptations the same way. That last clause is the one people trip over, since a derivative map published inside a commercial product or a company page inherits the non commercial and share alike terms. Your own legal review should settle how that applies to a map you generated rather than the code itself, and the safest practical path is to check LICENSE.md and cite the tool as the README asks, with the BibTeX, MLA, APA and Chicago forms given for the Authorea preprint of 2024.

Editorial conclusion

CitationMap suits an academic who wants a geographic picture of their citing authors in a minute, and who accepts an approximate answer and a Chrome window opening during the run, because the one line install and the four line script deliver the map and the CSV without any setup. It is the wrong tool if you need exact affiliation data, since the README itself points to manual annotation for that, and it is a poor fit for unattended or repeated runs now that Google Scholar blocks traffic harder and the author states they can no longer run the tool for users. Before you rely on it, install it with pip install citation-map, run it once on your own scholar ID with Chrome open, and check the CSV for missing citing authors, because the README says missing authors and misplaced pins are expected.

Frequently asked questions

Official sources

1. ChenLiu-1996/CitationMap on GitHub
2. Issues
3. Project website
4. README