Migration from Parameter-based Queries

This page helps you translate existing parameter-based API calls into the filter syntax documented in this section.

Parameter mapping

Parameter-based	Filter-based equivalent
type=publication&type=dataset (legacy arrays)	filter=type:publication|dataset
type=("publication" OR "dataset") (inline expression)	filter=type:publication|dataset
fromPublicationDate=2022&toPublicationDate=2023	filter=from_publication_date:2022,to_publication_date:2023
logicalOperator=AND (top-level)	Implicit: comma is AND, pipe is OR
includeStats=true	facets=type (or any fields you want)
sortBy=citationCount DESC	sort=citation_count:desc
mainTitle=neural network	filter=title.search:neural network
authorOrcid=0000-0002-...	filter=authorships.author.orcid:0000-0002-...
authorFullName=Paolo Manghi	filter=authorships.author.fullname:Paolo Manghi
relProjectFundingShortName=EC	filter=grants.funder_short_name:EC
hasProjectRel=true	filter=has_grant:true
relProjectId=...	filter=grants.project_id:...
relProjectCode=101017452	filter=grants.code:101017452
relOrganizationId=...	filter=affiliations.organization_id:...
relCommunityId=...	filter=communities.id:...
bestOpenAccessRightLabel=OPEN	filter=best_oa.rights:Open Access
influenceClass=C1	filter=impact.influence_class:C1
isPeerReviewed=true	filter=is_peer_reviewed:true
isGreen=true	filter=is_green:true
openAccessColor=gold	filter=oa_color:gold
countryCode=GR	filter=authorships.countries:GR
page=1&pageSize=10	page=1&page_size=10
cursor=*	cursor=* (same)

Key differences

Filter parameter

The parameter-based endpoints use 30+ individual query parameters. The filter-based endpoints collapse them into a single filter= parameter with field:value syntax. Multiple filters are comma-separated (AND logic), and pipe (|) is used for OR within a field.

Sort format

Parameter-based: sortBy=citationCount DESC (space-separated, camelCase)

Filter-based: sort=citation_count:desc (colon-separated, snake_case)

Page size

Parameter-based: pageSize=10 (camelCase)

Filter-based: page_size=10 (snake_case)

Aggregations

The parameter-based endpoints use includeStats=true, which returns a fixed set of statistics. The filter-based endpoints replace this with two flexible modes:

• facets=type,best_oa.rights — records + chosen aggregations
• group_by=type — aggregations only, no records

See Aggregations for details.

Sparse fieldsets

The filter-based endpoints add select= for requesting only specific response fields. This has no parameter-based equivalent.

See Sparse fieldsets for details.

Error handling

Code	When
400	Invalid filter syntax, unknown field, disallowed operator, mutual exclusion violation, pagination limit exceeded
404	Research product not found (by-ID endpoint)
500	Internal failure

Error response body:

{
  "status": 400,
  "message": "Unknown filter field: 'foo'"
}