Skip to main content
Tutorial

Build a Citation Graph from OpenAlex and Crossref

Build a citation graph in Python: seed works from OpenAlex, follow references, dedupe by DOI, enrich from Crossref, all through one API key.

fastcrw
By RecepNovember 15, 20267 min read

By the fastCRW team · Catalogue figures checked 2026-11-05 against GET /v1/data · Verify independently before relying on any figure.

A citation graph has papers as nodes and "cites" relationships as edges. You can build one from OpenAlex alone, because each work lists the works it references. The hard parts are the traversal (which papers to expand), the deduplication (the same paper can arrive under more than one ID) and the enrichment (Crossref can say which registry issued a DOI). This guide builds a small graph in Python through the Pergamon catalogue, with one fastCRW API key for OpenAlex, Crossref, DataCite and Europe PMC.

The graph model

Each node is a work. Its key is the DOI when it has one, and its OpenAlex ID when it does not. Each edge is a pair (citing, cited). A work's references give you its outgoing edges. The papers that cite a work come from a reverse filter, cites:, which gives you the incoming edges.

Seed a work and read its references

Start from one OpenAlex work. Ask only for the fields the graph needs, because a full work record is large. This call returns the title and the list of works it cites:

curl "https://api.fastcrw.com/v1/data/openalex/work?id=W2741809807&select=id,title,referenced_works" \
  -H "Authorization: Bearer $CRW_API_KEY"

In our run the seed returned 46 referenced works. Each reference is a full OpenAlex URL, so strip it to its short ID before you use it as a key.

Find the papers that cite a work

The works capability with a cites: filter returns the papers that cite a given work. Use it for the reverse direction. Highly cited works have very long lists, so cap the expansion instead of pulling every citer:

curl "https://api.fastcrw.com/v1/data/openalex/works?filter=cites:W2100837269&select=id,title" \
  -H "Authorization: Bearer $CRW_API_KEY"

In our run the meta.count for that work was 248263 citing papers. A page holds 25 results by default, and the page option moves through them. Expanding every citer is almost never what a graph needs.

The traversal script

This script walks outward from the seed through references, breadth first, to a depth of 2 and at most 50 fetched works. It skips any work OpenAlex does not return, keys nodes by DOI where one exists, and keeps only the edges between works it fetched:

# pip install crw
from collections import deque

from crw import CrwClient
from crw.exceptions import CrwApiError

client = CrwClient()  # reads CRW_API_KEY
SEED = "W2741809807"
MAX_DEPTH = 2
MAX_NODES = 50


def short_id(openalex_url: str) -> str:
    return openalex_url.rsplit("/", 1)[-1]


def node_key(work: dict) -> str:
    doi = (work.get("doi") or "").lower().replace("https://doi.org/", "")
    return f"doi:{doi}" if doi else f"openalex:{short_id(work['id'])}"


def fetch_work(work_id: str) -> dict | None:
    try:
        res = client.get_data("openalex", "work", {"id": work_id, "select": "id,title,doi,referenced_works"})
    except CrwApiError as exc:
        print("skipped", work_id, exc)
        return None
    return res["data"]


def crawl(seed_id: str) -> tuple[dict, set]:
    nodes: dict[str, dict] = {}
    edges: set[tuple[str, str]] = set()
    seen = {seed_id}
    queue: deque[tuple[str, int]] = deque([(seed_id, 0)])
    while queue and len(nodes) < MAX_NODES:
        work_id, depth = queue.popleft()
        work = fetch_work(work_id)
        if work is None:
            continue
        nodes[work_id] = {"key": node_key(work), "title": work.get("title")}
        for ref_url in work.get("referenced_works") or []:
            ref = short_id(ref_url)
            edges.add((work_id, ref))
            if depth < MAX_DEPTH and ref not in seen:
                seen.add(ref)
                queue.append((ref, depth + 1))
    return nodes, edges


if __name__ == "__main__":
    nodes, edges = crawl(SEED)
    kept = {(a, b) for a, b in edges if a in nodes and b in nodes}
    keys = {v["key"] for v in nodes.values()}
    key_edges = {(nodes[a]["key"], nodes[b]["key"]) for a, b in kept}
    print(f"fetched works: {len(nodes)}, unique keys after DOI dedupe: {len(keys)}, edges: {len(key_edges)}")

Output from our run. The whole script took about 50 seconds:

skipped W2611818942 OpenAlex returned 404 for this request
skipped W6640061894 OpenAlex returned 404 for this request
fetched works: 50, unique keys after DOI dedupe: 50, edges: 164

The two 404s are referenced works that OpenAlex did not return. The script logs them and moves on instead of stopping the crawl.

Enrich with Crossref and DataCite

Crossref can tell you which registration agency issued a DOI, and that decides where the record lives. Zenodo DOIs are issued through DataCite, not Crossref, so ask Crossref first and then query the right source:

curl "https://api.fastcrw.com/v1/data/crossref/agency?doi=10.5281/zenodo.1422871" \
  -H "Authorization: Bearer $CRW_API_KEY"
{"status":"ok","message-type":"work-agency","message":{"DOI":"10.5281/zenodo.1422871","agency":{"id":"datacite","label":"DataCite"}}}

The agency is DataCite, so query the datacite provider for the record:

curl "https://api.fastcrw.com/v1/data/datacite/doi?doi=10.5281/zenodo.1422871" \
  -H "Authorization: Bearer $CRW_API_KEY"

In our run the title in the response was "citation-network: First release of citation network R code".

