SciPROJ – API

O serviço de API do SciPROJ foi desenvolvido para fornecer os dados do registo nacional de financiamento de Ciência e Tecnologia (C&T) – 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 facilita a interoperabilidade e a reutilização de dados permitindo uma análise detalhada das tendências e impactos do financiamento público no sistema científico nacional.

Base URL
São disponibilizados dois ambientes, um produtivo e outros de testes em qualidade (QA).

Produção:
• https://api.ptcris.pt/

• https://api.ptcris.pt/docs/ (documentação swagger – Funding DB: Projects)

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

• https://etl.ptcris.pt/docs/ (documentação swagger – Funding DB: Projects)

Versão
A versão disponibilizada é a v1.1

A API do SciPROJ está disponível de forma pública e gratuita para todas as entidades pertencentes ao ecossistema PTCRIS. O acesso é realizado com credenciais fornecidas pela plataforma, usando o método de autenticação Basic Authentication.

Para solicitar as credenciais de acesso, a entidade interessada deve enviar um e-mail para identificadores.ptcris@fct.pt, incluindo as seguintes informações sobre a entidade subscritora:

• Nome da entidade ou instituição requerente
• URL da entidade
• Perfil cliente: público
• Nome e e-mail do responsável do serviço cliente

Após o recebimento das credenciais de acesso, os integradores poderão iniciar o desenvolvimento da integração no ambiente de testes da 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.

Perfil

Os clientes podem aceder a dois tipos de perfis: o perfil público, que permite visualizar toda a informação pública sobre projetos, e o perfil privado, que oferece acesso a dados públicos e privados, incluindo dados pessoais (entidade person), em conformidade com o Regulamento Geral sobre a Proteção de Dados (RGPD) e demais legislações aplicáveis. Proteção de Dados (RGPD) e demais legislações aplicáveis.

Permissões

As permissões disponíveis são exclusivamente de leitura.

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 – Projetos financiados
• Funding – Dados de financiamento
• Person – Pessoas associadas aos projetos
• OrgUnit – Organizações associadas aos projetos ou ao financiamento
• Equipment – Equipamento utilizado na execução do projeto

Estes schemas asseguram uma descrição normalizada e interoperável dos dados, conforme especificado nas guidelines CERIF-XML da OpenAIRE.

No caso da base de dados SciPROJ, o modelo CERIF-XML utilizado para a descrição de projetos, disponibilizado através de API, organiza cada registo num componente único que integra duas secções principais:

<header> que inclui metadados de nível do repositório, como:

• <identifier> identificador único do registo
• <datestamp> data e hora da última atualização do registo
• <setSpec> conjunto de dados ou coleção a que o registo pertence

<metadata> contém os principais atributos descritivos do projeto, incluindo:

• <Project> com elementos como:
  • <Acronym> acrónimo do projeto
  • <Title> título do projeto, com suporte a múltiplas línguas (xml:lang)
  • <Identifier> referências externas, como código do projeto ou programa de financiamento
  • <StartDate> e <EndDate> datas de início e término
  • <Subject> ou <Keywords> áreas do conhecimento ou palavras-chave do projeto

Em conjunto, esta estrutura garante uma descrição completa, coerente e alinhada com os padrões internacionais de gestão de informação científica.

Extensões aos Metadados CERIF e OpenAIRE

Para além da estrutura base de metadados, o sistema incorpora extensões específicas que permitem uma representação mais rica e detalhada das atividades de investigação. Estas extensões estão em total conformidade com as diretrizes CERIF-XML fornecidas pela OpenAIRE, garantindo que a informação científica seja facilmente partilhável e integrada em redes globais de conhecimento.

Este modelo de metadados organiza-se em blocos fundamentais, tais como Project (projetos financiados), Funding (dados de financiamento) e OrgUnit (organizações associadas), assegurando que todos os componentes do ecossistema de financiamento sejam devidamente mapeados.

A documentação técnica completa e as diretrizes detalhadas destas extensões podem ser consultadas através do link oficial: Extensões PTCRIS ao perfil CERIF/OpenAIRE

Os métodos que compõem o web service podem ser consultados através do acesso ao Web Application Description Language (WADL). O web service e os webmethods que compõem a consulta às referências de projeto do SciPROJ, podem ser consultados a partir do seguinte descritor:

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

Métodos da API SciPROJ

EndPoint: /projects
URI: https://api.ptcris.pt/services/searches/projects
Descrição: Retorna todos os projetos que atendam os critérios definidos, como título, datas de início e fim, e organização.

—

