vidIQ Score Collector

Automate YouTube searches with the vidIQ browser extension to export the "overall score" for a list of keywords.

Prerequisites

• Python 3.9 or newer (3.13 tested)
• pip install -r requirements.txt
• Download Playwright browsers once: playwright install chromium
• Installed vidIQ Chrome extension (public version)

Info: Playwright must launch Chromium with the vidIQ extension enabled. The script needs the unpacked extension folder and a dedicated browser profile directory so you stay signed in to vidIQ.

Gather Inputs

1. Locate the vidIQ extension directory
   • In Chrome, open chrome://extensions/, enable Developer mode, find vidIQ, and copy the Extension ID (example: pachckjkecffpdphbpmfolblodfkgbhl).
   • Open File Explorer and browse to %LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions\<extension-id>.
   • Each subfolder is a version number (for example 6.0.9.1234). Use the most recent version folder. That folder must contain manifest.json and the rest of the extension files. Pass this full folder path to the script via --extension-dir.
   • Optional but recommended: copy that version folder somewhere stable (for example VidIQ_Score/extension/) so Chrome updates do not change the path. Point --extension-dir to the copied folder.
   • If you use Edge or another Chromium browser, the path is similar: %LOCALAPPDATA%\Microsoft\Edge\User Data\Default\Extensions\<extension-id>.
2. Prepare keywords
   • Create a text file with one keyword per line, for example data/keywords.txt.
   • You can also pass keywords directly on the command line with repeated --keyword flags.

Run and Confirm vidIQ Overlay

Run the script once with a small keyword list to make sure the vidIQ overlay appears inside the automated browser window:

python scripts/collect_vidiq_scores.py \
  --keywords-file data/keywords.txt \
  --extension-dir "C:\\Users\\cheng\\OneDrive - University of Calgary\\Coding Projects\\VidIQ_Score\\extension" \
  --user-data-dir profiles/vidiq-browser \
  --browser-channel chrome \
  --pause-for-login \
  --post-navigation-wait-ms 4000

Steps during the first run:

• A Chromium window opens using the profile directory you provided.
• Because --pause-for-login is set, the script waits on https://www.youtube.com until you press Enter in the terminal.
• Sign in to YouTube if prompted and confirm the vidIQ panel appears on the search results page. Perform any vidIQ login steps so the score widget becomes visible.
• Return to the terminal, press Enter, and the script will start processing each keyword.
• Watch the terminal output for lines like -> Overall score: 62. If you see missing or timeout, the overlay was not detected; keep the browser open, ensure vidIQ is active, then rerun.

Useful Flags

• --json-output runs/results.json writes JSON in addition to the default CSV (vidiq_scores.csv).
• --screenshot-dir runs/screens captures a full-page screenshot whenever the score is missing or an error occurs.
• --delay-between-ms 3000 controls the wait between searches (default 1500 ms).
• --max-wait-ms 15000 increases the time allowed for the vidIQ widget to render per keyword.

The CSV now keeps only the keyword and overall score from the original export and adds the headline vidIQ metrics that appear in the sidebar (volume score, competition, highest views, average views/subscribers, added last 7 days, closed captions count, average age, title/description usage counts, and top creator). Status and notes columns remain so you can spot missing data quickly.

Tips

• Do not run with --headless; Chrome extensions usually fail to load without a visible window.
• If Google shows "This browser or app may not be secure", rerun with --browser-channel chrome (or --browser-channel msedge) so Playwright launches an installed browser that Google trusts.
• The script already hides the navigator.webdriver flag. If you want to inject extra Chromium flags, use the repeatable --chromium-arg option: --chromium-arg="--disable-features=OptimizationHints".
• Add --verbose to print the raw vidIQ widget text whenever parsing fails; helpful for spotting UI changes.
• You can use environment variables in paths (for example --extension-dir "%LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions\..."); the script expands them automatically.
• Keep the same --user-data-dir between runs so you stay authenticated in vidIQ. Delete the directory to reset the profile if needed.
• If scores are missing, confirm the vidIQ overlay appears when you search manually in the opened browser, then re-run the script or increase --max-wait-ms.
• Use smaller keyword batches to avoid triggering anti-bot measures from YouTube.