# 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_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. 🚀
Raw data
{
"_id": null,
"home_page": null,
"name": "springernature-api-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "API, Springer Nature, client, requests",
"author": "Springer Nature",
"author_email": "supportapi@springernature.com",
"download_url": "https://files.pythonhosted.org/packages/45/69/afa6dde6fd160f4ef684c00c03337d0745b33c445ca02595d73edd348067/springernature_api_client-0.0.8.tar.gz",
"platform": null,
"description": "# Springer Nature API Client\n\n[](https://pypi.org/project/springernature-api-client/)\n[](https://pypi.org/project/springernature-api-client/)\n[](https://github.com/springernature/springernature_api_client/blob/main/LICENSE)\n\nA Python package to interact with the **Springer Nature API** for fetching metadata, open access articles, and text & data mining (TDM) content.\n\n---\n\n## \ud83d\ude80 Installation\n\n### Install Python\n\nEnsure you have Python installed (version 3.9+ recommended).\n\nWindows: Download from [python.org](https://www.python.org/downloads/) and install.\n\nmacOS: Install via Homebrew:\n\n```bash\nbrew install python\n```\n\nLinux: Install using package manager (e.g., apt for Debian/Ubuntu):\n\n```bash\nsudo apt update && sudo apt install python3 python3-venv python3-pip\n```\n\n### For Users\nTo install the package from PyPI(If you just want to use the package in your project):\n```bash\npip install springernature_api_client\n```\n\n### For Developers\nIf you're planning to contribute to the project:\n1. Install Poetry (dependency management tool)\nThis project uses Poetry for dependency management. Install Poetry if you haven't already:\n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n2. Clone the repository and install dependencies\n```bash\n git clone https://github.com/springernature/springernature_api_client.git\n cd springernature_api_client\n poetry install --with dev\n```\n3. Activate the virtual environment using Poetry:\n```bash\npoetry env use python\npoetry shell\n# or \npoetry env activate\n```\nSee [CONTRIBUTING.md](https://github.com/springernature/springernature_api_client/blob/main/CONTRIBUTING.md) for more details on the development workflow.\n\n## \ud83d\udd11 Setup\nBefore using the package, obtain an API key from Springer Nature Developer Portal.\n\nSet the API key in your environment:\n```python\nexport SPRINGER_API_KEY=\"your_api_key_here\"\n```\nOr pass it directly in Python:\n```python\napi_key = \"your_api_key_here\"\n```\n\n## \ud83d\udccc Basic Usage\n\nFetch Metadata and Export to Excel\n\n```python\nimport springernature_api_client.metadata as metadata\nfrom springernature_api_client.utils import results_to_dataframe\n\n# Initialize API Client\nmetadata_client = metadata.MetadataAPI(api_key=\"your_api_key\")\n\n# Fetch results (pagination enabled, stops at `s=200`)\nresponse = metadata_client.search(q='keyword:\"cancer\"', p=20, s=1, fetch_all=False, is_premium=False)\n\n# Convert API response to DataFrame & export to Excel\ndf = results_to_dataframe(response, export_to_excel=True, filename=\"articles.xlsx\")\n\nprint(df.head()) # Display first few rows\n```\n\n## \ud83d\udcda API Modules\n\n### 1\ufe0f\u20e3 Meta API\n\n```python\nimport springernature_api_client.meta as meta\nfrom springernature_api_client.utils import results_to_dataframe\n\nmeta_client = meta.MetaAPI(api_key=\"your_api_key\")\nresponse = meta_client.search(q='keyword:\"cancer\"', p=20, s=1, fetch_all=False, is_premium=False)\ndf = results_to_dataframe(response, export_to_excel=True)\nprint(df.head())\n```\n\n### 2\ufe0f\u20e3 Metadata API\n\n```python\nimport springernature_api_client.metadata as metadata\nfrom springernature_api_client.utils import results_to_dataframe\n\nmetadata_client = metadata.MetadataAPI(api_key=\"your_api_key\")\nresponse = metadata_client.search(q='keyword:\"cancer\"', p=20, s=1, fetch_all=False, is_premium=False)\ndf = results_to_dataframe(response, export_to_excel=True)\nprint(df.head())\n```\n\n### 3\ufe0f\u20e3 Open Access API\n\n```python\nimport springernature_api_client.openaccess as openaccess\nfrom springernature_api_client.utils import results_to_dataframe\n\nopenaccess_client = openaccess.OpenAccessAPI(api_key=\"your_api_key\")\nresponse = openaccess_client.search(q='keyword:\"cancer\"', p=20, s=1, fetch_all=False, is_premium=False)\ndf = results_to_dataframe(response, export_to_excel=True)\nprint(df.head())\n```\n\n### 4\ufe0f\u20e3 TDM (Text & Data Mining) API\n\n```python\nimport springernature_api_client.tdm as tdm\n\ntdm_client = tdm.TDMAPI(api_key=\"your_api_key/your_metric\")\nresponse = tdm_client.search(q='keyword:\"cancer\"', p=20, s=1, fetch_all=False, is_premium=False)\nfile_path = tdm_client.save_xml(response, \"output_tdm.xml\")\nprint(f\"\u2705 XML saved successfully to {file_path}\")\n```\n\n### \ud83d\udd04 Pagination Handling (fetch_all=True)\n\nIf fetch_all=True, the API will automatically paginate through results.\n\n```python\nresponse = metadata_client.search(q='keyword:\"cancer\"', p=20, s=1, fetch_all=False, is_premium=False)\n```\n\n## \ud83d\udce4 Exporting to Excel\n\nBy default, results_to_dataframe() saves the results as an Excel file:\n\n```python\ndf = results_to_dataframe(response, export_to_excel=True, filename=\"output.xlsx\")\n```\n\n## \ud83d\udcbe Saving XML Content (TDM API)\n\nThe TDM API save_xml() method formats and saves XML responses:\n\n```python\nfile_path = tdm_client.save_xml(xml_response, \"output_tdm.xml\")\n```\n\n## \ud83d\udee0 Troubleshooting\n\n### 1\ufe0f\u20e3 Invalid API Key\n\nEnsure you pass the correct API key.\nTry setting the API key as an environment variable.\n\n### 2\ufe0f\u20e3 Rate Limit Exceeded (Error 429)\n\nSpringer Nature API limits requests per minute.\nIf you hit the limit, wait or request a higher quota.\n\n### 3\ufe0f\u20e3 Connection Timeout\n\nIf requests timeout, check your internet connection.\nTry increasing the timeout value in the request.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License. See [LICENSE](https://github.com/springernature/springernature_api_client/blob/main/LICENSE) for details.\n\n## \ud83d\udc68\u200d\ud83d\udcbb Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](https://github.com/springernature/springernature_api_client/blob/main/CONTRIBUTING.md) for details. \ud83d\ude80\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Springer Nature API Client",
"version": "0.0.8",
"project_urls": null,
"split_keywords": [
"api",
" springer nature",
" client",
" requests"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cdb99ed2ff12dec5e8cbbd43af169a9c5275e9df876f482baf822ed9222a0b67",
"md5": "0047049467b42963e1fe160840a17890",
"sha256": "7cde07b0bb082c68dd5f3c413d3e8f2930b7aaaf15a6919973abc9da26600529"
},
"downloads": -1,
"filename": "springernature_api_client-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0047049467b42963e1fe160840a17890",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11808,
"upload_time": "2025-11-05T09:47:31",
"upload_time_iso_8601": "2025-11-05T09:47:31.379392Z",
"url": "https://files.pythonhosted.org/packages/cd/b9/9ed2ff12dec5e8cbbd43af169a9c5275e9df876f482baf822ed9222a0b67/springernature_api_client-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4569afa6dde6fd160f4ef684c00c03337d0745b33c445ca02595d73edd348067",
"md5": "4cbedf822c7f98bbb5055a5bf0909a82",
"sha256": "7fc196843ab286a12670ee9e35ce74a880b045d0291eb45d1b86c0dad425511f"
},
"downloads": -1,
"filename": "springernature_api_client-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "4cbedf822c7f98bbb5055a5bf0909a82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8520,
"upload_time": "2025-11-05T09:47:33",
"upload_time_iso_8601": "2025-11-05T09:47:33.128535Z",
"url": "https://files.pythonhosted.org/packages/45/69/afa6dde6fd160f4ef684c00c03337d0745b33c445ca02595d73edd348067/springernature_api_client-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 09:47:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "springernature-api-client"
}
JSON