Struct PubMedClient

Source

pub struct PubMedClient { /* private fields */ }

Expand description

Client for interacting with PubMed API

Implementations§

Source §

impl PubMedClient

Source

pub async fn get_related_articles( &self, pmids: &[u32], ) -> Result<RelatedArticles>

Get related articles for given PMIDs

§Arguments

pmids - List of PubMed IDs to find related articles for

§Returns

Returns a Result<RelatedArticles> containing related article information

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let related = client.get_related_articles(&[31978945]).await?;
    println!("Found {} related articles", related.related_pmids.len());
    Ok(())
}

Source

pub async fn get_pmc_links(&self, pmids: &[u32]) -> Result<PmcLinks>

Get PMC links for given PMIDs (full-text availability)

§Arguments

pmids - List of PubMed IDs to check for PMC availability

§Returns

Returns a Result<PmcLinks> containing PMC IDs with full text available

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let pmc_links = client.get_pmc_links(&[31978945]).await?;
    println!("Found {} PMC articles", pmc_links.pmc_ids.len());
    Ok(())
}

Source

pub async fn get_citations(&self, pmids: &[u32]) -> Result<Citations>

Get citing articles for given PMIDs

This method retrieves articles that cite the specified PMIDs from the PubMed database. The citation count returned represents only citations within the PubMed database (peer-reviewed journal articles indexed in PubMed).

§Important Note on Citation Counts

The citation count from this method may be lower than counts from other sources like Google Scholar, Web of Science, or scite.ai because:

PubMed citations (this method): Only includes peer-reviewed articles in PubMed
Google Scholar/scite.ai: Includes preprints, books, conference proceedings, and other sources

For example, PMID 31978945 shows:

PubMed (this API): ~14,000 citations (PubMed database only)
scite.ai: ~23,000 citations (broader sources)

This is expected behavior - this method provides accurate PubMed-specific citation data.

§Arguments

pmids - List of PubMed IDs to find citing articles for

§Returns

Returns a Result<Citations> containing citing article information

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let citations = client.get_citations(&[31978945]).await?;
    println!("Found {} citing articles in PubMed", citations.citing_pmids.len());
    Ok(())
}

Source §

impl PubMedClient

Source

pub async fn spell_check(&self, term: &str) -> Result<SpellCheckResult>

Check spelling of a search term using the ESpell API

Provides spelling suggestions for terms within a single text query. Useful as a preprocessing step before executing actual searches to improve search accuracy.

§Arguments

term - The search term to spell-check

§Returns

Returns a Result<SpellCheckResult> containing the original query, corrected query, and detailed information about which terms were corrected.

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let result = client.spell_check("asthmaa OR alergies").await?;

    println!("Original: {}", result.query);
    println!("Corrected: {}", result.corrected_query);

    if result.has_corrections() {
        println!("Replacements: {:?}", result.replacements());
    }

    Ok(())
}

Source

pub async fn spell_check_db( &self, term: &str, db: &str, ) -> Result<SpellCheckResult>

Check spelling of a search term against a specific database using the ESpell API

Spelling suggestions are database-specific, so use the same database you plan to search.

§Arguments

term - The search term to spell-check
db - The NCBI database to check against (e.g., “pubmed”, “pmc”)

§Returns

Returns a Result<SpellCheckResult> containing spelling suggestions

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let result = client.spell_check_db("fiberblast cell grwth", "pmc").await?;
    println!("Corrected: {}", result.corrected_query);
    Ok(())
}

Source §

impl PubMedClient

Source

pub async fn search_with_history( &self, query: &str, limit: usize, ) -> Result<SearchResult>

Search for articles with history server support

This method enables NCBI’s history server feature, which stores search results on the server and returns WebEnv/query_key identifiers. These can be used with fetch_from_history() to efficiently paginate through large result sets.

§Arguments

query - Search query string
limit - Maximum number of PMIDs to return in the initial response

§Returns

Returns a Result<SearchResult> containing PMIDs and history session information

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let result = client.search_with_history("covid-19", 100).await?;

    println!("Total results: {}", result.total_count);
    println!("First batch: {} PMIDs", result.pmids.len());

    // Use history session to fetch more results
    if let Some(session) = result.history_session() {
        let next_batch = client.fetch_from_history(&session, 100, 100).await?;
        println!("Next batch: {} articles", next_batch.len());
    }

    Ok(())
}

