SciPROJ – API

The service of API of SciPROJ It was developed to provide data from the national register of Science and Technology (S&T) funding. SciPROJ, num formato de dados abertos. Baseada no modelo de dados Common European Research Information Format (CERIF) e alinhada com o perfil Perfil de dados adotado para publicação e integração europeia (OpenAIRE), a API SciPROJ It facilitates interoperability and data reuse, enabling a detailed analysis of the trends and impacts of public funding on the national scientific system.

Base URL
Two environments are available, one productive and the other for quality testing (QA).

Production:
• https://api.ptcris.pt/

• https://api.ptcris.pt/docs/ (Swagger documentation – Funding DB: Projects)

Testing (QA)
• https://etl.ptcris.pt/docs/

• https://etl.ptcris.pt/docs/ (Swagger documentation – Funding DB: Projects)

Version
The version available is v1.1

THE API of SciPROJ It is publicly and freely available to all entities belonging to the ecosystem. PTCRIS. O acesso é realizado com credenciais fornecidas pela plataforma, usando o método de autenticação Basic Authentication.

To request access credentials, the interested entity must send an email to identifiers.ptcris@fct.pt, including the following information about the subscribing entity:

• Name of the requesting entity or institution
• Entity URL
• Customer profile: public
• Name and email of the customer service manager

After receiving the access credentials, integrators will be able to begin developing the integration in the test environment. API. O ambiente de produção será disponibilizado aos integradores que concluírem os testes no ambiente de QA e implementarem as recomendações de uso, após validação da equipa PTCRIS.

Profile

Clients can access two types of profiles: the public profile, which allows them to view all public information about projects, and the private profile, which provides access to public and private data, including personal data (person entity), in compliance with the General Data Protection Regulation (GDPR) and other applicable legislation.

Permissions

The available permissions are read-only.

A estrutura de metadados de um currículo e de projetos financiados organiza-se segundo o modelo Formato de intercâmbio usado para interoperabilidade entre sistemas (CERIF-XML), seguindo as diretrizes definidas pela OpenAIRE. Esta estrutura agrupa a informação em vários blocos informativos fundamentais, nomeadamente:

• Project – Funded projects
• Funding – Financing data
• Person – People associated with the projects
• OrgUnit – Organizations associated with projects or funding
• Equipment – Equipment used in the execution of the project

These schemas ensure a standardized and interoperable description of the data, as specified in the guidelines. CERIF-XML from the OpenAIRE.

In the case of the database SciPROJ, o modelo CERIF-XML used for project description, made available through API, organiza cada registo num componente único que integra duas secções principais:

<header> which includes repository-level metadata, such as:

• <identifier> unique identifier of the record
• <datestamp> date and time of the last record update
• <setSpec> dataset or collection to which the record belongs

<metadata> It contains the main descriptive attributes of the project, including:

• <Project> with elements such as:
  • <Acronym> acronym for the project
  • <Title> Project title, with support for multiple languages (xml:lang)
  • <Identifier> External references, such as project code or funding program.
  • <StartDate> and <EndDate> start and end dates
  • <Subject> or <Keywords> Project knowledge areas or keywords

Together, this structure ensures a complete, coherent description aligned with international standards for scientific information management.

Metadata Extensions CERIF and OpenAIRE

Beyond the basic metadata structure, the system incorporates specific extensions that allow for a richer and more detailed representation of research activities. These extensions are in full compliance with the guidelines. CERIF-XML provided by OpenAIRE, garantindo que a informação científica seja facilmente partilhável e integrada em redes globais de conhecimento.

This metadata model is organized into fundamental blocks, such as Project (funded projects), Funding (funding data), and OrgUnit (associated organizations), ensuring that all components of the funding ecosystem are properly mapped.

The complete technical documentation and detailed guidelines for these extensions can be found at the official link: PTCRIS extensions to the CERIF/OpenAIRE profile

The methods that make up the web service can be consulted by accessing the Web Application Description Language (WADL). The web service and the web methods that make up the query of the project references of SciPROJ, podem ser consultados a partir do seguinte descritor:

https://api.ptcris.pt/services/searches/projects?_wadl

Methods of API SciPROJ

EndPoint: /projects
URI: https://api.ptcris.pt/services/searches/projects
DescriptionReturns all projects that meet the defined criteria, such as title, start and end dates, and organization.

—

EndPoint: /projects/{id}
URI: https://api.ptcris.pt/services/searches/projects/{id}
Description: Returns complete information about a project based on its unique ID.

—

