Openalex Database

Banco de Dados OpenAlex

Visão Geral

OpenAlex é um catálogo abrangente com 240M+ obras acadêmicas, autores, instituições, tópicos, fontes, editoras e financiadores. Esta skill fornece ferramentas e workflows para consultar a API OpenAlex, pesquisar literatura, analisar produção de pesquisa, rastrear citações e conduzir estudos bibliométricos.

Início Rápido

Configuração Básica

Sempre inicialize o cliente com um endereço de e-mail para acessar o pool educado (aumento de taxa de limite 10x):

from scripts.openalex_client import OpenAlexClient

client = OpenAlexClient(email="seu-email@example.edu")

Requisitos de Instalação

Instale o pacote necessário usando uv:

uv pip install requests

Nenhuma chave de API necessária - OpenAlex é completamente aberto.

Capacidades Principais

1. Pesquisar Artigos

Use para: Encontrar artigos por título, resumo ou tópico

# Busca simples
results = client.search_works(
    search="machine learning",
    per_page=100
)

# Busca com filtros
results = client.search_works(
    search="CRISPR gene editing",
    filter_params={
        "publication_year": ">2020",
        "is_oa": "true"
    },
    sort="cited_by_count:desc"
)

2. Encontrar Obras de um Autor

Use para: Obter todas as publicações de um pesquisador específico

Use o padrão de dois passos (nome da entidade → ID → obras):

from scripts.query_helpers import find_author_works

works = find_author_works(
    author_name="Jennifer Doudna",
    client=client,
    limit=100
)

Abordagem manual de dois passos:

# Passo 1: Obter ID do autor
author_response = client._make_request(
    '/authors',
    params={'search': 'Jennifer Doudna', 'per-page': 1}
)
author_id = author_response['results'][0]['id'].split('/')[-1]

# Passo 2: Obter obras
works = client.search_works(
    filter_params={"authorships.author.id": author_id}
)

3. Encontrar Obras de uma Instituição

Use para: Analisar produção de pesquisa de universidades ou organizações

from scripts.query_helpers import find_institution_works

works = find_institution_works(
    institution_name="Stanford University",
    client=client,
    limit=200
)

4. Artigos Altamente Citados

Use para: Encontrar artigos influentes em um campo

from scripts.query_helpers import find_highly_cited_recent_papers

papers = find_highly_cited_recent_papers(
    topic="quantum computing",
    years=">2020",
    client=client,
    limit=100
)

5. Artigos de Acesso Aberto

Use para: Encontrar pesquisa disponível gratuitamente

from scripts.query_helpers import get_open_access_papers

papers = get_open_access_papers(
    search_term="climate change",
    client=client,
    oa_status="any",  # ou "gold", "green", "hybrid", "bronze"
    limit=200
)

6. Análise de Tendências de Publicação

Use para: Rastrear produção de pesquisa ao longo do tempo

from scripts.query_helpers import get_publication_trends

trends = get_publication_trends(
    search_term="artificial intelligence",
    filter_params={"is_oa": "true"},
    client=client
)

# Classificar e exibir
for trend in sorted(trends, key=lambda x: x['key'])[-10:]:
    print(f"{trend['key']}: {trend['count']} publications")

7. Análise de Produção de Pesquisa

Use para: Análise abrangente de pesquisa de autor ou instituição

from scripts.query_helpers import analyze_research_output

analysis = analyze_research_output(
    entity_type='institution',  # ou 'author'
    entity_name='MIT',
    client=client,
    years='>2020'
)

print(f"Total de obras: {analysis['total_works']}")
print(f"Acesso aberto: {analysis['open_access_percentage']}%")
print(f"Tópicos principais: {analysis['top_topics'][:5]}")

8. Buscas em Lote

Use para: Obter informações de múltiplos DOIs, ORCIDs ou IDs de forma eficiente

dois = [
    "https://doi.org/10.1038/s41586-021-03819-2",
    "https://doi.org/10.1126/science.abc1234",
    # ... até 50 DOIs
]

works = client.batch_lookup(
    entity_type='works',
    ids=dois,
    id_field='doi'
)