Source

pub async fn search_with_history_and_options( &self, query: &str, limit: usize, sort: Option<&SortOrder>, ) -> Result<SearchResult>

Search for articles with history server support and sort options

This method enables NCBI’s history server feature, which stores search results on the server and returns WebEnv/query_key identifiers. These can be used with fetch_from_history() to efficiently paginate through large result sets.

Also returns query translation showing how PubMed interpreted the query.

§Arguments

query - Search query string
limit - Maximum number of PMIDs to return in the initial response
sort - Optional sort order for results

§Returns

Returns a Result<SearchResult> containing PMIDs, history session, and query translation

§Example

use pubmed_client::{PubMedClient, pubmed::SortOrder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let result = client
        .search_with_history_and_options("asthma", 100, Some(&SortOrder::PublicationDate))
        .await?;

    println!("Total results: {}", result.total_count);
    if let Some(translation) = &result.query_translation {
        println!("Query interpreted as: {}", translation);
    }
    Ok(())
}

Source

pub async fn epost(&self, pmids: &[&str]) -> Result<EPostResult>

Upload a list of PMIDs to the NCBI History server using EPost

This stores the UIDs on the server and returns WebEnv/query_key identifiers that can be used with fetch_from_history() to retrieve article metadata.

This is useful when you have a pre-existing list of PMIDs (e.g., from a file, database, or external source) and want to use them with history server features like batch fetching.

§Arguments

pmids - Slice of PubMed IDs as strings

§Returns

Returns a Result<EPostResult> containing WebEnv and query_key

§Errors

ParseError::InvalidPmid - If any PMID is invalid
PubMedError::RequestError - If the HTTP request fails
PubMedError::ApiError - If the NCBI API returns an error

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();

    // Upload PMIDs to the history server
    let result = client.epost(&["31978945", "33515491", "25760099"]).await?;

    println!("WebEnv: {}", result.webenv);
    println!("Query Key: {}", result.query_key);

    // Use the session to fetch articles
    let session = result.history_session();
    let articles = client.fetch_from_history(&session, 0, 100).await?;
    println!("Fetched {} articles", articles.len());

    Ok(())
}

Source

pub async fn epost_to_session( &self, pmids: &[&str], session: &HistorySession, ) -> Result<EPostResult>

Upload PMIDs to an existing History server session using EPost

This appends UIDs to an existing WebEnv session, allowing you to combine multiple sets of IDs into a single session for subsequent operations.

§Arguments

pmids - Slice of PubMed IDs as strings
session - Existing history session to append to

§Returns

Returns a Result<EPostResult> with the updated session information. The returned webenv will be the same as the input session, and a new query_key will be assigned for the uploaded IDs.

Source

pub async fn fetch_from_history( &self, session: &HistorySession, start: usize, max: usize, ) -> Result<Vec<PubMedArticle>>

Fetch articles from history server using WebEnv session

This method retrieves articles from a previously executed search using the history server. It’s useful for paginating through large result sets without re-running the search query.

§Arguments

session - History session containing WebEnv and query_key
start - Starting index (0-based) for pagination
max - Maximum number of articles to fetch

§Returns

Returns a Result<Vec<PubMedArticle>> containing the fetched articles

§Note

WebEnv sessions typically expire after 1 hour of inactivity.

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();

    // First, search with history
    let result = client.search_with_history("cancer treatment", 100).await?;

    if let Some(session) = result.history_session() {
        // Fetch articles 100-199
        let batch2 = client.fetch_from_history(&session, 100, 100).await?;
        println!("Fetched {} articles", batch2.len());

        // Fetch articles 200-299
        let batch3 = client.fetch_from_history(&session, 200, 100).await?;
        println!("Fetched {} more articles", batch3.len());
    }

    Ok(())
}

Source

pub async fn fetch_all_by_pmids( &self, pmids: &[&str], ) -> Result<Vec<PubMedArticle>>

Fetch all articles for a list of PMIDs using EPost and the History server

This is the recommended method for fetching large numbers of articles by PMID. It uploads the PMID list to the History server via EPost (using HTTP POST to avoid URL length limits), then fetches articles in batches using pagination.

