Public API Guide

Welcome to the Electrospinning Data Public API.

This read-only API provides programmatic access to standardized electrospinning records, including polymers, solvents, morphologies, process parameters, and associated metadata.

[!IMPORTANT] New: Official Python Client
We now provide a dedicated Python library for easier data retrieval and analysis. Check out the Python Client Guide for a quick start.

All public API requests are served from the following base URL:

https://api.electrospinning-data.org/public/dataset

Endpoints Summary

Endpoint	Method	Description
`/` or `/latest`	`GET`	Fetch the latest dataset records (JSON, paginated).
`/versions`	`GET`	Retrieve a list of all available version snapshots.
`/{version}`	`GET`	Fetch dataset records from a specific version snapshot.
`/export`	`GET`	Export the latest dataset in `xlsx`, `json`, or `zip` format.
`/{version}/export`	`GET`	Export specific version snapshots in `xlsx`, `json`, or `zip` formats.

1. Fetching Data

Retrieve paginated and filterable records from the latest dataset release or from a specific version snapshot.

Query Parameters

Parameter	Default	Description
`skip`	`0`	Number of records to skip before returning results.
`limit`	`100`	Maximum number of records to return.
`filter`	—	URL-encoded JSON string containing filter criteria.

Basic Request Examples

cURL
Python
R

# Fetch the first 50 records from the latest dataset
curl -G "https://api.electrospinning-data.org/public/dataset" \
  --data-urlencode "skip=0" \
  --data-urlencode "limit=50"

import requests

# Base URL for the public read-only API
url = "https://api.electrospinning-data.org/public/dataset"

params = {
    "skip": 0,
    "limit": 50
}

response = requests.get(url, params=params, timeout=30)
response.raise_for_status()

data = response.json()

print(f"Retrieved {len(data['data'])} records")
print(f"Total available records: {data['total']}")

library(httr)
library(jsonlite)

# Base URL for versioned dataset records
url <- "https://api.electrospinning-data.org/public/dataset"

response <- GET(
  url,
  query = list(
    skip = 0,
    limit = 50
  )
)

stop_for_status(response)

data <- content(response, as = "parsed")

cat("Retrieved", length(data$data), "records\n")
cat("Total available:", data$total, "\n")

2. Exporting Data

Download the complete dataset or filtered subsets in research-ready formats.

Supported Formats

Format	Description
`xlsx`	Excel spreadsheet export
`json`	Full structured dataset
`zip`	Associated image archive

Export Examples

cURL
Python
R

# Export the latest dataset records as Excel
curl -L "https://api.electrospinning-data.org/public/dataset/export?format=xlsx" \
  -o electrospinning_dataset_latest.xlsx

# Export the latest dataset records as JSON
curl -L "https://api.electrospinning-data.org/public/dataset/export?format=json" \
  -o electrospinning_dataset_latest.json

# Export image version snapshot v1.0.0
curl -L "https://api.electrospinning-data.org/public/dataset/v1.0.0/export?format=zip" \
  -o electrospinning_images_v1.0.0.zip

import json
import requests

# Export filtered dataset records
url = "https://api.electrospinning-data.org/public/dataset/export"

filters = {
    "polymer": "PAN"
}

params = {
    "format": "xlsx",
    "filter": json.dumps(filters)
}

response = requests.get(url, params=params, timeout=60)
response.raise_for_status()

output_file = "pan_dataset.xlsx"

with open(output_file, "wb") as f:
    f.write(response.content)

print(f"Saved: {output_file}")

library(httr)
library(jsonlite)

# Export filtered dataset records using R
url <- "https://api.electrospinning-data.org/public/dataset/export"
filters <- list(polymer = "PAN")

response <- GET(
  url,
  query = list(
    format = "xlsx",
    filter = toJSON(filters, auto_unbox = TRUE)
  )
)

stop_for_status(response)

output_file <- "pan_dataset.xlsx"

writeBin(
  content(response, "raw"),
  output_file
)

cat("Saved:", output_file, "\n")

3. Versioning and Reproducibility

The Electrospinning Data platform maintains immutable version snapshots to support reproducible research and long-term citation stability.

Each version represents a fixed state of the dataset at a specific time.

Retrieving Available Versions

Use the following endpoint to list all available dataset versions:

# Retrieve all available version snapshots
curl "https://api.electrospinning-data.org/public/dataset/versions"

Example Response

[
  {
    "versionIdentifier": "v1.0.0",
    "recordCount": 5420,
    "createdAt": "2024-05-10T12:00:00Z"
  },
  {
    "versionIdentifier": "v0.9-beta",
    "recordCount": 1200,
    "createdAt": "2023-11-20T09:30:00Z"
  }
]

Accessing a Specific Version

Once you obtain a version identifier, include it directly in the request path:

https://api.electrospinning-data.org/public/dataset/v1.0.0