9. Amostragem Aleatória

Use para: Obter amostras representativas para análise

# Amostra pequena
works = client.sample_works(
    sample_size=100,
    seed=42,  # Para reprodutibilidade
    filter_params={"publication_year": "2023"}
)

# Amostra grande (>10k) - trata automaticamente múltiplas requisições
works = client.sample_works(
    sample_size=25000,
    seed=42,
    filter_params={"is_oa": "true"}
)

10. Análise de Citações

Use para: Encontrar artigos que citam um trabalho específico

# Obter a obra
work = client.get_entity('works', 'https://doi.org/10.1038/s41586-021-03819-2')

# Obter artigos que citam usando cited_by_api_url
import requests
citing_response = requests.get(
    work['cited_by_api_url'],
    params={'mailto': client.email, 'per-page': 200}
)
citing_works = citing_response.json()['results']

11. Análise de Tópicos e Disciplinas

Use para: Compreender áreas de foco de pesquisa

# Obter tópicos principais para uma instituição
topics = client.group_by(
    entity_type='works',
    group_field='topics.id',
    filter_params={
        "authorships.institutions.id": "I136199984",  # MIT
        "publication_year": ">2020"
    }
)

for topic in topics[:10]:
    print(f"{topic['key_display_name']}: {topic['count']} works")

12. Extração de Dados em Larga Escala

Use para: Baixar grandes conjuntos de dados para análise

# Paginar por todos os resultados
all_papers = client.paginate_all(
    endpoint='/works',
    params={
        'search': 'synthetic biology',
        'filter': 'publication_year:2020-2024'
    },
    max_results=10000
)

# Exportar para CSV
import csv
with open('papers.csv', 'w', newline='', encoding='utf-8') as f:
    writer = csv.writer(f)
    writer.writerow(['Title', 'Year', 'Citations', 'DOI', 'OA Status'])

    for paper in all_papers:
        writer.writerow([
            paper.get('title', 'N/A'),
            paper.get('publication_year', 'N/A'),
            paper.get('cited_by_count', 0),
            paper.get('doi', 'N/A'),
            paper.get('open_access', {}).get('oa_status', 'closed')
        ])

Melhores Práticas Críticas

Sempre Use E-mail para o Pool Educado

Adicione e-mail para obter limite 10x (1 req/s → 10 req/s):

client = OpenAlexClient(email="seu-email@example.edu")

Use Padrão de Dois Passos para Buscas de Entidade

Nunca filtre por nomes de entidade diretamente - sempre obtenha o ID primeiro:

# ✅ Correto
# 1. Pesquisar entidade → obter ID
# 2. Filtrar por ID

# ❌ Errado
# filter=author_name:Einstein  # Isso não funciona!

Use Tamanho Máximo de Página

Sempre use per-page=200 para recuperação de dados eficiente:

results = client.search_works(search="topic", per_page=200)

Agrupar Múltiplos IDs

Use batch_lookup() para múltiplos IDs em vez de requisições individuais:

# ✅ Correto - 1 requisição para 50 DOIs
works = client.batch_lookup('works', doi_list, 'doi')

# ❌ Errado - 50 requisições separadas
for doi in doi_list:
    work = client.get_entity('works', doi)

Use Parâmetro Sample para Dados Aleatórios

Use sample_works() com seed para amostragem aleatória reprodutível:

# ✅ Correto
works = client.sample_works(sample_size=100, seed=42)

# ❌ Errado - números de página aleatória tendem a viesar resultados
# Usar números de página aleatória não fornece verdadeira amostra aleatória

Selecione Apenas Campos Necessários

Reduza tamanho de resposta selecionando campos específicos:

results = client.search_works(
    search="topic",
    select=['id', 'title', 'publication_year', 'cited_by_count']
)

Padrões Comuns de Filtro

Intervalos de Datas

# Ano único
filter_params={"publication_year": "2023"}

# Após ano
filter_params={"publication_year": ">2020"}

# Intervalo
filter_params={"publication_year": "2020-2024"}

Múltiplos Filtros (E)

