Parameter-based Queries

This section documents the parameter-based style of the Graph API: you filter by adding one query parameter per filter, and most fields accept inline AND / OR / NOT expressions within a single parameter.

https://api.openaire.eu/graph/v3/research-products?type=publication&fromPublicationYear=2023

This is the style carried over from the earlier versions of the API, so it is the closest match if you are coming from one of them. If you would rather express all filters in a single compact expression, see Filter-based Queries instead.

New here? Jump to the Quickstart.

Endpoints

Each entity is exposed under its own path:

Entity	Search endpoint	Single entity
Research products	GET /v3/research-products	GET /v3/research-products/{id}
Organizations	GET /v3/organizations	GET /v3/organizations/{id}
Data sources	GET /v3/datasources	GET /v3/datasources/{id}
Projects	GET /v3/projects	GET /v3/projects/{id}
Persons	GET /v3/persons	GET /v3/persons/{id}

Filters combine with AND by default, and most text/identifier fields accept inline AND / OR / NOT expressions. The top-level logicalOperator (default AND) controls how different fields combine. Paging is the same across all five endpoints.

Current version

The current version of the parameter-based API is V3, served under /v3 and documented throughout this section. You can access the Swagger documentation at Swagger UI.

V3 supersedes V1 and V2, which are deprecated. It keeps the same parameter-based query style, so most existing V1/V2 calls translate with only minor changes, while adding a substantially larger set of filters, new entity fields, and consistent endpoint paths and value formats across all entities. The rest of this page summarizes what changed, for anyone migrating. For the release-by-release history, see the Changelog.

Endpoint paths

All entities are now served under a single, consistently named lowercase /v3 path. Notably, Persons is promoted from a V1-only endpoint to a first-class endpoint.

Entity	V1/V2 endpoint	V3 endpoint
Research products	GET /v2/researchProducts	GET /v3/research-products
Organizations	GET /v1/organizations	GET /v3/organizations
Data sources	GET /v1/dataSources	GET /v3/datasources
Projects	GET /v1/projects	GET /v3/projects
Persons	GET /v1/persons	GET /v3/persons

The query conventions are unchanged.

Renamed parameters (research products)

A few filters were renamed and their accepted values made more readable:

V1/V2	V3	What changed
authorOrcid	authorId	Generalized to any author identifier (ORCIDs still work).
bestOpenAccessRightLabel	accessRightLabel	Values are now human-readable: Open Access, Closed Access, Restricted, Open Source, Embargo, Unknown (previously OPEN, CLOSED, EMBARGO, …).
sdg	sdgLabel	Now a label such as 13. Climate action instead of an integer 1–17. See the list of values.

New filters

Research products

New filters (full reference):

• Year-based dates — fromPublicationYear, toPublicationYear and publicationYear, complementing the existing date-based fromPublicationDate / toPublicationDate.
• Date-range negation — excludePubDateRange, which inverts a fromPublicationDate / toPublicationDate range (it applies to the date filters, not the year ones).
• Content — language, hasLicense, eoscIfGuidelines.
• Funding hierarchy — relFunder, relFundingLevel0Id, relFundingLevel1Id, relFundingLevel2Id.
• Relations by name (not just id) — relOrganization, relProject, relHostingDataSource, relCommunityName.
• Communities — subCommunity.
• Data source — source (match products collected from or hosted by a data source).

Data sources

New filters (full reference):

• collectedFromName, country, thematic, jurisdiction, eoscdatasourcetype, odLanguages, compatibilityId, compatibilityName.

Projects

New filters (full reference):

• Year-based dates — fromStartYear, toStartYear, fromEndYear, toEndYear, startYear, endYear, activeYear (in addition to the existing date-based fromStartDate / toStartDate / fromEndDate / toEndDate).
• Funding — funder, fundinglevel0Id, fundinglevel1Id, fundinglevel2Id.
• Other — country, projectOAMandatePublications.

Organizations & Persons

The set of filters is unchanged from V1; only the endpoint path moved (organizations, persons).

Cross-cutting themes

• Consistent paths — every entity (including Persons) is now under /v3 with uniform path naming.
• Filter by year, not only by full date, for research products and projects.
• Funding-stream hierarchy filters (levels 0–2) for research products and projects.
• Filter by related-entity name in addition to id (organizations, projects, data sources, communities, funders).
• Readable value formats for access rights and SDGs.