EndPoint: /projects/{id}
URI: https://api.ptcris.pt/services/searches/projects/{id}
Descrição: Retorna a informação completa de um projeto com base no seu ID único.

—

EndPoint: /projects/all
URI: https://api.ptcris.pt/services/searches/projects/all
Descrição: Retorna toda a informação resumida dos projetos, num ficheiro ZIP.

—

EndPoint: /projects/dump
URI: https://api.ptcris.pt/services/searches/projects/dump
Descrição: Retorna toda a informação dos projetos compilados semanalmente em um arquivo ZIP, de acordo com os critérios de filtro.

—

EndPoint: /projects/endDate
URI: https://api.ptcris.pt/services/searches/projects/endDate
Descrição: Retorna informação filtrada por data de conclusão do projeto.

—

EndPoint: /projects/startDate
URI: https://api.ptcris.pt/services/searches/projects/startDate
Descrição: Retorna informação filtrada pela data de início do projeto.

Para uma utilização otimizada da API por toda a comunidade, recomenda-se as seguintes práticas de utilização:

• Armazenamento em cache dos dados para evitar solicitações repetidas.
• Monitorização do uso da API, com um máximo recomendado de 2 chamadas por segundo (120 por minuto).
• Reportar falhas ao endereço identificadores.ptcris@fct.pt.

Utilizações que afetem negativamente a qualidade do serviço, de forma intencional ou negligente, podem resultar em restrições ou bloqueio de acesso.

Formatos

A API devolve resultados nos formatos XML e JSON, especificáveis pelo cliente através do parâmetro accept no header do pedido.

Tipos de métodos
A API suporta apenas métodos HTTP do tipo GET.

Códigos de resposta
A resposta da API pode incluir vários códigos de acordo com o tipo de chamada realizada:

200 – Operação com sucesso
400 – ID de registo inválido
403 – Permissões inválidas para acesso ao(s) registo(s)
404 – Registo não encontrado
500 – Erro de operação

Os códigos de resposta na gama 4-x-x devem ser tratados durante o processo de integração para garantir a normalização das chamadas à 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 através do email ptcris@fccn.pt.

Ficheiros dump
Para obtenção completa de informação, o SciPROJ disponibiliza regularmente um ficheiro ZIP com dados resumidos dos projetos registados na base de dados. Este ficheiro pode ser acedido através do método “/services/searches/projects/all”.

Licença de uso
Os dados da plataforma estão disponíveis sob a licença Creative Commons Attribution 4.0 (CC BY 4.0).

Chamada à API para obter os dados de projetos por título:

Chamada para obter dados completos de um projeto específico:

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

—

Chamada para obter todos os projetos registados num ficheiro ZIP:

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

—

Chamada para obter todos os projetos filtrados por data de fim:

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

—

Chamada para receber todos os projetos por data de início:

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-OUT-2023 – Alterações em relação à versão anterior

Tipo de programa de financiamento: Foi adicionado o atributo “Tipo de Programa de Financiamento” ao elemento XML “Identifier” dentro do elemento Projeto. Esta inclusão permite categorizar os registos de financiamento segundo o tipo de programa, proporcionando maior clareza e organização nos dados.

Elemento “Usos”: O elemento “Usos” foi incorporado ao perfil de dados. Com esta melhoria, é possível aceder a informações sobre a utilização de determinado equipamento no contexto de um financiamento.

Formato do elemento “OAMandate”: O elemento “OAMandate” passa a ser representado como “TRUE” ou “FALSE”, fornecendo uma representação mais flexível das políticas de Acesso Aberto associadas ao financiamento, em conformidade com os padrões 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). Esta atualização enriquece os dados, permitindo filtrar registos de financiamento com base em domínios científicos, facilitando pesquisas e análises com um padrão internacional. O domínio científico é extraído e exibido como comentário no XML.

Identificadores de autor: Os identificadores de autor (elemento “Person”) específicos do ecossistema académico-científico nacional, como o CIÊNCIA ID e a Chave Pública FCT (J), anteriormente representados de forma não conforme às diretrizes CERIF do 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) associado ao financiamento: Quando disponível, o DOI associado ao financiamento é incluído como “Grant DOI”, um atributo do elemento “Funding”. Exemplo XML:

<Funding>
    <GrantDOI>10.3030/777541</GrantDOI>
</Funding>

Sexo/Género: O atributo “Sexo” no elemento “Person” foi renomeado para “Género”, em conformidade com as diretrizes CERIF do OpenAIRE, para melhor compatibilidade com as normas adotadas.