# API Sources

`axm-bib` integrates eight academic APIs. This page explains what each provides and how they complement each other.

## Semantic Scholar

**URL:** `https://api.semanticscholar.org/graph/v1`

The primary search engine. Covers 200M+ papers from all fields.

| Feature | Details |
|---|---|
| **Search** | Full-text relevance ranking |
| **Fields** | Title, authors, year, abstract, DOI, arXiv ID, citations, venue, OA PDF |
| **Rate limit** | 1 req/sec (public), 10 req/sec (with API key) |
| **Auth** | Optional `x-api-key` header |

**Used by:**

- [`BibPipeline.search()`][axm_bib.pipeline.BibPipeline.search] — primary search engine
- `VenueEnricher` (`venue.py`) — direct paper lookup via `/paper/ARXIV:{id}` for arXiv venue enrichment

---

## CrossRef

**URL:** `https://api.crossref.org`

The authoritative source for DOI metadata. Covers 140M+ DOI records.

| Feature | Details |
|---|---|
| **DOI resolution** | Full metadata + BibTeX formatting |
| **Search** | Title-based search (fallback for S2) |
| **Rate limit** | Generous (polite pool with `mailto` header) |
| **Auth** | None required |

**Used by:**

- [`BibPipeline.resolve()`][axm_bib.pipeline.BibPipeline.resolve] — DOI → BibTeX
- [`BibPipeline.search()`][axm_bib.pipeline.BibPipeline.search] — one of 6 search sources in the parallel fan-out

---

## Unpaywall

**URL:** `https://api.unpaywall.org/v2`

Finds open-access versions of papers. Covers 30M+ OA articles.

| Feature | Details |
|---|---|
| **OA lookup** | Returns list of OA locations per DOI |
| **Priority** | Repositories (arXiv) before publishers |
| **Rate limit** | 100K req/day |
| **Auth** | Email address required (`?email=...`) |

**Used by:** [`BibPipeline.download_pdf()`][axm_bib.pipeline.BibPipeline.download_pdf] — as one of several PDF sources in the multi-source URL chain.

### OA Location Priority

Unpaywall returns multiple OA locations. `axm-bib` sorts them:

1. **Repository** (arXiv, PubMed Central) — reliable, no 403s
2. **Publisher** — may return 403 Forbidden

If a URL returns 403, the next one is tried automatically.

---

## DBLP

**URL:** `https://dblp.org/search/publ/api`

Computer science bibliography with native BibTeX. Covers 6M+ publications.

| Feature | Details |
|---|---|
| **Search** | Title/keyword search with venue filtering |
| **BibTeX** | Native BibTeX from `dblp.org/rec/{key}.bib` |
| **Rate limit** | No auth required, generous limits |
| **Auth** | None |

**Used by:**

- [`BibPipeline.search()`][axm_bib.pipeline.BibPipeline.search] — one of 6 search sources in the parallel fan-out
- `VenueEnricher` (`venue.py`) — DBLP fallback when S2 direct lookup fails (CoRR entries are filtered out via `_dblp_non_corr_venue`)

---

## OpenReview

**URL:** `https://api2.openreview.net`

Peer review platform for top ML venues (NeurIPS, ICLR, ICML, COLM, TMLR).

| Feature | Details |
|---|---|
| **Search** | Content search via `/notes/search` |
| **Venue listing** | List papers by venue ID (e.g. `NeurIPS.cc/2024/Conference`) |
| **BibTeX** | Synthetic `@inproceedings` generated from metadata |
| **API versions** | Handles both v1 (plain values) and v2 (`{value: ...}` wrapper). Uses v2 API (`api2.openreview.net`) as primary, with **v1 API fallback** (`api.openreview.net`) when v2 fails to find a note |
| **Identifier formats** | OpenReview URL (`https://openreview.net/forum?id=...`) or bare prefix (`openreview:ID`) |
| **Auth** | None required for public endpoints |

**Used by:**

- [`BibPipeline.search()`][axm_bib.pipeline.BibPipeline.search] — one of 6 search sources in the parallel fan-out
- `OpenReviewClient` — standalone client for conference paper discovery (`venue_papers()`, `bibtex()`)

---

## arXiv

**URL:** `https://arxiv.org/bibtex/{id}` (BibTeX) / `http://export.arxiv.org/api/query` (search)

Preprint repository with native BibTeX and guaranteed open-access PDFs.

| Feature | Details |
|---|---|
| **BibTeX** | Native `@misc` entries from `arxiv.org/bibtex/{id}` |
| **Search** | Atom XML via `export.arxiv.org/api/query` |
| **PDF** | Deterministic URL: `arxiv.org/pdf/{id}.pdf` |
| **Rate limit** | 1 request per 3 seconds (Terms of Use) |
| **Auth** | None |

**Used by:** `ArXivClient` — standalone client for native BibTeX + paper search

!!! note "ID formats"
    ArXivClient normalizes various ID formats: `arXiv:1706.03762`,
    `https://arxiv.org/abs/1706.03762`, `math/0102101` (old format).

---

## OpenAlex

**URL:** `https://api.openalex.org/works`

Open catalog of 240M+ scholarly works with CC0 data. Key strength is **cross-referencing**: given a title, it returns DOI, MAG ID, OpenAlex ID.

| Feature | Details |
|---|---|
| **Search** | Title/keyword search via `works?search={query}` |
| **Direct lookup** | `works/{openalex_id}` |
| **Cross-ref IDs** | DOI, arXiv ID, MAG ID from `ids` field |
| **Abstract** | Reconstructed from inverted index |
| **Auth** | None (polite User-Agent recommended) |

**Used by:** `OpenAlexClient` — search-only client for identity linking

---

## HAL

**URL:** `http://api.archives-ouvertes.fr/search/`

French multi-disciplinary open-access archive (CNRS/CCSD). Covers theses, INRIA reports, and French conference papers.

| Feature | Details |
|---|---|
| **Search** | Solr-based: `q=title_t:"query"&wt=json` |
| **BibTeX** | Native via `wt=bibtex` parameter |
| **Fields** | `halId_s`, `title_s`, `authFullName_s`, `producedDateY_i`, `doiId_s` |
| **Auth** | None |

**Used by:** `HALClient` — standalone client for French research publications

---

## Fallback Strategy

```mermaid
graph LR
    Search["Search"] --> FanOut["6-source fan-out"]
    FanOut --> S2["Semantic Scholar"]
    FanOut --> CR["CrossRef"]
    FanOut --> DBLP["DBLP"]
    FanOut --> OR["OpenReview"]
    FanOut --> ArXivS["arXiv"]
    FanOut --> OA["OpenAlex"]

    DOI["DOI → BibTeX"] --> CR2["CrossRef"]

    ArXivBib["arXiv BibTeX"] --> ARC["ArXivClient"]
    Venue["Venue listing"] --> OR["OpenReview"]
    HALBib["HAL BibTeX"] --> HAL["HALClient"]

    PDF["PDF Download"] --> S2OA["S2 Open Access PDF"]
    S2OA -->|none| ArXivDirect["arXiv direct"]
    ArXivDirect -->|none| UW["Unpaywall"]
    UW --> Repo["Repository URL"]
    Repo -->|403| Pub["Publisher URL"]
    Pub -->|403| FB{"DOI-based fallback"}
    FB -->|arXiv DOI| ArXiv["arxiv.org/pdf/{id}"]
    FB -->|ACL DOI| ACL["aclanthology.org/{path}.pdf"]
    FB -->|unknown| Err["Not open access"]
```
