Source Adapters¶
Litseer searches multiple academic databases through a unified adapter
interface. Each source returns results as Work objects with a common
set of fields. This document describes each source, its API, and what
it is best suited for.
All sources implement the SearchSource protocol:
- search(query, year, limit) -- keyword search
- get_work(identifier) -- fetch a single paper by DOI or ID
- get_citing_works(identifier, limit) -- forward citation walk
- get_references(identifier, limit) -- backward reference walk
openalex¶
Database: OpenAlex -- open catalog of 250M+ scholarly works, built on the former Microsoft Academic Graph.
API: https://api.openalex.org/ (REST, JSON)
API key: None required. Polite pool access via mailto in User-Agent for higher rate limits.
Rate limits: 10 req/s without mailto, 100 req/s with mailto in polite pool.
Citation walking: Full support. Forward citations via cites: filter, backward references via referenced_works field.
Fields returned: title, authors, year, venue, venue_type, DOI, OpenAlex ID, cited_by_count, is_open_access, primary_field (topic), suggested_citekey.
Coverage strengths: - Broadest coverage across all disciplines - Strong citation graph with forward and backward links - Open access status detection - Topic/field classification - Retracted paper filtering (excluded by default)
Best for: Primary search source. Start here for any literature review.
semanticscholar¶
Database: Semantic Scholar -- AI-powered academic search by the Allen Institute for AI, covering 200M+ papers.
API: https://api.semanticscholar.org/graph/v1/ (REST, JSON)
API key: None required for basic access. Optional API key for higher limits.
Rate limits: 100 requests per 5 minutes (free tier). Litseer uses a conservative 3-second interval between requests.
Citation walking: Full support. Forward citations and backward references via dedicated endpoints.
Fields returned: title, authors, year, venue, venue_type, DOI, Semantic Scholar ID, citationCount, isOpenAccess, fieldsOfStudy, suggested_citekey.
Coverage strengths: - Strong in computer science, engineering, and biomedical fields - Publication type detection (journal, conference, review) - Fields of study classification - Good citation graph coverage
Best for: Engineering and CS-heavy reviews. Good complement to OpenAlex with different ranking.
crossref¶
Database: CrossRef -- DOI registration agency metadata for 150M+ works from 17,000+ publishers.
API: https://api.crossref.org/ (REST, JSON)
API key: None required. Polite pool via mailto.
Rate limits: 50 req/s with mailto in polite pool, lower without.
Citation walking: Backward references only (via reference field in work metadata). No forward citation endpoint.
Fields returned: title, authors, year, venue, venue_type, DOI, is-referenced-by-count, is_open_access (from license data), suggested_citekey.
Coverage strengths: - Authoritative DOI metadata (it is the DOI registry) - Accurate publication dates and venue information - Good publisher type detection (journal-article, proceedings-article, etc.) - License/open-access information from publisher data
Best for: Accurate bibliographic metadata. Good for verifying DOIs and getting canonical publication info.
nasa_ntrs¶
Database: NASA Technical Reports Server -- NASA's repository of technical reports, conference papers, journal articles, and patents.
API: https://ntrs.nasa.gov/api/ (REST, JSON)
API key: None required.
Rate limits: 500 requests per 15 minutes. Litseer uses a 0.2-second interval.
Citation walking: Not supported. NTRS does not expose citation graph data.
Fields returned: title, authors, year, venue, venue_type, DOI (when available), NTRS URL, NASA center code, suggested_citekey.
Coverage strengths: - NASA technical memoranda, contractor reports, and conference papers - Content not always indexed in general academic databases - All content is public domain / open access - Covers aeronautics, space science, and engineering disciplines - Includes grey literature from NASA centers (JPL, LaRC, GRC, etc.)
Best for: Aerospace engineering reviews. Essential for finding NASA technical reports that are not in CrossRef or OpenAlex.
ieee¶
Database: IEEE Xplore -- IEEE and IET publications including journals, conferences, and standards.
API: https://ieeexploreapi.ieee.org/api/v1/ (REST, JSON)
API key: Required. Register at developer.ieee.org. Set via --ieee-key flag or IEEE_API_KEY environment variable. If no key is provided, IEEE is silently skipped.
Rate limits: Varies by API tier. Litseer uses a 0.5-second interval.
Citation walking: Not supported via the Xplore API.
Fields returned: title, authors, year, venue (publication_title), venue_type (from content_type), DOI, IEEE URL, citing_paper_count, access_type, IEEE index terms, suggested_citekey.
Coverage strengths: - Definitive source for IEEE journals (IEEE T-AES, IEEE T-CST, etc.) - IEEE conference proceedings (AEROCONF, DASC, etc.) - IEEE standards - Index terms for subject classification - Distinguishes journal vs. conference vs. standard content types
Best for: Avionics, control systems, signal processing, and any topic with strong IEEE presence.
aiaa¶
Database: AIAA (American Institute of Aeronautics and Astronautics) publications, accessed via CrossRef with member ID filtering.
API: https://api.crossref.org/ with member:27 filter (REST, JSON)
API key: None required.
Rate limits: Same as CrossRef (polite pool with mailto).
Citation walking: Backward references only (via CrossRef reference data).
Fields returned: Same as CrossRef, with source_db set to "aiaa".
Coverage strengths: - AIAA Journal, Journal of Spacecraft and Rockets, Journal of Propulsion and Power, etc. - AIAA conference papers (SciTech, Aviation, SPACE, etc.) - Focused results: only AIAA publications, no noise from other publishers - Sorted by citation count
Best for: Core aerospace research. Use this alongside openalex to ensure full AIAA coverage.
sae¶
Database: SAE International publications, accessed via CrossRef with member ID filtering.
API: https://api.crossref.org/ with member:403 filter (REST, JSON)
API key: None required.
Rate limits: Same as CrossRef.
Citation walking: Backward references only.
Fields returned: Same as CrossRef, with source_db set to "sae".
Coverage strengths: - SAE Technical Papers (SAE-TP series) - SAE standards (J-standards, AMS, AS, ARP) - Automotive and aerospace engineering overlap - Materials, manufacturing, and testing standards
Best for: Industry standards and applied engineering. Especially useful for propulsion, materials, and manufacturing topics.
skybrary¶
Database: SKYbrary -- Eurocontrol's aviation safety knowledge base with content from ICAO, EASA, and industry contributors.
API: MediaWiki Action API at https://www.skybrary.aero/api.php (REST, JSON)
API key: None required.
Rate limits: No documented limit. Litseer uses a 0.5-second interval to be polite.
Citation walking: Supported via MediaWiki backlinks (forward) and page links (backward). These are wiki cross-references, not formal citations.
Fields returned: title, authors (always "SKYbrary"), year (often unavailable), venue ("SKYbrary"), venue_type ("report" or "standard"), URL, abstract from search snippet, suggested_citekey.
Coverage strengths: - Aviation safety procedures and best practices - Accident and incident analysis - ICAO and EASA regulations - Human factors in aviation - ATM (Air Traffic Management) topics
Limitations: - Not a peer-reviewed source (classified as Tier 2 or 4) - Year information often unavailable - Author always listed as "SKYbrary" - No DOIs
Best for: Aviation safety reviews, regulatory context, and human factors research. Useful for background sections but not primary citations.
Source Selection Guidelines¶
For a typical aerospace engineering literature review:
# Comprehensive search (all free sources)
litseer search config.yaml -s openalex -s crossref -s aiaa -s nasa_ntrs -s sae
# Quick broad search
litseer search config.yaml -s openalex
# Aerospace-focused
litseer search config.yaml -s openalex -s aiaa -s nasa_ntrs
# With IEEE (requires API key)
IEEE_API_KEY=your_key litseer search config.yaml -s openalex -s ieee -s aiaa
# Aviation safety focus
litseer search config.yaml -s openalex -s skybrary -s nasa_ntrs
When no -s flags are given, litseer searches all sources (skipping IEEE
if no API key is set).