Citation Impact Map Generator

Generate a colorful world map of institutions citing your Google Scholar publications.

This project is based on CitationMap by Chen Liu at Yale University, a pip-installable Python tool to generate an HTML citation world map from a Google Scholar ID.

Why we improved it

The original tool fails in several common scenarios:

• Google Scholar blocks datacenter IPs with a CAPTCHA wall, crashing the tool immediately on cloud servers
• scholarly is incompatible with httpx 0.28 and above, throwing a TypeError on startup in modern Python environments
• Chrome and ChromeDriver version mismatches cause SessionNotCreatedException before any data is fetched
• No resume support means any crash requires starting the entire affiliation-fetching stage over
• Institution names written as job titles cause geocoding to silently fail, leaving large gaps in the map

What we changed

• Affiliation fetching is replaced: the original uses scholarly with Selenium internally, which fails on datacenter IPs and breaks with httpx 0.28 and above. We bypass this by directly scraping Google Scholar pages via ScraperAPI
• Institution name cleaning is added before geocoding, stripping role prefixes like "PhD Student at..." that cause Nominatim to fail
• Resume support is added: affiliation fetching saves progress per author, so re-running picks up where it left off
• fix_geocode.py added for manually fixing remaining geocoding failures

Requirements

pip install citation-map scholarly requests beautifulsoup4 folium geopy
pip install "httpx==0.27.2"

httpx must be pinned to version 0.27.2. Version 0.28 removed the proxies argument from httpx.Client, which breaks scholarly's proxy setup.

You also need a ScraperAPI key. The free tier provides 5,000 requests per month.

🚀 Quick Start

# 1. Edit config.py with your Scholar ID and ScraperAPI key
# 2. Run each script in order:
python fetch_authors.py
python fetch_affiliations.py
python geocode.py
python fix_geocode.py
python generate_map.py
python export_csv.py
# Open citation_map.html in your browser

Scripts

fetch_authors.py

Fetches all papers that cite your work and all authors of those papers using the original citation_map package. Must be run locally and not on a cloud or datacenter IP, as Google Scholar will block those requests. Results are cached automatically and re-running loads from cache.

fetch_affiliations.py

Fetches each citing author's institution page via ScraperAPI. Re-running skips already-fetched authors and picks up where it left off. If you run out of API credits, register a new ScraperAPI account, update SCRAPER_API_KEY in config.py, and re-run.

geocode.py

Cleans institution names and geocodes them via Nominatim, which is free and requires no API key. Results are cached in geocode_cache.json.

Name cleaning examples:

• "PhD Student, Cornell University" becomes "Cornell University"
• "Associate Professor, MIT" becomes "MIT"
• "Research Scientist at Google" becomes "Google"
• "MIT | Stanford" becomes "MIT"

fix_geocode.py

Manually fixes remaining geocoding failures. Edit two dictionaries in the file.

Format 1: map a non-standard name to a searchable one

MANUAL_MAPPING = {
    "IEEE Fellow, Professor, Shanghai Jiao Tong University": "Shanghai Jiao Tong University",
    "MaiNLP lab @ LMU Munich":                              "Ludwig Maximilian University of Munich",
    "HUST PhD":                                             "Huazhong University of Science and Technology",
    "Yonsei Unviersity":                                    "Yonsei University",
}

Format 2: assign coordinates directly for companies or labs without a geocodable address

MANUAL_COORDS = {
    "Thinking Machines Lab":   [14.5995, 120.9842],
    "Meta Reality Labs":       [37.4845, -122.1477],
    "Microsoft Research Asia": [39.9042, 116.4074],
    "Data Scientist":          None,
    "Unknown affiliation":     None,
}

To find coordinates, search the institution on Google Maps, right-click the location, and copy the latitude and longitude numbers shown.

generate_map.py

Reads the cached data and produces citation_map.html. Open in any browser. Markers are clickable and show institution name and author list.

export_csv.py

Exports citation data to citation_info.csv with columns: citing author, affiliation, cleaned affiliation, latitude, longitude.

Configuration

Edit config.py before running:

SCHOLAR_ID — your Google Scholar ID, found in your profile URL

SCRAPER_API_KEY — your ScraperAPI key

TOTAL_INSTITUTIONS — total institution count shown in the map title

OUTPUT_HTML — output filename, default is citation_map.html

File Structure

config.py
fetch_authors.py
fetch_affiliations.py
geocode.py
fix_geocode.py
generate_map.py
export_csv.py
cache/
    YOUR_SCHOLAR_ID/
        all_citing_author_paper_tuple_list.pkl
        affiliation_progress.json
        affiliations_done.json
        geocode_cache.json
citation_map.html
citation_info.csv

Notes

Google Scholar blocks datacenter IPs including AWS and GCP. Run fetch_authors.py on your local machine.

ScraperAPI free tier provides 5,000 credits per month. Each author lookup costs 1 credit. If you have more than 5,000 citing authors, register additional accounts and swap the key in config.py.

Nominatim geocoding is rate-limited to 1 request per second. Around 400 institutions takes roughly 10 minutes.

Typical geocoding success rate is 85 to 90 percent of valid institutions. The remaining failures are usually job title descriptions with no institution name such as "Data Scientist" or "Independent Researcher", which cannot be geocoded.

Citation

If this tool helps your research, please consider citing or starring this repo.

@misc{chen2026citationmap,
  author = {Yuyan Chen},
  title = {Citation Impact Map Generator: An Improved Google Scholar Citation World Map Tool},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/Yukyin/CitationMapGenerator}
}

License

Noncommercial use is governed by LICENSE (PolyForm Noncommercial 1.0.0). Commercial use requires a separate agreement. See COMMERCIAL_LICENSE.md.

Commercial inquiries: yolandachen0313@gmail.com