For small lists (up to ~200 PMIDs), fetch_articles() works fine. Use this method when you have hundreds or thousands of PMIDs.

§Arguments

pmids - Slice of PubMed IDs as strings

§Returns

Returns a Result<Vec<PubMedArticle>> containing all fetched articles

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();

    // Works efficiently even with thousands of PMIDs
    let pmids: Vec<&str> = vec!["31978945", "33515491", "25760099"];
    let articles = client.fetch_all_by_pmids(&pmids).await?;
    println!("Fetched {} articles", articles.len());

    Ok(())
}

Source

pub fn search_all( &self, query: &str, batch_size: usize, ) -> impl Stream<Item = Result<PubMedArticle>> + '_

Search and stream all matching articles using history server

This method performs a search and returns a stream that automatically paginates through all results using the NCBI history server. It’s ideal for processing large result sets without loading all articles into memory.

§Arguments

query - Search query string
batch_size - Number of articles to fetch per batch (recommended: 100-500)

§Returns

Returns a Stream that yields Result<PubMedArticle> for each article

§Example

use pubmed_client::PubMedClient;
use futures_util::StreamExt;
use std::pin::pin;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();

    let stream = client.search_all("cancer biomarker", 100);
    let mut stream = pin!(stream);
    let mut count = 0;

    while let Some(result) = stream.next().await {
        match result {
            Ok(article) => {
                count += 1;
                println!("{}: {}", article.pmid, article.title);
            }
            Err(e) => eprintln!("Error: {}", e),
        }

        // Stop after 1000 articles
        if count >= 1000 {
            break;
        }
    }

    println!("Processed {} articles", count);
    Ok(())
}

Source §

impl PubMedClient

Source

pub async fn fetch_summaries( &self, pmids: &[&str], ) -> Result<Vec<ArticleSummary>>

Fetch lightweight article summaries by PMIDs using the ESummary API

Returns basic metadata (title, authors, journal, dates, DOI) without abstracts, MeSH terms, or chemical lists. Faster than fetch_articles() when you only need bibliographic overview data.

§Arguments

pmids - Slice of PubMed IDs as strings

§Returns

Returns a Result<Vec<ArticleSummary>> containing lightweight article metadata

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let summaries = client.fetch_summaries(&["31978945", "33515491"]).await?;
    for summary in &summaries {
        println!("{}: {} ({})", summary.pmid, summary.title, summary.pub_date);
    }
    Ok(())
}

Source

pub async fn fetch_summary(&self, pmid: &str) -> Result<ArticleSummary>

Fetch a single article summary by PMID using the ESummary API

§Arguments

pmid - PubMed ID as a string

§Returns

Returns a Result<ArticleSummary> containing lightweight article metadata

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let summary = client.fetch_summary("31978945").await?;
    println!("{}: {}", summary.pmid, summary.title);
    Ok(())
}

Source

pub async fn search_and_fetch_summaries( &self, query: &str, limit: usize, sort: Option<&SortOrder>, ) -> Result<Vec<ArticleSummary>>

Search and fetch lightweight summaries in a single operation

Combines search_articles() and fetch_summaries(). Use this when you only need basic metadata (title, authors, journal, dates) and want faster retrieval than search_and_fetch().

§Arguments

query - Search query string
limit - Maximum number of articles to fetch

§Returns

Returns a Result<Vec<ArticleSummary>> containing lightweight article metadata

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let summaries = client.search_and_fetch_summaries("covid-19 treatment", 20, None).await?;
    for summary in &summaries {
        println!("{}: {}", summary.pmid, summary.title);
    }
    Ok(())
}

Source §

impl PubMedClient

Source

pub fn search(&self) -> SearchQuery

Create a search query builder for this client

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let articles = client
        .search()
        .query("covid-19 treatment")
        .free_full_text_only()
        .published_after(2020)
        .limit(10)
        .search_and_fetch(&client)
        .await?;

    println!("Found {} articles", articles.len());
    Ok(())
}

Source

pub fn new() -> Self

Create a new PubMed client with default configuration

Uses default NCBI rate limiting (3 requests/second) and no API key. For production use, consider using with_config() to set an API key.

§Example

use pubmed_client::PubMedClient;

let client = PubMedClient::new();

Source

pub fn with_config(config: ClientConfig) -> Self

