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 CERIF e alinhada com o perfil 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.

O pedido de acesso a este serviço deverá ser feito para o endereço identificadores.ptcris@fct.pt, pelo representante da instituição, ou alguém por si
mandatado, incluindo as seguintes informações da 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.

Estrutura de metadados

A estrutura de metadados de um registo organiza-se nos seguintes blocos informativos:

• 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

Os schemas que estruturam estes metadados seguem as diretrizes CERIF-XML fornecidas pela OpenAIRE, acessíveis em:

https://openaire-guidelines-for-cris-managers.readthedocs.io/en/v1.2.0/

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/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 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:// https://www.wikidata.org/wiki/Q122584897″>E717-6F26-3A5E< /Identifier >
< Identifier type=”https://https://www.wikidata.org/wiki/Q122538528″>J011415< /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>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.