4. Filtering Reference

The filter parameter accepts a JSON object.

Multiple filters can be combined within a single request.

Python Users: Instead of manually constructing JSON objects, you can use the FilterBuilder provided by our official electrospinning-data-client library for a fluent and type-safe experience.
from electrospinning_data_client import FilterBuilder
filters = (FilterBuilder()
           .polymer("PAN")
           .voltage(min_val=20, max_val=30)
           .build())

String Filters

Key	Description
`doi`	Search by publication DOI
`polymer`	Case-insensitive search in polymer names
`solvent`	Case-insensitive search in solvent names
`collectorType`	Filter by collector type (e.g., Rotating, Flat)
`needleType`	Filter by needle type (e.g., Single, Coaxial)
`morphology`	Search in morphology labels
`instability`	Search in jet instability labels
`status`	Filter by record status (e.g., PUBLISHED)
`isFormationStable`	Filter using `yes` or `no`
`fractureBehaviour`	Filter by fracture description

Numeric Range Filters

Use Min and Max suffixes for range-based filtering.

General & Process Parameters

Feature	Minimum Key	Maximum Key	Unit
Voltage	`voltageMin`	`voltageMax`	kV
Flow rate	`flowRateMin`	`flowRateMax`	mL/h
Distance	`tipDistMin`	`tipDistMax`	cm
Concentration	`concentrationMin`	`concentrationMax`	wt%
Temperature	`tempMin`	`tempMax`	°C
Humidity	`humidityMin`	`humidityMax`	%
Needle Diameter	`needleDiameterMin`	`needleDiameterMax`	mm

Fiber & Product Properties

Feature	Minimum Key	Maximum Key	Unit
Fiber diameter	`fiberDiameterMin`	`fiberDiameterMax`	nm
Diameter Variation	`variationMin`	`variationMax`	%
Product Weight	`weightMin`	`weightMax`	g/m²

Mechanical Properties

Feature	Minimum Key	Maximum Key	Unit
Tensile Strength	`tensileStrengthMin`	`tensileStrengthMax`	MPa
Modulus	`modulusMin`	`modulusMax`	MPa
Elongation at Break	`elongationAtBreakMin`	`elongationAtBreakMax`	%

Functional Properties

Feature	Minimum Key	Maximum Key	Unit
Surface Area	`surfaceAreaMin`	`surfaceAreaMax`	m²/g
Porosity	`porosityMin`	`porosityMax`	%
Permeability	`permeabilityMin`	`permeabilityMax`	cm²
Wettability	`wettabilityMin`	`wettabilityMax`	°
Electrical Conductivity	`electricalConductivityMin`	`electricalConductivityMax`	S/m
Thermal Conductivity	`thermalConductivityMin`	`thermalConductivityMax`	W/mK

Filtering Example

Find PAN produced between 20–30 kV

{
  "polymer": "PAN",
  "voltageMin": 20,
  "voltageMax": 30
}

Example Filtered Request

cURL
Python
R

# Filter dataset records for PAN
curl -G "https://api.electrospinning-data.org/public/dataset" \
  --data-urlencode 'filter={"polymer":"PAN","voltageMin":20,"voltageMax":30}'

import json
import requests

# Base URL for public dataset records
url = "https://api.electrospinning-data.org/public/dataset"

filters = {
    "polymer": "PAN",
    "voltageMin": 20,
    "voltageMax": 30
}

response = requests.get(
    url,
    params={"filter": json.dumps(filters)}
)

data = response.json()

print(f"Retrieved {len(data['data'])} records")

library(httr)
library(jsonlite)

# Query filtered dataset records
url <- "https://api.electrospinning-data.org/public/dataset"
filters <- list(
  polymer = "PAN",
  voltageMin = 20,
  voltageMax = 30
)

response <- GET(
  url,
  query = list(
    filter = toJSON(filters, auto_unbox = TRUE)
  )
)

data <- content(response, as = "parsed")

cat("Retrieved", length(data$data), "records\n")

Rate Limiting

The public API enforces IP-based rate limits to ensure fair usage and platform stability.

If you receive a 429 Too Many Requests response:

Reduce request frequency
Avoid aggressive polling
Implement retry logic with exponential backoff where appropriate

Citation and Reproducibility

For reproducible research workflows, it is recommended to:

Reference a specific dataset version in publications
Archive exported datasets alongside analysis scripts
Include API query parameters in supplementary materials where relevant

Support

Website: https://electrospinning-data.org
GitHub: https://github.com
LinkedIn: https://linkedin.com

Endpoints Summary​

1. Fetching Data

Query Parameters​

Basic Request Examples​

2. Exporting Data

Supported Formats​

Export Examples​

3. Versioning and Reproducibility

Retrieving Available Versions​

Example Response​

Accessing a Specific Version​