rest api doc
v2021.2
O Inspire é um centro comunitário de confiança que ajuda os pesquisadores a compartilhar e encontrar informações acadêmicas precisas em física de alta energia. Além de uma interface da Web regular para acesso interativo ao seu conteúdo, uma API REST é fornecida para acesso programático. O presente documento explica como usar esta API REST.
Se você usar a API em um trabalho acadêmico, cite -o usando os seguintes metadados:
@article { Moskovic:2021zjs ,
author = " Moskovic, Micha " ,
title = " {The INSPIRE REST API} " ,
url = " https://github.com/inspirehep/rest-api-doc " ,
doi = " 10.5281/zenodo.5788550 " ,
month = " 12 " ,
year = " 2021 "
}Se você tiver algum problema usando a API, gostaria de ajudar ou ter algumas sugestões para melhorar a API ou sua documentação, abra um problema ou entre em contato conosco.
O uso da API é governado por nossos Termos de Uso. Conforme explicado lá com mais detalhes, a maioria dos metadados está disponível sob uma licença CC0, mas as restrições se aplicam a alguns campos e a coleta em massa de endereços de email não é permitida.
A API é geralmente repousante e os retornos resulta em JSON por padrão. Isso significa, por exemplo, que ele retornará um código de status de 404 HTTP se um registro não puder ser encontrado.
Em geral, a maioria das páginas que você passa pelo site possui uma representação correspondente na API obtida prefixando o componente do caminho da URL com /api/ . Por exemplo, os dados exibidos em
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
está disponível através da API em
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
Atualmente, apenas operações somente leitura nos registros são permitidas e todas elas usam o método GET HTTP.
Observe que todos os exemplos são exibidos de maneira legível pelo homem, mas os parâmetros de consulta geralmente precisam ser codificados por URL. Em particular, os espaços precisam ser substituídos por %20 .
Para evitar sobrecarregar o servidor, aplicamos limites de taxa por endereço IP: todo endereço IP é permitido 15 solicitações em uma janela 5S. Se você exceder esses limites, receberá uma resposta com o código de status HTTP 429. Observe que as solicitações que estão bloqueadas devido a exceder a contagem de limites das taxas para a cota, para que você precise esperar pelo menos 5s ao receber uma resposta 429 antes de tentar novamente.
Para obter os metadados em um único registro, use o seguinte tipo de URL:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Duas categorias principais de identificadores de registros (que são pares de {identifier-type} e {identifier-value} ) são suportados.
Estes são os mesmos identificadores que aparecem nos URLs no site e também podem ser usados para pesquisa. O {identifier-type} pode assumir os seguintes valores:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata e o {identifier-value} é um número que identifica o registro fornecido no banco de dados Inspire (também chamado de ID ou recid ). Por exemplo,
https://inspirehep.net/api/literature/451647
é o registro do famoso artigo de ADS/CFT de Maldacena, enquanto
https://inspirehep.net/api/conferences/1642486
é o registro da conferência Ichep 2018.
Esses são identificadores persistentes que não foram atribuídos por inspirar, mas, no entanto, identificar de maneira única um registro no Inspire (se houver um registro para o identificador correspondente no sistema).
Os seguintes identificadores externos podem ser usados:
{identifier-type} | {identifier-value} (exemplos) | Uso |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | para obter um registro de literatura dado um doi |
arxiv | 1207.7214 , hep-ph/0603175 | Para obter um registro de literatura, dado um identificador ARXIV |
orcid | 0000-0003-3897-046X | Para obter um registro de autor dado um ID Orcid |
Por exemplo,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
é o registro do autor de Stephen Hawkings.
Por padrão, a resposta da API ao recuperar um único registro estará no formato JSON e conterá as seguintes chaves:
| Chave | Descrição |
|---|---|
id | Identificador usado para recuperar o registro |
created | Timestamp de criação do registro no UTC |
updated | Última atualização Timestamp do registro no UTC |
links | Links para recursos relacionados ao registro |
metadata | Metadados do registro |
Qualquer que seja o identificador usado para recuperar o registro, ele também estará presente (assim como os outros identificadores pertencentes a esse registro) dentro metadata .
O objeto links contém links para metadados relacionados a esse registro, mas não incluídos diretamente no registro (por exemplo, informações de citação) e formatos alternativos de serialização (por exemplo, Bibtex).
O objeto metadata contém os metadados do registro. Todos os registros têm uma chave $schema , que vincula a um esquema JSON (rascunho 4) que os metadados recordes obedecem. Documentação detalhada sobre os campos possíveis para cada esquema e seu significado pode ser encontrado na documentação do esquema.
Por exemplo, os metadata dos registros Literature estão em conformidade com o esquema hep , cujos campos estão documentados aqui.
É possível obter uma representação de um registro (ou vários registros) em um formato diferente do JSON padrão. Isso pode ser feito de duas maneiras alternativas:
format={format-name} string de consulta URL, ouAccept HTTP para um tipo MIME específico. Atualmente, os seguintes formatos são suportados (apenas para registros Literature ):
{format-name} | MIME TIPO | Descrição |
|---|---|---|
| JSON | Aplicação/JSON | O formato JSON padrão |
| bibtex | APLICAÇÃO/X-BIBTEX | O formato de citação bibtex |
| LATEX-EU | APLICAÇÃO/VND+inspire.latex.eu+x-Latex | O formato de citação de látex (UE) |
| látex-us | APLICAÇÃO/VND+inspire.latex.us+x-Latex | O formato de citação de látex (EUA) |
| cv | Texto/VND+inspire.html+html | O formato de citação CV HTML |
Os links para formatos alternativos também podem ser encontrados no objeto links dentro da resposta JSON.
Por exemplo, para obter o famoso artigo de Glohow sobre interações fracas no formato Bibtex, use um parâmetro de formato:
https://inspirehep.net/api/literature/4328?format=bibtex
ou equivalentemente, a negociação de conteúdo (o exemplo usa a ferramenta de linha de comando curl para definir o cabeçalho):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
Para obter resultados para uma pesquisa em vez de obter os dados de um único registro por seu identificador, use um URL base do seguinte formulário:
https://inspirehep.net/api/{record-type}?{query-string}
O {record-type} deve ser um dos:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdataObserve que esses são os mesmos que os tipos de identificador interno.
O {query-string} pode conter vários pares {parameter}={value} separados por & . Os seguintes parâmetros são sempre suportados:
{parameter} | Descrição de {value} |
|---|---|
q | A consulta de pesquisa |
sort | A ordem de classificação |
size | O número de resultados retornados por página |
page | O número da página |
fields | Os campos nos metadados a serem devolvidos |
Além disso, dependendo do {record-type} , diferentes filtros de faceta estão disponíveis para restringir o conjunto de resultados. Eles funcionam exatamente da mesma maneira que no site.
Por exemplo, para obter as 6ª a 10ª conferências futuras, o seguinte URL pode ser usado:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
Para obter os 10 artigos mais recentes citados pelo menos 1000 vezes, use:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
O argumento da string de consulta q permite especificar uma consulta de pesquisa que corresponda apenas a um subconjunto de registros.
Para registros de literatura (obtidos através do endpoint /api/literature ), uma sintaxe de pesquisa personalizada é usada para compatibilidade com versões anteriores com os pináculos e o antigo inspiração. É explicado aqui. Além disso, qualquer campo dos metadados do registro pode ser pesquisado usando seu caminho fornecido concatenando as chaves aninhadas com . , seguido por A : e o valor a procurar.
Por exemplo, para encontrar todos os trabalhos com um resumo de Springer, a seguinte pesquisa pode ser usada:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
Para encontrar todos os documentos de conferências que citam Edward Witten, você pode usar:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
Para verificar se existe um campo, você pode usar um * curinga. Por exemplo, para encontrar todos os papéis com um doi, você pode usar:
https://inspirehep.net/api/literature?q=dois.value:*
Para outros tipos de registros, a sintaxe de string de consulta Elasticsearch é usada. Aqui também, qualquer campo dos metadados do registro pode ser pesquisado usando seu caminho dado concatenando as chaves aninhadas . , seguido por A : e o valor a procurar.
Por exemplo, para encontrar todos os experimentos usando o acelerador CERN Proton-Synchotron (PS), use
https://inspirehep.net/api/experiments?q=accelerator.value:PS
Da mesma forma, para encontrar um autor com um determinado id de inspiração, use
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
A ordem em que os resultados da pesquisa são retornados depende se uma consulta de pesquisa é fornecida.
Por padrão,
q ), os resultados serão classificados com os registros mais recentes primeiro,q ), os resultados serão classificados com os mais relevantes primeiro. Esse comportamento pode ser substituído pelo parâmetro de consulta sort={sort-order} . As seguintes opções são suportadas:
{record-type} | {sort-order} | Descrição |
|---|---|---|
literature | mostrecent | Os registros mais recentes aparecem primeiro (com base na data mais antiga em metadados) |
literature | mostcited | Registros com a maioria das citações aparecem primeiro |
jobs | mostrecent | Os trabalhos criados mais recentemente aparecem primeiro |
jobs | deadline | Empregos com o prazo mais antigo aparecem primeiro |
conferences | dateasc | Conferências com a data inicial mais antiga aparecem primeiro |
conferences | datedesc | Conferências com a data de início mais recente aparecem primeiro |
seminars | dateasc | Seminários com o primeiro tempo de partida aparecem primeiro |
seminars | datedesc | Seminários com o tempo de partida mais recente aparecem primeiro |
Por exemplo, o URL a seguir retornará os 10 artigos mais citados de Edward Witten:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
Os resultados da pesquisa são retornados nas páginas para limitar o tamanho da resposta. Por padrão, 10 resultados são retornados por página e a primeira página dos resultados é retornada. Para chegar às próximas páginas, você pode passar o número da página para o parâmetro de consulta page .
Por exemplo, use o seguinte URL para obter os 31º a 40º artigos de Edward Witten.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
Para ir na próxima página, o next URL do objeto links na resposta pode ser seguido (ao usar o formato JSON padrão).
O número de resultados por página pode ser substituído com o parâmetro de consulta size . Para não sobrecarregar o servidor, o valor máximo permitido é 1000 e você receberá uma resposta com o código de status HTTP 400 se exceder.
Por exemplo, para obter os 50 papéis mais citados de Edward Witten de uma só vez, o URL seguinte pode ser usado:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
Observe que, além do limite de resultados retornados por página, atualmente existe uma limitação técnica que impede a recuperação de mais de 10000 resultados para uma determinada consulta de pesquisa. A solução alternativa é dividir a pesquisa única em várias pesquisas com menos de 10000 resultados cada. Veja este comentário para obter mais informações.
A resposta para uma pesquisa é um objeto JSON com as seguintes teclas:
hits : contém o número total de resultados no total e os registros em hits (que é uma matriz cujos elementos têm a mesma estrutura da resposta de registro único)links : links para recursos relacionados, como serializações alternativas dos resultados da pesquisa e a próxima página na next . Observe que os metadados do registro (em hits.hits.metadata ) contém mais campos do que na resposta de registro único. A maioria deles é para uso interno: qualquer campo não parte do esquema não deve ser confiado, e não há garantia de que ele permanecerá presente ou que seu conteúdo não mudará , com a exceção de:
/api/literature| chave | valor (exemplo) | descrição |
|---|---|---|
earliest_date | 2020-03-18 | a data mais antiga no registro |
citation_count | 243 | o número total de citações recebidas por este registro |
citation_count_without_self_citations | 213 | O número de citações recebidas por este registro, excluindo autocitações |
Às vezes, você pode estar interessado em apenas alguns campos específicos dos metadados recordes e não em todo o registro. Para evitar gerar e baixar a resposta completa, que pode ser bastante grande, o parâmetro de consulta fields pode ser usado. Ele deve ser definido como uma lista de campos separados por vírgula que precisa estar presente nos metadados recordes.
Por exemplo, o URL a seguir retornará apenas os títulos, nomes dos autores e links para registros de afiliação de artigos com mais de 1000 citações:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
A filtragem de metadados está disponível apenas em pesquisas, não para a resposta de registro único. No entanto, se você conhece um identificador do registro que deseja obter metadados parciais, poderá executar uma pesquisa por esse identificador, que retornará apenas um registro.
Por exemplo, o URL a seguir fornecerá a contagem de citações do registro em https://inspirehep.net/api/literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
Observe que não é possível colocar limites no número de elementos de uma matriz, mas selecione apenas se essa matriz deve aparecer. Por exemplo, não é possível selecionar apenas os 10 primeiros autores, mas é possível evitar que os autores devolvam não colocando authors (ou qualquer um de seus subcampos) entre os fields .
Além dos bancos de dados bibliográficos, o Inspire oferece uma ferramenta para gerar uma bibliografia a partir de um arquivo tex contendo cite{...} comandos (ou variantes) com chaves que respeitam uma convenção específica que permite ao sistema inferir o registro citado. Instruções mais detalhadas estão disponíveis na ferramenta interativa.
Para acessá-lo através da API, você precisa fazer uma solicitação de postagem no ponto final em https://inspirehep.net/api/bibliography-generator , com os seguintes dados:
format cujo valor é bibtex , latex_eu ou latex_us dependendo do formato bibliográfico necessáriofile que contém o arquivo codificado por forma como argumento. A resposta será um objeto JSON com uma única chave data cujo valor é um objeto que contém o URL para o arquivo de bibliografia gerado em download_url e uma matriz de erros encontrados sob errors (que estão vazios se não houver erros no processo).
Por exemplo, com curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
Ao usar o pacote popular requests do Python, isso pode ser feito conforme explicado em sua documentação.
Várias ferramentas em diferentes idiomas estão usando esta API. Seu código pode servir como uma fonte útil de exemplos do mundo real.
Se você deseja que seu projeto seja listado, não hesite em nos informar.