Create a new PubMed client with custom configuration

§Arguments

config - Client configuration including rate limits, API key, etc.

§Example

use pubmed_client::{PubMedClient, ClientConfig};

let config = ClientConfig::new()
    .with_api_key("your_api_key_here")
    .with_email("researcher@university.edu");

let client = PubMedClient::with_config(config);

Source

pub fn with_client(client: Client) -> Self

Create a new PubMed client with custom HTTP client and default configuration

§Arguments

client - Custom reqwest client with specific configuration

§Example

use pubmed_client::PubMedClient;
use reqwest::Client;
use std::time::Duration;

let http_client = Client::builder()
    .timeout(Duration::from_secs(30))
    .build()
    .unwrap();

let client = PubMedClient::with_client(http_client);

Source

pub async fn fetch_article(&self, pmid: &str) -> Result<PubMedArticle>

Fetch article metadata by PMID with full details including abstract

§Arguments

pmid - PubMed ID as a string

§Returns

Returns a Result<PubMedArticle> containing the article metadata with abstract

§Errors

ParseError::ArticleNotFound - If the article is not found
PubMedError::RequestError - If the HTTP request fails
ParseError::JsonError - If JSON parsing fails

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let article = client.fetch_article("31978945").await?;
    println!("Title: {}", article.title);
    if let Some(abstract_text) = &article.abstract_text {
        println!("Abstract: {}", abstract_text);
    }
    Ok(())
}

Source

pub async fn search_articles( &self, query: &str, limit: usize, sort: Option<&SortOrder>, ) -> Result<Vec<String>>

Search for articles using a query string

§Arguments

query - Search query string
limit - Maximum number of results to return
sort - Optional sort order for results

§Returns

Returns a Result<Vec<String>> containing PMIDs of matching articles

§Errors

PubMedError::RequestError - If the HTTP request fails
ParseError::JsonError - If JSON parsing fails

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let pmids = client.search_articles("covid-19 treatment", 10, None).await?;
    println!("Found {} articles", pmids.len());
    Ok(())
}

Source

pub async fn fetch_articles(&self, pmids: &[&str]) -> Result<Vec<PubMedArticle>>

Fetch multiple articles by PMIDs in a single batch request

This method sends a single EFetch request with multiple PMIDs (comma-separated), which is significantly more efficient than fetching articles one by one. For large numbers of PMIDs, the request is automatically split into batches.

§Arguments

pmids - Slice of PubMed IDs as strings

§Returns

Returns a Result<Vec<PubMedArticle>> containing articles with metadata. Articles that fail to parse are skipped (logged via tracing).

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let articles = client.fetch_articles(&["31978945", "33515491", "25760099"]).await?;
    for article in &articles {
        println!("{}: {}", article.pmid, article.title);
    }
    Ok(())
}

Source

pub async fn search_and_fetch( &self, query: &str, limit: usize, sort: Option<&SortOrder>, ) -> Result<Vec<PubMedArticle>>

Search and fetch multiple articles with metadata

Uses batch fetching internally for efficient retrieval.

§Arguments

query - Search query string
limit - Maximum number of articles to fetch

§Returns

Returns a Result<Vec<PubMedArticle>> containing articles with metadata

§Example

use pubmed_client::PubMedClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let articles = client.search_and_fetch("covid-19", 5, None).await?;
    for article in articles {
        println!("{}: {}", article.pmid, article.title);
    }
    Ok(())
}

Trait Implementations§

Source §

impl Clone for PubMedClient

Source §

fn clone(&self) -> PubMedClient

Returns a duplicate of the value. Read more

1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Source §

impl Default for PubMedClient

Source §

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl !UnwindSafe for PubMedClient

Blanket Implementations§

Source §

impl<T> Any for T
where T: 'static + ?Sized,

Source §

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

Source §

impl<T> Borrow<T> for T
where T: ?Sized,

Source §

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

Source §

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source §

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

Source §

impl<T> CloneToUninit for T
where T: Clone,

Source §

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)

Performs copy-assignment from self to dest. Read more

Source §

impl<T> From<T> for T

Source §

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more

§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Source §

impl<T, U> Into for T
where U: From<T>,

Source §

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source §

impl<T> IntoEither for T

Source §

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

§