https://github.com/springernature/springernature_api_client
A Python package to interact with the Springer Nature API for fetching metadata, open access articles, and text & data mining (TDM) content.
https://github.com/springernature/springernature_api_client
api-wrapper meta metadata openaccess opensource pypi pypi-package python3 tdm
Last synced: 4 months ago
JSON representation
A Python package to interact with the Springer Nature API for fetching metadata, open access articles, and text & data mining (TDM) content.
- Host: GitHub
- URL: https://github.com/springernature/springernature_api_client
- Owner: springernature
- License: mit
- Created: 2025-02-07T10:18:20.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-03T07:37:42.000Z (7 months ago)
- Last Synced: 2025-11-03T08:25:11.919Z (7 months ago)
- Topics: api-wrapper, meta, metadata, openaccess, opensource, pypi, pypi-package, python3, tdm
- Language: Python
- Homepage:
- Size: 135 KB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# Springer Nature API Client
[](https://pypi.org/project/springernature-api-client/)
[](https://pypi.org/project/springernature-api-client/)
[](https://github.com/springernature/springernature_api_client/blob/main/LICENSE)
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](https://www.python.org/downloads/) and install.
macOS: Install via Homebrew:
```bash
brew install python
```
Linux: Install using package manager (e.g., apt for Debian/Ubuntu):
```bash
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):
```bash
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:
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
2. Clone the repository and install dependencies
```bash
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:
```bash
poetry env use python
poetry shell
# or
poetry env activate
```
See [CONTRIBUTING.md](https://github.com/springernature/springernature_api_client/blob/main/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:
```python
export SPRINGER_API_KEY="your_api_key_here"
```
Or pass it directly in Python:
```python
api_key = "your_api_key_here"
```
## 📌 Basic Usage
Fetch Metadata and Export to Excel
```python
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
```python
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
```python
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
```python
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
```python
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.
```python
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:
```python
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:
```python
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](https://github.com/springernature/springernature_api_client/blob/main/LICENSE) for details.
## 👨💻 Contributing
We welcome contributions! See [CONTRIBUTING.md](https://github.com/springernature/springernature_api_client/blob/main/CONTRIBUTING.md) for details. 🚀