Struct ListParams 

pub struct ListParams {
    pub filter: Option<String>,
    pub search: Option<String>,
    pub sort: Option<String>,
    pub per_page: Option<u32>,
    pub page: Option<u32>,
    pub cursor: Option<String>,
    pub sample: Option<u32>,
    pub seed: Option<u32>,
    pub select: Option<String>,
    pub group_by: Option<String>,
}

Query parameters shared by all 7 list endpoints (works, authors, sources, institutions, topics, publishers, funders). All fields are optional.

Supports both struct-update syntax and the bon builder pattern:

use papers_openalex::ListParams;

// Struct-update syntax
let params = ListParams {
    search: Some("machine learning".into()),
    per_page: Some(10),
    ..Default::default()
};

// Builder syntax
let params = ListParams::builder()
    .search("machine learning")
    .filter("publication_year:2024,is_oa:true")
    .sort("cited_by_count:desc")
    .per_page(10)
    .page(1)
    .build();

Pagination

Two pagination modes are available (mutually exclusive):

• Offset pagination: set page (max page * per_page <= 10,000)
• Cursor pagination: set cursor to "*" for the first page, then pass ListMeta::next_cursor from the previous response. When next_cursor is None, there are no more results.

Sampling

Set sample to get a random sample instead of paginated results. Use seed for reproducibility.

Grouping

Set group_by to aggregate results by a field. The response will include a group_by array with key, display name, and count for each group.

Fields

filter: Option<String>

Filter expression. Comma-separated AND conditions, pipe (|) for OR (max 50 alternatives). Supports negation (!), comparison (>, <), and ranges (2020-2023).

Example: "publication_year:2024,is_oa:true" or "type:article|preprint"

search: Option<String>

Full-text search query. For works, searches across title, abstract, and fulltext. For other entities, searches display_name. Supports stemming and stop-word removal.

sort: Option<String>

Sort field with optional direction suffix. Append :desc for descending order. Multiple fields can be comma-separated.

Available fields: display_name, cited_by_count, works_count, publication_date, relevance_score (only with active search).

Example: "cited_by_count:desc"

per_page: Option<u32>

Results per page (1-200, default 25).

Note: the API query key is per-page (hyphenated); this field handles the mapping automatically.

page: Option<u32>

Page number for offset pagination. Maximum accessible: page * per_page <= 10,000. For deeper results, use cursor pagination.

cursor: Option<String>

Cursor for cursor-based pagination. Start with "*", then pass meta.next_cursor from the previous response. When next_cursor is None, there are no more results. Mutually exclusive with page.

sample: Option<u32>

Return a random sample of this many results instead of paginated results. Use with seed for reproducibility.

seed: Option<u32>

Seed value for reproducible random sampling. Only meaningful when sample is set.

select: Option<String>

Comma-separated list of fields to include in the response. Reduces payload size. Unselected fields will be omitted.

Example: "id,display_name,cited_by_count"

group_by: Option<String>

Aggregate results by a field and return counts. The response will include a group_by array with key, key_display_name, and count for each group.

Example: "type" groups works by article/preprint/etc.

Implementations

impl ListParams

pub fn builder() -> ListParamsBuilder

Create an instance of ListParams using the builder syntax

Trait Implementations

impl Clone for ListParams

fn clone(&self) -> ListParams

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ListParams

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ListParams

fn default() -> ListParams

Returns the “default value” for a type.