crossref_local API

Main Functions

crossref_local.search(query, limit=10, offset=0, with_if=False)[source]

Full-text search across works.

Uses FTS5 index for fast searching across titles, abstracts, and authors.

Parameters:

query (str) – Search query (supports FTS5 syntax)
limit (int) – Maximum results to return
offset (int) – Skip first N results (for pagination)
with_if (bool) – Include impact factor data (OpenAlex)

Return type:

SearchResult

Returns:

SearchResult with matching works

Example

>>> from crossref_local import search
>>> results = search("machine learning")
>>> print(f"Found {results.total} matches")

crossref_local.get(doi)[source]

Get a work by DOI.

Parameters:: doi (str) – Digital Object Identifier
Return type:: Optional[Work]
Returns:: Work object or None if not found

Example

>>> from crossref_local import get
>>> work = get("10.1038/nature12373")
>>> print(work.title)

crossref_local.get_many(dois)[source]

Get multiple works by DOI.

Parameters:: dois (List[str]) – List of DOIs
Return type:: List[Work]
Returns:: List of Work objects (missing DOIs are skipped)

crossref_local.count(query)[source]

Count matching works without fetching results.

Parameters:: query (str) – FTS5 search query
Return type:: int
Returns:: Number of matching works

crossref_local.exists(doi)[source]

Check if a DOI exists in the database.

Parameters:: doi (str) – Digital Object Identifier
Return type:: bool
Returns:: True if DOI exists

crossref_local.configure(db_path)[source]

Configure for local database access.

Parameters:: db_path (str) – Path to CrossRef SQLite database
Return type:: None

Example

>>> from crossref_local import configure
>>> configure("/path/to/crossref.db")

crossref_local.configure_http(api_url='http://localhost:8333')[source]

Configure for HTTP API access.

Parameters:: api_url (str) – URL of CrossRef Local API server
Return type:: None

Example

>>> from crossref_local import configure_http
>>> configure_http("http://localhost:8333")
>>> # Or via SSH tunnel:
>>> # ssh -L 8333:127.0.0.1:8333 your-server
>>> configure_http()  # Uses default localhost:8333

crossref_local.enrich(results, include_citations=True, include_references=True)[source]

Enrich search results with full metadata (citations, references).

The search() function returns basic metadata for speed. This function fetches full metadata for each work, adding citation counts and references.

Parameters:

results (SearchResult) – SearchResult from search()
include_citations (bool) – Include citation counts
include_references (bool) – Include reference DOIs

Return type:

SearchResult

Returns:

SearchResult with enriched works

Example

>>> from crossref_local import search, enrich
>>> results = search("machine learning", limit=10)
>>> enriched = enrich(results)
>>> for work in enriched:
...     print(f"{work.title}: {work.citation_count} citations")

crossref_local.enrich_dois(dois, include_citations=True, include_references=True)[source]

Enrich a list of DOIs with full metadata.

Fetches complete metadata for each DOI including citation counts and reference lists.

Parameters:

dois (List[str]) – List of DOIs to enrich
include_citations (bool) – Include citation counts
include_references (bool) – Include reference DOIs

Return type:

List[Work]

Returns:

List of Work objects with full metadata

Example

>>> from crossref_local import enrich_dois
>>> works = enrich_dois(["10.1038/nature12373", "10.1126/science.aax0758"])
>>> for w in works:
...     print(f"{w.doi}: {w.citation_count} citations, {len(w.references)} refs")

crossref_local.get_mode()[source]

Get current mode.

Return type:: str
Returns:: “db” or “http”

crossref_local.info()[source]

Get database/API information.

Return type:: dict
Returns:: Dictionary with database stats and mode info

Data Classes

Work

class crossref_local.Work(doi, title=None, authors=<factory>, year=None, journal=None, issn=None, volume=None, issue=None, page=None, publisher=None, type=None, abstract=None, url=None, citation_count=None, references=<factory>, impact_factor=None, impact_factor_source=None)[source]

Represents a scholarly work from CrossRef.

doi: Digital Object Identifier

title: Work title

authors: List of author names

year: Publication year

journal: Journal/container title

issn: Journal ISSN

volume: Volume number

issue: Issue number

page: Page range

publisher: Publisher name

type: Work type (journal-article, book-chapter, etc.)

abstract: Abstract text (if available)

url: Resource URL

citation_count: Number of citations (if available)

references: List of reference DOIs

doi: str

title: str | None = None

authors: List[str]

year: int | None = None

journal: str | None = None

issn: str | None = None

volume: str | None = None

issue: str | None = None

page: str | None = None

publisher: str | None = None

type: str | None = None

abstract: str | None = None

url: str | None = None

citation_count: int | None = None

references: List[str]

impact_factor: float | None = None

impact_factor_source: str | None = None

classmethod from_metadata(doi, metadata)[source]

Create Work from CrossRef metadata JSON.

Parameters:

doi (str) – DOI string
metadata (dict) – CrossRef metadata dictionary

Return type:

Work

Returns:

Work instance

to_dict()[source]

Convert to dictionary.

Return type:: dict

citation(style='apa')[source]

Format as citation string.

Parameters:: style (str) – Citation style (currently only “apa” supported)
Return type:: str
Returns:: Formatted citation string

to_text(include_abstract=False)[source]

Format as human-readable text.

Parameters:: include_abstract (bool) – Include abstract in output
Return type:: str
Returns:: Formatted text string

to_bibtex()[source]

Format as BibTeX entry.

Return type:: str
Returns:: BibTeX string

save(path, format='json')[source]

Save work to file.

Parameters:

path (str) – Output file path
format (str) – Output format (“text”, “json”, “bibtex”)

Return type:

str

Returns:

Path to saved file

Examples

>>> work = get("10.1038/nature12373")
>>> work.save("paper.json")
>>> work.save("paper.bib", format="bibtex")

__init__(doi, title=None, authors=<factory>, year=None, journal=None, issn=None, volume=None, issue=None, page=None, publisher=None, type=None, abstract=None, url=None, citation_count=None, references=<factory>, impact_factor=None, impact_factor_source=None)

SearchResult

class crossref_local.SearchResult(works, total, query, elapsed_ms, limit_info=None)[source]

Container for search results with metadata.

works: List of Work objects

total: Total number of matches

query: Original search query

elapsed_ms: Search time in milliseconds

limit_info: Information about result limiting

works: List[Work]

total: int

query: str

elapsed_ms: float

limit_info: LimitInfo | None = None

save(path, format='json', include_abstract=True)[source]

Save search results to file.

Parameters:

path (str) – Output file path
format (str) – Output format (“text”, “json”, “bibtex”)
include_abstract (bool) – Include abstracts in text format

Return type:

str

Returns:

Path to saved file

Examples

>>> results = search("machine learning", limit=10)
>>> results.save("results.json")
>>> results.save("results.bib", format="bibtex")
>>> results.save("results.txt", format="text")

__init__(works, total, query, elapsed_ms, limit_info=None)