Springer Nature API Client

A Python package to interact with the Springer Nature API for fetching metadata, open access articles, and text & data mining (TDM) content.

🚀 Installation

Install Python

Ensure you have Python installed (version 3.9+ recommended).

Windows: Download from python.org and install.

macOS: Install via Homebrew:

brew install python

Linux: Install using package manager (e.g., apt for Debian/Ubuntu):

sudo apt update && sudo apt install python3 python3-venv python3-pip

For Users

To install the package from PyPI(If you just want to use the package in your project):

pip install springernature_api_client

For Developers

If you're planning to contribute to the project:

1. Install Poetry (dependency management tool) This project uses Poetry for dependency management. Install Poetry if you haven't already:

curl -sSL https://install.python-poetry.org | python3 -

2. Clone the repository and install dependencies

   git clone https://github.com/springernature/springernature_api_client.git
   cd springernature_api_client
   poetry install --with dev

3. Activate the virtual environment using Poetry:

poetry env use python
poetry shell
# or 
poetry env activate

See CONTRIBUTING.md for more details on the development workflow.

🔑 Setup

Before using the package, obtain an API key from Springer Nature Developer Portal.

Set the API key in your environment:

export SPRINGER_API_KEY="your_api_key_here"

Or pass it directly in Python:

api_key = "your_api_key_here"

📌 Basic Usage

Fetch Metadata and Export to Excel

import springernature_api_client.metadata as metadata
from springernature_api_client.utils import results_to_dataframe

# Initialize API Client
metadata_client = metadata.MetadataAPI(api_key="your_api_key")

# Fetch results (pagination enabled, stops at `s=200`)
response = metadata_client.search(q='keyword:"cancer"', p=20, s=1, fetch_all=False, is_premium=False)

# Convert API response to DataFrame & export to Excel
df = results_to_dataframe(response, export_to_excel=True, filename="articles.xlsx")

print(df.head())  # Display first few rows

📚 API Modules

1️⃣ Meta API

import springernature_api_client.meta as meta
from springernature_api_client.utils import results_to_dataframe

meta_client = meta.MetaAPI(api_key="your_api_key")
response = meta_client.search(q='keyword:"cancer"', p=20, s=1, fetch_all=False, is_premium=False)
df = results_to_dataframe(response, export_to_excel=True)
print(df.head())

2️⃣ Metadata API

import springernature_api_client.metadata as metadata
from springernature_api_client.utils import results_to_dataframe

metadata_client = metadata.MetadataAPI(api_key="your_api_key")
response = metadata_client.search(q='keyword:"cancer"', p=20, s=1, fetch_all=False, is_premium=False)
df = results_to_dataframe(response, export_to_excel=True)
print(df.head())

3️⃣ Open Access API

import springernature_api_client.openaccess as openaccess
from springernature_api_client.utils import results_to_dataframe

openaccess_client = openaccess.OpenAccessAPI(api_key="your_api_key")
response = openaccess_client.search(q='keyword:"cancer"', p=20, s=1, fetch_all=False, is_premium=False)
df = results_to_dataframe(response, export_to_excel=True)
print(df.head())

4️⃣ TDM (Text & Data Mining) API

import springernature_api_client.tdm as tdm

tdm_client = tdm.TDMAPI(api_key="your_api_key/your_api_metric")
response = tdm_client.search(q='keyword:"cancer"', p=20, s=1, fetch_all=False, is_premium=False)
file_path = tdm_client.save_xml(response, "output_tdm.xml")
print(f"✅ XML saved successfully to {file_path}")

🔄 Pagination Handling (fetch_all=True)

If fetch_all=True, the API will automatically paginate through results.

response = metadata_client.search(q='keyword:"cancer"', p=20, s=1, fetch_all=False, is_premium=False)

📤 Exporting to Excel

By default, results_to_dataframe() saves the results as an Excel file:

df = results_to_dataframe(response, export_to_excel=True, filename="output.xlsx")

💾 Saving XML Content (TDM API)

The TDM API save_xml() method formats and saves XML responses:

file_path = tdm_client.save_xml(xml_response, "output_tdm.xml")

🛠 Troubleshooting

1️⃣ Invalid API Key

Ensure you pass the correct API key. Try setting the API key as an environment variable.

2️⃣ Rate Limit Exceeded (Error 429)

Springer Nature API limits requests per minute. If you hit the limit, wait or request a higher quota.

3️⃣ Connection Timeout

If requests timeout, check your internet connection. Try increasing the timeout value in the request.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

👨‍💻 Contributing

We welcome contributions! See CONTRIBUTING.md for details. 🚀