Biomedical citations from Europe PMC

For a biomedical paper, Europe PMC keeps its own citation list. Pass the source and the record ID:

curl "https://api.fastcrw.com/v1/data/europepmc/citations?source=MED&id=31378106" \
  -H "Authorization: Bearer $CRW_API_KEY"

The response has citationList and hitCount. In our run the hit count was 30. Add these edges with the same key rule, so a paper seen in Europe PMC and OpenAlex lands on one node when both records share a DOI.

What the dedupe step did in this run

The key rule merges two records only when they share a DOI. In this run all 50 works already had distinct keys, so the dedupe step removed nothing. It earns its place when the same paper arrives under two OpenAlex IDs, or when two sources agree on a DOI. Records with no DOI on either side stay separate, and that is the correct behaviour, not a bug to hide.

Store the graph

For exploration, load the key_edges set into NetworkX as a directed graph. For a larger graph, write the edges to a Postgres table with two text columns and an index on each, then run traversals in SQL. Either way the traversal logic stays the same.

Cost

Each successful call costs 1 credit. The script above made 52 work calls: 50 returned data, and the 2 that returned 404 are not billed. The reverse citer query costs 1 credit per page. Budget a crawl as nodes times calls per node, and set MAX_NODES before you start, not after the bill arrives. Find calls are free. See pricing for plan prices.

What this does not do

  • Missing edges are not proof. An edge comes from the reference list of each work. A citation that a source does not list is not confirmed to be absent.
  • Some works have no references in the data. For example, W4391876620 has an empty referenced_works list. The script treats that as zero outgoing edges, not as an error.
  • The DOI key merges only exact matches. Two records for the same paper with different DOIs, or with a DOI on one side only, stay as two nodes.
  • Metadata is not full text. This guide computes over metadata. Check each source's terms before you redistribute records or abstracts.

Read the SDK response shape

The Python SDK returns the same data with camelCase keys, while the REST envelope keeps the snake_case names. In our run the SDK result carried creditsUsed, and its provenance block carried attributionText. The data field is the OpenAlex work object itself, so res["data"]["referenced_works"] is the list the script walks. Keep the two shapes apart in your code, and do not mix REST and SDK keys in one parser.

Why the caps matter

A breadth-first crawl grows fast. Each fetched work can add dozens of outgoing edges, and each new node costs a call. The script stops at 50 fetched works, and it stops expanding at depth 2. In our run the crawl hit the 50-work cap, so the cap, not the citation structure, set the size of the sample.

Citers are a bigger risk than references. The paper W2100837269 had 248263 citing works in our run. If the crawl followed every citer of every node, a single famous paper would dominate the budget. Cap citers per node, sort them if the source supports it, and record how many you skipped so the graph reports its own truncation.

Check the crawl before you trust it

A crawl can finish and still be wrong. Four numbers tell you whether it did what you meant:

  • Skipped works. Our run skipped 2 works that OpenAlex returned 404 for. A large skip count means the seed or the cap needs a second look.
  • Empty reference lists. Some works have an empty referenced_works list. Count them. An empty list means the source gives no outgoing edges for that work, which is not proof that the paper cites nothing.
  • Distinct keys against nodes. If the number of unique keys is lower than the number of nodes, the DOI rule merged records. In our run the two numbers matched at 50.
  • Edges that point outside the graph. The script drops edges whose ends it did not fetch. Count how many it dropped. Those are the references the cap cut off.

Read the sample, not the field

The in-degree of a node inside your sample is the number of sampled works that cite it. It is not the global citation count for that paper. For the global number, use the meta.count of the cites: filter, as the reverse query above shows. Report the sample figure and the source figure as two separate numbers, with the sample size next to them.

Budget the crawl before you run it

The sample run made 52 work calls and took about 50 seconds. The time grows with the number of calls, so budget about a second per call and one credit per successful call before you start a larger crawl. Set the node cap first, then the depth, and only then the citer cap for the highly cited nodes.

Errors in the crawl

The script catches only CrwApiError, so a bad key or a network fault still stops the run loudly. A work that OpenAlex does not return raises an upstream error, which the script prints as a skip. The errorCode on that response is upstream_error, and a failed call is not billed.

Sources

Related: OpenAlex API in Python · Build a knowledge graph from web data · Public data API for AI agents · OpenAlex on Pergamon

FAQ

Frequently asked questions

Do I need an OpenAlex or Crossref key?
Not for these sources. OpenAlex, Crossref, DataCite and Europe PMC are server sources in the Pergamon catalogue, so your fastCRW API key covers them. Each successful call costs 1 credit, a failed call is not billed, and find calls are free.
Why dedupe by DOI instead of by title?
Titles vary by punctuation, capitalization and subtitle across sources, so title matching creates duplicate nodes. A DOI is issued once per work, so it is a stable key when two records share one.
How deep should I traverse from one seed paper?
Two hops is a good start for a focused topic map. Cap the number of fetched works before you start, as the script does with MAX_NODES, and cap citer expansion per node so one highly cited paper does not dominate the crawl.
Is Pergamon a separate citation database?
No. Pergamon calls OpenAlex itself and returns its JSON unchanged, with the licence and attribution attached. The citation links come from OpenAlex's own records, and you still need to read each source's terms before you redistribute them.

Get Started

Try fastCRW free

Run a live request in the playground — no signup required. Or grab a free API key with 500 credits, earn up to 500 more, no credit card.

Continue exploring

More tutorial posts

View category archive