habanero Python Client

habanero provides several specialized modules for interacting with the Crossref API:

• crossref: Core Crossref APIs.
• worksquery: Use the WorksQuery class to query works from Crossref.
• workscontainer: Use the WorksContainer class to work with collections of works.
• filters: Provides filters for use with the crossref module.
• counts: Access Crossref citation counts.
• cn: Handles Crossref content negotiation.

Rate Limits

Monitor the following HTTP headers to track your current usage and limits:

• X-Rate-Limit-Limit
• X-Rate-Limit-Interval

Search Behavior

When performing searches via the Crossref search API, note that the API does not perform full-text searches or abstract searches. It only searches metadata available in the returned data, such as article titles and authors.

The habanero library is organized into specialized modules. You can either import the entire library or import specific modules individually to reduce overhead. The available modules are:

• Crossref: Provides core Crossref APIs for searching, accessing journal information, member data, etc.
• Counts: Provides access to Crossref citation counts.
• Content negotiation: Handles content negotiation logic.

To install the latest development version directly from GitHub, or to build it from a local clone, use the following commands.

# Install dev version from git
pip install git+https://github.com/sckott/habanero.git#egg=habanero

# Build from local clone
git clone https://github.com/sckott/habanero.git
cd habanero
make install

You can install the stable version of habanero using pip or uv. If you need to fix BibTeX format citations using content negotiation, install the optional [bibtex] dependency which includes bibtexparser >= 2.0.0b7.

# pip
pip install habanero

# pip with bibtex support
pip install habanero[bibtex]

# uv w/ legacy project setup
uv pip install habanero

# uv w/ pyproject.toml
uv add habanero

You can use uv to manage your installation depending on your project structure:

• For legacy project setups, use uv pip install.
• For projects using pyproject.toml, use uv add to add the dependency to your project.

# uv w/ legacy project setup
uv pip install habanero

# uv w/ pyproject.toml
uv add habanero

If you need to fix BibTeX format citations using content negotiation, install habanero with the [bibtex] extra.

pip install habanero[bibtex]

To install the stable version of habanero from PyPI, use the standard pip install command.

pip install habanero

Habanero supports automatic pagination using cursors. When do_request() is called, if the response contains a next-cursor, the class will automatically perform subsequent requests to fetch more data until either no more cursors are provided, the cursor_max limit is reached, or the total-results count is met.

If progress_bar=True is passed to the Request constructor, a tqdm progress bar will be displayed in the console, tracking the number of request 'runs' required to complete the pagination process.

request = Request(
    # ... other params ...
    cursor_max=5000,
    progress_bar=True
)
results = request.do_request()

To inspect the underlying HTTP requests and responses (similar to curl -v), configure the standard Python logging module to the DEBUG level. This is useful for troubleshooting connection issues or inspecting headers.

import logging
import httpx2
from habanero import Crossref

logging.basicConfig(
    format="%(levelname)s [%(asctime)s] %(name)s - %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    level=logging.DEBUG
)

cr = Crossref()
cr.works(query="ecology")