ai-citation-map 0.1.0__tar.gz

ai_citation_map-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test-build-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build pytest
+      - run: pip install -e . && pytest -q
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

ai_citation_map-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CiteProof
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_citation_map-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: ai-citation-map
+Version: 0.1.0
+Summary: Rank the domains cited in AI answers (ChatGPT, Perplexity, Gemini) from a CSV.
+Project-URL: Homepage, https://github.com/citeproof/ai-citation-map
+Project-URL: Source, https://github.com/citeproof/ai-citation-map
+Project-URL: Related tools, https://citeproof.co/tools/ai-citation-checker?utm_source=pypi&utm_medium=parasite&utm_campaign=ai-citation-map
+Author-email: CiteProof <hello@citeproof.co>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aeo,ai search,chatgpt,citations,llm,perplexity,seo
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ai-citation-map
+
+Turn a CSV of URLs cited in AI answers (ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews) into a ranked list of domains: how often each is cited, on how many distinct questions, and by which engines.
+
+No dependencies. Python 3.8+.
+
+## Install
+
+```bash
+pip install ai-citation-map
+```
+
+## Use
+
+Input: one row per cited URL.
+
+```csv
+question,engine,cited_url
+best invoicing app for freelancers,chatgpt,https://www.g2.com/categories/invoicing
+best invoicing app for freelancers,perplexity,https://www.reddit.com/r/freelance/comments/abc
+best invoicing app for freelancers,gemini,https://zapier.com/blog/best-invoicing-software/
+```
+
+```bash
+ai-citation-map citations.csv --top 25 --csv-out map.csv
+```
+
+```
+domain                              cites questions  engines
+g2.com                                  1         1  chatgpt
+reddit.com                              1         1  perplexity
+zapier.com                              1         1  gemini
+```
+
+From Python:
+
+```python
+from ai_citation_map import build_map
+for d in build_map(rows):
+    print(d.domain, d.cites, len(d.questions), sorted(d.engines))
+```
+
+## Reading the output
+
+- Results are sorted by **distinct questions**, then citations: a domain cited once on each of eight questions matters more than one cited ten times on a single question.
+- Domains cited by every engine are the safest targets; ones cited by a single engine may come and go.
+- AI answers vary between runs and locations. Treat the map as a sample and re-run it with the same questions over time.
+
+## Collecting the input
+
+By hand (ask each question in each engine and log the cited links), or with CiteProof's free [AI citation checker](https://citeproof.co/tools/ai-citation-checker?utm_source=pypi&utm_medium=parasite&utm_campaign=ai-citation-map), which queries ChatGPT, Perplexity and Gemini and lists the domains each one cites.
+
+More templates (robots.txt rules for AI crawlers, llms.txt, JSON-LD): [citeproof/ai-visibility-toolkit](https://github.com/citeproof/ai-visibility-toolkit).
+
+MIT licensed. Maintained by [CiteProof](https://citeproof.co).

ai_citation_map-0.1.0/README.md

@@ -0,0 +1,55 @@
+# ai-citation-map
+
+Turn a CSV of URLs cited in AI answers (ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews) into a ranked list of domains: how often each is cited, on how many distinct questions, and by which engines.
+
+No dependencies. Python 3.8+.
+
+## Install
+
+```bash
+pip install ai-citation-map
+```
+
+## Use
+
+Input: one row per cited URL.
+
+```csv
+question,engine,cited_url
+best invoicing app for freelancers,chatgpt,https://www.g2.com/categories/invoicing
+best invoicing app for freelancers,perplexity,https://www.reddit.com/r/freelance/comments/abc
+best invoicing app for freelancers,gemini,https://zapier.com/blog/best-invoicing-software/
+```
+
+```bash
+ai-citation-map citations.csv --top 25 --csv-out map.csv
+```
+
+```
+domain                              cites questions  engines
+g2.com                                  1         1  chatgpt
+reddit.com                              1         1  perplexity
+zapier.com                              1         1  gemini
+```
+
+From Python:
+
+```python
+from ai_citation_map import build_map
+for d in build_map(rows):
+    print(d.domain, d.cites, len(d.questions), sorted(d.engines))
+```
+
+## Reading the output
+
+- Results are sorted by **distinct questions**, then citations: a domain cited once on each of eight questions matters more than one cited ten times on a single question.
+- Domains cited by every engine are the safest targets; ones cited by a single engine may come and go.
+- AI answers vary between runs and locations. Treat the map as a sample and re-run it with the same questions over time.
+
+## Collecting the input
+
+By hand (ask each question in each engine and log the cited links), or with CiteProof's free [AI citation checker](https://citeproof.co/tools/ai-citation-checker?utm_source=pypi&utm_medium=parasite&utm_campaign=ai-citation-map), which queries ChatGPT, Perplexity and Gemini and lists the domains each one cites.
+
+More templates (robots.txt rules for AI crawlers, llms.txt, JSON-LD): [citeproof/ai-visibility-toolkit](https://github.com/citeproof/ai-visibility-toolkit).
+
+MIT licensed. Maintained by [CiteProof](https://citeproof.co).

ai_citation_map-0.1.0/examples/citations.csv

@@ -0,0 +1,4 @@
+question,engine,cited_url
+best invoicing app for freelancers,chatgpt,https://www.g2.com/categories/invoicing
+best invoicing app for freelancers,perplexity,https://www.reddit.com/r/freelance/comments/abc
+best invoicing app for freelancers,gemini,https://zapier.com/blog/best-invoicing-software/

ai_citation_map-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-citation-map"
+version = "0.1.0"
+description = "Rank the domains cited in AI answers (ChatGPT, Perplexity, Gemini) from a CSV."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [{ name = "CiteProof", email = "hello@citeproof.co" }]
+keywords = ["seo", "aeo", "ai search", "chatgpt", "perplexity", "citations", "llm"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+
+[project.urls]
+Homepage = "https://github.com/citeproof/ai-citation-map"
+Source = "https://github.com/citeproof/ai-citation-map"
+"Related tools" = "https://citeproof.co/tools/ai-citation-checker?utm_source=pypi&utm_medium=parasite&utm_campaign=ai-citation-map"
+
+[project.scripts]
+ai-citation-map = "ai_citation_map.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai_citation_map"]

ai_citation_map-0.1.0/src/ai_citation_map/__init__.py

@@ -0,0 +1,5 @@
+"""Turn a CSV of URLs cited in AI answers into a ranked list of domains."""
+from .core import build_map, domain_of
+
+__all__ = ["build_map", "domain_of"]
+__version__ = "0.1.0"

ai_citation_map-0.1.0/src/ai_citation_map/cli.py

@@ -0,0 +1,44 @@
+import argparse
+import csv
+import sys
+
+from .core import build_map, read_csv
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="ai-citation-map",
+        description="Rank the domains cited in AI answers (ChatGPT, Perplexity, Gemini...) from a CSV "
+        "with columns question, engine, cited_url.",
+    )
+    p.add_argument("csv", help="input CSV file")
+    p.add_argument("-n", "--top", type=int, default=25, help="how many domains to show (default 25)")
+    p.add_argument("--csv-out", help="also write the full map to this CSV file")
+    a = p.parse_args(argv)
+
+    try:
+        rows = read_csv(a.csv)
+    except FileNotFoundError:
+        print(f"File not found: {a.csv}", file=sys.stderr)
+        return 1
+    missing = {"question", "engine", "cited_url"} - set(rows[0].keys() if rows else [])
+    if missing:
+        print(f"Missing column(s): {', '.join(sorted(missing))}", file=sys.stderr)
+        return 1
+
+    result = build_map(rows)
+    print(f"{'domain':35} {'cites':>5} {'questions':>9}  engines")
+    for s in result[: a.top]:
+        print(f"{s.domain:35} {s.cites:>5} {len(s.questions):>9}  {', '.join(sorted(s.engines))}")
+
+    if a.csv_out:
+        with open(a.csv_out, "w", newline="", encoding="utf-8") as f:
+            w = csv.writer(f)
+            w.writerow(["domain", "cites", "questions", "engines"])
+            for s in result:
+                w.writerow([s.domain, s.cites, len(s.questions), " ".join(sorted(s.engines))])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ai_citation_map-0.1.0/src/ai_citation_map/core.py

@@ -0,0 +1,42 @@
+import csv
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Iterable, List
+from urllib.parse import urlparse
+
+
+def domain_of(url: str) -> str:
+    """Return the host of a URL, lowercased, without a leading 'www.'."""
+    host = urlparse(url.strip()).netloc.lower()
+    return host[4:] if host.startswith("www.") else host
+
+
+@dataclass
+class DomainStats:
+    domain: str
+    cites: int = 0
+    questions: set = field(default_factory=set)
+    engines: set = field(default_factory=set)
+
+
+def build_map(rows: Iterable[dict]) -> List[DomainStats]:
+    """Aggregate rows with 'question', 'engine' and 'cited_url' keys.
+
+    Sorted by number of distinct questions, then by number of citations.
+    """
+    stats = {}
+    for row in rows:
+        url = (row.get("cited_url") or "").strip()
+        if not url:
+            continue
+        d = domain_of(url)
+        s = stats.setdefault(d, DomainStats(d))
+        s.cites += 1
+        s.questions.add((row.get("question") or "").strip())
+        s.engines.add((row.get("engine") or "").strip().lower())
+    return sorted(stats.values(), key=lambda s: (-len(s.questions), -s.cites, s.domain))
+
+
+def read_csv(path: str) -> List[dict]:
+    with open(path, newline="", encoding="utf-8") as f:
+        return list(csv.DictReader(f))

ai_citation_map-0.1.0/tests/test_core.py

@@ -0,0 +1,19 @@
+from ai_citation_map import build_map, domain_of
+
+
+def test_domain_of():
+    assert domain_of("https://www.G2.com/x") == "g2.com"
+    assert domain_of("http://reddit.com/r/a") == "reddit.com"
+
+
+def test_build_map_orders_by_questions():
+    rows = [
+        {"question": "q1", "engine": "chatgpt", "cited_url": "https://a.com/1"},
+        {"question": "q1", "engine": "chatgpt", "cited_url": "https://a.com/2"},
+        {"question": "q1", "engine": "chatgpt", "cited_url": "https://a.com/3"},
+        {"question": "q1", "engine": "perplexity", "cited_url": "https://b.com"},
+        {"question": "q2", "engine": "gemini", "cited_url": "https://www.b.com"},
+    ]
+    m = build_map(rows)
+    assert m[0].domain == "b.com" and len(m[0].questions) == 2
+    assert m[1].domain == "a.com" and m[1].cites == 3