PhysioNet APIphysionet.org ↗
Access PhysioNet datasets, file listings, and text content via API. Search 5 endpoints for biomedical research data including ECG, EEG, and clinical records.
What is the PhysioNet API?
The PhysioNet API exposes 5 endpoints for discovering and accessing biomedical research datasets hosted at physionet.org. With search_resources you can query across data, software, challenges, and models by keyword and filter by resource type. get_dataset_detail returns full metadata including DOI, abstract, authors, and citation text, while list_dataset_files and get_file_content let you browse and read files from Open Access datasets without manual navigation.
curl -X GET 'https://api.parse.bot/scraper/b9587d03-0081-4ee2-85d5-1077ef6da7b6/search_resources?page=1&query=ECG&types=%5B0%5D&orderby=relevance-desc' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace physionet-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: PhysioNet SDK — search datasets, inspect metadata, browse and read files."""
from parse_apis.physionet_api import PhysioNet, Sort, DatasetNotFound
client = PhysioNet()
# Search for ECG-related datasets, sorted by newest first
for dataset in client.datasets.search(query="ECG", sort=Sort.PUBLISH_DATE_DESC, limit=5):
print(dataset.title, dataset.slug, dataset.version, dataset.access_level)
# Construct a known dataset and get its full detail
detail = client.dataset("mitdb").details(version="1.0.0")
print(detail.title, detail.doi, detail.published)
for author in detail.authors:
print(author)
# Browse files in that dataset
for f in client.dataset("mitdb").files.list(version="1.0.0", limit=10):
print(f.name, f.is_dir, f.size, f.date)
# Read a text file's content from the dataset
content = client.dataset("mitdb").files.get_content(version="1.0.0", filepath="RECORDS")
print(content.filepath, content.content[:100])
# Typed error handling: catch a missing dataset
try:
client.dataset("nonexistent-dataset-xyz").details(version="9.9.9")
except DatasetNotFound as exc:
print(f"Dataset not found: {exc}")
# List latest news items
for item in client.newsitems.list(limit=3):
print(item.title, item.date)
print("exercised: datasets.search / dataset.details / files.list / files.get_content / newsitems.list")
Search for PhysioNet resources (datasets, software, challenges, models) by keyword. Returns paginated results with metadata about each matching resource including title, slug, version, authors, description, tags, and access level. Paginates via integer page number. Server-side filtering is limited to query, type, and sort order.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| query | string | Search keyword or topic |
| types | string | JSON array of resource type integers to filter: 0=Data, 1=Software, 2=Challenge, 3=Model. Omitting returns all types. |
| orderby | string | Sort order for results |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"results": "array of resource objects with title, slug, version, url, authors, description, tags, pub_details, and access_level",
"total_pages": "integer, total number of pages available"
},
"sample": {
"data": {
"page": 1,
"results": [
{
"url": "https://physionet.org/content/mitdb/1.0.0/",
"slug": "mitdb",
"tags": [
"ecg",
"arrhythmia"
],
"title": "MIT-BIH Arrhythmia Database",
"authors": "George Moody, Roger Mark",
"version": "1.0.0",
"description": "ECG database.",
"pub_details": "Published: Feb. 24, 2005. Version: 1.0.0",
"access_level": "Open Access"
}
],
"total_pages": 14
},
"status": "success"
}
}About the PhysioNet API
Search and Discovery
The search_resources endpoint accepts a query string and an optional types parameter — a JSON array of integers where 0=Data, 1=Software, 2=Challenge, and 3=Model — letting you narrow results to a specific resource category. Results are paginated (page, total_pages) and sortable via orderby with options including relevance-desc, publish-date-desc, and title-asc. Each result object includes title, slug, version, authors, description, tags, pub_details, and access_level, giving you enough context to decide which resources to investigate further.
Dataset Metadata and File Access
get_dataset_detail takes a slug (e.g. mitdb, chbmit) and a version string and returns the full metadata record: doi, abstract, citation, authors, published, and title. This is the right endpoint for building citations or surfacing dataset provenance. list_dataset_files browses the file index of a dataset version and accepts an optional path parameter to descend into subdirectories; each file object includes name, is_dir, size, date, and url. Both list_dataset_files and get_file_content are restricted to Open Access datasets — credentialed or restricted datasets return an error.
File Content Retrieval and News
get_file_content retrieves the raw text of a specific file by filepath (e.g. RECORDS, subject-info.csv) within a given dataset slug and version. Returned content is capped at 100,000 characters and is only available for text-based files; binary files return an error. The list_news endpoint requires no inputs and returns all current PhysioNet announcements with date, title, and content fields — useful for monitoring new dataset releases or challenge announcements.
The PhysioNet API is a managed, monitored endpoint for physionet.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when physionet.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official physionet.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Catalog all ECG and EEG datasets on PhysioNet by searching with
types=[0]and filtering by relevant tags. - Programmatically generate dataset citations using the
citationanddoifields fromget_dataset_detail. - Build a dataset browser that lists files and subdirectories of any Open Access dataset using
list_dataset_files. - Read RECORDS or subject metadata CSV files directly using
get_file_contentwithout downloading the full dataset. - Monitor PhysioNet challenge announcements by polling
list_newsfor new entries. - Aggregate author contribution data across multiple datasets by collecting
authorsarrays fromget_dataset_detail. - Filter and sort datasets by publication date using the
publish-date-descorderby option insearch_resources.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does PhysioNet have an official developer API?+
What does `list_dataset_files` return, and when does it fail?+
name, is_dir, size, date, and url. You can browse subdirectories by passing a path parameter. It only works for Open Access datasets; any dataset requiring credentialed or restricted access returns an error instead of a file listing.Does the API expose download URLs for dataset files?+
files array from list_dataset_files includes a url field for each file, pointing to the file location on PhysioNet. Actual file download is done directly from that URL; the API does not proxy binary file transfers. Text file content can be retrieved inline via get_file_content, subject to the 100,000-character cap.Can I access datasets that require credentialed or restricted access?+
list_dataset_files and get_file_content — only work for Open Access datasets and return an error for restricted ones. The get_dataset_detail endpoint still returns metadata for any dataset by slug and version. You can fork this API on Parse and revise it to add credentialed-access endpoints if your use case requires them.Does the API return waveform or signal data from PhysioNet files?+
get_file_content. You can fork this API on Parse and revise it to add an endpoint that handles binary file retrieval or format-specific parsing.