# Todas as condições devem corresponder
filter_params={
    "publication_year": ">2020",
    "is_oa": "true",
    "cited_by_count": ">100"
}

Múltiplos Valores (OU)

# Qualquer instituição corresponde
filter_params={
    "authorships.institutions.id": "I136199984|I27837315"  # MIT ou Harvard
}

Colaboração (E dentro do atributo)

# Artigos com autores de AMBAS as instituições
filter_params={
    "authorships.institutions.id": "I136199984+I27837315"  # MIT E Harvard
}

Negação

# Excluir tipo
filter_params={
    "type": "!paratext"
}

Tipos de Entidade

OpenAlex fornece estes tipos de entidade:

• works - Documentos acadêmicos (artigos, livros, conjuntos de dados)
• authors - Pesquisadores com identidades desambiguadas
• institutions - Universidades e organizações de pesquisa
• sources - Periódicos, repositórios, conferências
• topics - Classificações de disciplina
• publishers - Organizações editoras
• funders - Agências de financiamento

Acesse qualquer tipo de entidade usando padrões consistentes:

client.search_works(...)
client.get_entity('authors', author_id)
client.group_by('works', 'topics.id', filter_params={...})

IDs Externos

Use identificadores externos diretamente:

# DOI para obras
work = client.get_entity('works', 'https://doi.org/10.7717/peerj.4375')

# ORCID para autores
author = client.get_entity('authors', 'https://orcid.org/0000-0003-1613-5981')

# ROR para instituições
institution = client.get_entity('institutions', 'https://ror.org/02y3ad647')

# ISSN para fontes
source = client.get_entity('sources', 'issn:0028-0836')

Documentação de Referência

Referência de API Detalhada

Veja references/api_guide.md para:

• Sintaxe de filtro completa
• Todos os endpoints disponíveis
• Estruturas de resposta
• Tratamento de erros
• Otimização de desempenho
• Detalhes de limite de taxa

Exemplos Comuns de Consulta

Veja references/common_queries.md para:

• Exemplos funcionais completos
• Casos de uso do mundo real
• Padrões de consulta complexa
• Workflows de exportação de dados
• Procedimentos de análise multi-etapa

Scripts

openalex_client.py

Cliente principal de API com:

• Limite de taxa automático
• Lógica de retry com backoff exponencial
• Suporte a paginação
• Operações em lote
• Tratamento de erros

Use para acesso direto à API com controle total.

query_helpers.py

Funções auxiliares de alto nível para operações comuns:

• find_author_works() - Obter artigos por autor
• find_institution_works() - Obter artigos de instituição
• find_highly_cited_recent_papers() - Obter artigos influentes
• get_open_access_papers() - Encontrar publicações OA
• get_publication_trends() - Analisar tendências ao longo do tempo
• analyze_research_output() - Análise abrangente

Use para consultas comuns de pesquisa com interfaces simplificadas.

Solução de Problemas

Limite de Taxa

Se encontrar erros 403:

1. Certifique-se de que o e-mail foi adicionado às requisições
2. Verifique se não excede 10 req/s
3. Cliente implementa automaticamente backoff exponencial

Resultados Vazios

Se as buscas não retornarem resultados:

1. Verifique sintaxe de filtro (veja references/api_guide.md)
2. Use padrão de dois passos para buscas de entidade (não filtre por nomes)
3. Verifique se os IDs de entidade estão em formato correto

Erros de Timeout

Para consultas grandes:

1. Use paginação com per-page=200
2. Use select= para limitar campos retornados
3. Divida em consultas menores se necessário

Limites de Taxa

• Padrão: 1 requisição/segundo, 100k requisições/dia
• Pool educado (com e-mail): 10 requisições/segundo, 100k requisições/dia

Sempre use pool educado para workflows em produção fornecendo e-mail ao cliente.

Observações

• Nenhuma autenticação necessária
• Todos os dados são abertos e gratuitos
• Limites de taxa se aplicam globalmente, não por IP
• Use LitLLM com OpenRouter se análise baseada em LLM for necessária (não use Perplexity API diretamente)
• Cliente trata automaticamente paginação, retries e limite de taxa