EndPoint: /projects/all
URI: https://api.ptcris.pt/services/searches/projects/all
Description: Returns all project summary information in a ZIP file.

—

EndPoint: /projects/dump
URI: https://api.ptcris.pt/services/searches/projects/dump
Description: Returns all project information compiled weekly into a ZIP file, according to the filter criteria.

—

EndPoint: /projects/endDate
URI: https://api.ptcris.pt/services/searches/projects/endDate
Description: Returns information filtered by project completion date.

—

EndPoint: /projects/startDate
URI: https://api.ptcris.pt/services/searches/projects/startDate
Description: Returns information filtered by project start date.

For optimal use of API Throughout the community, the following usage practices are recommended:

• Caching of data to avoid repeated requests.
• Monitoring the use of API, com um máximo recomendado de 2 chamadas por segundo (120 por minuto).
• Report failures to the address identifiers.ptcris@fct.pt.

Uses that negatively affect the quality of the service, whether intentional or negligent, may result in restrictions or blocking of access.

Formats

THE API It returns results in XML and JSON formats, which can be specified by the client using the `accept` parameter in the request header.

Types of methods
THE API It only supports HTTP methods of type GET.

Response codes
The answer from API It may include various codes depending on the type of call made:

200 – Successful operation
400 – Invalid registration ID
403 – Invalid permissions to access the record(s)
404 – Record not found
500 – Operation error

Response codes in the 4-xx range must be handled during the integration process to ensure call normalization. API SciPROJ. Já os códigos de resposta na gama 5-x-x devem ser validados pelo integrador; caso não seja possível mitigar o problema, é necessário entrar em contacto com o suporte do PTCRIS via email ptcris@fccn.pt.

Dump files
For complete information, the SciPROJ It regularly provides a ZIP file with summary data of the projects registered in the database. This file can be accessed via the method “/services/searches/projects/all”.

License to use
Platform data is available under the license Creative Commons Attribution 4.0 (CC BY 4.0).

Call to API To obtain project data by title:

Call for complete data on a specific project:

curl -X GET “https://api.ptcris.pt/services/searches/projects/55088” -H “accept: application/xml”

—

Call to get all registered projects in a ZIP file:

curl -X GET “https://api.ptcris.pt/services/searches/projects/all” -H “accept: application/xml”

—

Call to get all projects filtered by end date:

curl -X GET “https://api.ptcris.pt/services/searches/projects/endDate?from=2019-01-01&to=2019-01-31” -H “accept: application/xml”

—

Call to receive all projects by start date:

curl -X GET “https://api.ptcris.pt/services/searches/projects/startDate?from=2019-01-01&to=2019-01-31” -H “accept: application/xml”

DEPLOY 15-OCT-2023 – Changes compared to the previous version

Type of financing program: The "Funding Program Type" attribute has been added to the "Identifier" XML element within the Project element. This inclusion allows funding records to be categorized by program type, providing greater clarity and organization to the data.

“Uses” element: The "Uses" element has been incorporated into the data profile. This improvement allows access to information about the use of a specific piece of equipment in the context of financing.

Format of the “OAMandate” element: The “OAMandate” element will now be represented as “TRUE” or “FALSE”, providing a more flexible representation of Open Access policies associated with funding, in accordance with the standards. OpenAIRE.

Integração da classificação Fields of Science (FOS): O elemento “Subject” agora inclui a Classificação de Domínios Científicos e Tecnológicos de 2007 (FOS – Fields of Science and Technology). This update enriches the data, allowing filtering of funding records based on scientific domains, facilitating research and analysis with an international standard. The scientific domain is extracted and displayed as a comment in the XML.

Author identifiers: The author identifiers (the “Person” element) specific to the national academic-scientific ecosystem, such as the CIÊNCIA ID and the FCT Public Key (J), previously represented in a manner that did not conform to the guidelines. CERIF of OpenAIRE, agora são apresentados de forma mais genérica, através de um valor e um link. Exemplo XML:

<Identifier type="https://www.wikidata.org/wiki/Q122584897">E717-6F26-3A5E</Identifier>
<Identifier type="https://www.wikidata.org/wiki/Q122538528">J011415</Identifier>

Digital Object Identifier (DOI) associated with financing: When available, the DOI The financing is associated with and included as a "Grant". DOI”, an attribute of the “Funding” element. XML example:

10.3030/777541

Sex/Gender: The “Sexo” attribute in the “Person” element has been renamed to “Gênero”, in accordance with the guidelines. CERIF of OpenAIRE, para melhor compatibilidade com as normas adotadas.