rest api doc
v2021.2
Inspire es un centro comunitario de confianza que ayuda a los investigadores a compartir y encontrar información académica precisa en física de alta energía. Además de una interfaz web regular para el acceso interactivo a su contenido, se proporciona una API REST para el acceso programático. El presente documento explica cómo usar esta API REST.
Si usa la API en un trabajo académico, cíquelo usando los siguientes metadatos:
@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 "
}Si tiene algún problema para usar la API, desea ayuda o tiene algunas sugerencias para mejorar la API o su documentación, por favor, abra un problema o contáctenos.
El uso de la API se rige por nuestros Términos de uso. Como se explica allí con más detalle, la mayoría de los metadatos están disponibles bajo una licencia CC0, pero las restricciones se aplican a algunos campos, y no se permite la recopilación masiva de direcciones de correo electrónico.
La API generalmente es relajante y devuelve los resultados en JSON por defecto. Esto significa, por ejemplo, que devolverá un código de estado HTTP 404 si no se puede encontrar un registro.
En general, la mayoría de las páginas que obtiene a través del sitio web tienen una representación correspondiente en la API obtenida al prefijo el componente de ruta de la URL con /api/ . Por ejemplo, los datos se muestran en
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
está disponible a través de la API en
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
Actualmente, solo se permiten operaciones de solo lectura en registros y todas utilizan el método GET HTTP.
Tenga en cuenta que todos los ejemplos se muestran de manera legible por humanos, pero los parámetros de consulta a menudo deben estar codificados por URL. En particular, los espacios deben ser reemplazados por %20 .
Para evitar abrumar al servidor, hacemos cumplir los límites de tarifa por dirección IP: a cada dirección IP se les permite 15 solicitudes en una ventana 5S. Si excede esos límites, recibirá una respuesta con el Código de Estado HTTP 429. Tenga en cuenta que las solicitudes que están bloqueadas debido a que excede el límite de tasa con el recuento de la cuota, por lo que deberá esperar al menos 5s al recibir una respuesta de 429 antes de intentarlo de nuevo.
Para obtener los metadatos en un solo registro, use el siguiente tipo de URL:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Se admiten dos categorías principales de identificadores de registros (es decir, pares de {identifier-type} y {identifier-value} ).
Estos son los mismos identificadores que aparecen en las URL en el sitio web y también se pueden usar para buscar. El {identifier-type} puede tomar los siguientes valores:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata y el {identifier-value} es un número que identifica el registro dado en la base de datos Inspire (también llamada ID de registro o recid ). Por ejemplo,
https://inspirehep.net/api/literature/451647
es el registro del famoso papel/papel CFT de Maldacena, mientras que
https://inspirehep.net/api/conferences/1642486
es el registro de la conferencia ICHEP 2018.
Estos son identificadores persistentes que no fueron asignados por Inspire pero, sin embargo, identifican de manera única un registro en Inspire (si un registro para el identificador correspondiente existe en el sistema).
Se pueden usar los siguientes identificadores externos:
{identifier-type} | {identifier-value} (ejemplos) | Uso |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | para obtener un registro de literatura dado un doi |
arxiv | 1207.7214 , hep-ph/0603175 | Para obtener un registro de literatura dado un identificador ARXIV |
orcid | 0000-0003-3897-046X | Para obtener un registro de autor dado una identificación orcid |
Por ejemplo,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
Es el registro de autor de Stephen Hawkings.
Por defecto, la respuesta de la API al recuperar un solo registro estará en formato JSON y contendrá las siguientes claves:
| Llave | Descripción |
|---|---|
id | Identificador utilizado para recuperar el registro |
created | Creación de marca de tiempo del registro en UTC |
updated | Última actualización de la marca de tiempo de actualización del registro en UTC |
links | Enlaces a recursos relacionados con el registro |
metadata | Metadatos del registro |
Cualquiera que sea el identificador que se use para recuperar el registro, también estará presente (así como los otros identificadores que pertenecen a este registro) dentro de metadata .
El objeto links contiene enlaces a metadatos relacionados con este registro, pero no se incluye directamente en el registro (por ejemplo, información de citas) y formatos de serialización alternativos (por ejemplo, bibtex).
El objeto metadata contiene los metadatos del registro propiamente dicho. Todos los registros tienen una clave $schema , que vincula a un esquema JSON (borrador 4) que el registro obedece los metadatos. La documentación detallada sobre los posibles campos para cada esquema y su significado se puede encontrar en la documentación del esquema.
Por ejemplo, los metadata de los registros Literature se ajustan al esquema hep , cuyos campos están documentados aquí.
Es posible obtener una representación de un registro (o varios registros) en un formato diferente del JSON predeterminado. Esto se puede hacer de dos maneras alternativas:
format={format-name}Accept a un tipo MIME específico. Actualmente, los siguientes formatos son compatibles (solo para registros Literature ):
{format-name} | Tipo mimo | Descripción |
|---|---|---|
| json | Aplicación/JSON | El formato JSON predeterminado |
| bibtex | Aplicación/X-Bibtex | El formato de cita de bibtex |
| látex-eu | Aplicación/VND+Inspire.Latex.EU+X-Latex | El formato de cita de látex (UE) |
| látex-us | Aplicación/VND+Inspire.Latex.US+X-Latex | El formato de cita de látex (EE. UU.) |
| CV | texto/vnd+inspire.html+html | El formato de cita CV HTML |
Los enlaces a formatos alternativos también se pueden encontrar en el objeto links dentro de la respuesta JSON.
Por ejemplo, para obtener el famoso artículo de Glashow sobre interacciones débiles en formato Bibtex, use un parámetro de formato:
https://inspirehep.net/api/literature/4328?format=bibtex
o de manera equivalente, la negociación de contenido (el ejemplo usa la herramienta de línea de comandos curl para establecer el encabezado):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
Para obtener resultados para una búsqueda en lugar de obtener los datos de un solo registro por su identificador, use una URL base de la siguiente forma:
https://inspirehep.net/api/{record-type}?{query-string}
El {record-type} debe ser uno de:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdataTenga en cuenta que estos son lo mismo que los tipos de identificadores internos.
La {query-string} puede contener varios pares {parameter}={value} separados por & . Los siguientes parámetros siempre son compatibles:
{parameter} | Descripción de {value} |
|---|---|
q | La consulta de búsqueda |
sort | El orden de clasificación |
size | El número de resultados devueltos por página |
page | El número de página |
fields | Los campos en los metadatos a devolver |
Además, dependiendo del {record-type} , hay diferentes filtros de faceta disponibles para restringir el conjunto de resultados. Funcionan exactamente de la misma manera que en el sitio web.
Por ejemplo, para obtener las conferencias de sexto a décimo próximo, se puede usar la siguiente URL:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
Para obtener los 10 documentos más recientes citados al menos 1000 veces, use:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
El argumento de cadena de consulta q permite especificar una consulta de búsqueda que solo coincide con un subconjunto de registros.
Para los registros de la literatura (obtenidos a través del punto final /api/literature ), se usa una sintaxis de búsqueda personalizada para la compatibilidad hacia atrás con las agujas y el antiguo Inspire. Se explica aquí. Además, cualquier campo de los metadatos de registro se puede buscar utilizando su ruta dada concatenando las teclas anidadas con . , seguido de A : y el valor para buscar.
Por ejemplo, para encontrar todos los documentos que tienen un resumen de Springer, se puede usar la siguiente búsqueda:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
Para encontrar todos los documentos de conferencias citando a Edward Witten, puede usar:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
Para verificar si existe un campo, puede usar un * comodín. Por ejemplo, para encontrar todos los documentos que tienen un DOI, puede usar:
https://inspirehep.net/api/literature?q=dois.value:*
Para otros tipos de registros, se utiliza la sintaxis de cadena de consulta Elasticsearch. Aquí también, cualquier campo de los metadatos de registro se puede buscar utilizando su ruta dada concatenando las teclas anidadas con . , seguido de A : y el valor para buscar.
Por ejemplo, para encontrar todos los experimentos utilizando el acelerador de sincronización de protones de CERN (PS), use
https://inspirehep.net/api/experiments?q=accelerator.value:PS
Del mismo modo, para encontrar un autor con una identificación de Inspire dada, use
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
El orden en el que se devuelven los resultados de búsqueda depende de si se proporciona una consulta de búsqueda.
Por defecto,
q ), los resultados se clasifican primero con los registros más recientes, primero,q ), los resultados se clasifican con el primero más relevante. Este comportamiento se puede anular con el parámetro de consulta sort={sort-order} . Se admiten las siguientes opciones:
{record-type} | {sort-order} | Descripción |
|---|---|---|
literature | mostrecent | Los registros más recientes aparecen primero (basado en la fecha más temprana en los metadatos) |
literature | mostcited | Los registros con la mayoría de las citas aparecen primero |
jobs | mostrecent | Los trabajos creados recientemente aparecen primero |
jobs | deadline | Los trabajos con la fecha límite más temprana aparecen primero |
conferences | dateasc | Las conferencias con la fecha de inicio más temprana aparecen primero |
conferences | datedesc | Las conferencias con la fecha de inicio más reciente aparecen primero |
seminars | dateasc | Los seminarios con la hora de inicio más temprana aparecen primero |
seminars | datedesc | Los seminarios con el tiempo de inicio más reciente aparecen primero |
Por ejemplo, la siguiente URL devolverá los 10 documentos más citados de Edward Witten:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
Los resultados de búsqueda se devuelven en páginas para limitar el tamaño de la respuesta. Por defecto, se devuelven 10 resultados por página y se devuelve la primera página de resultados. Para llegar a las siguientes páginas, puede pasar el número de página al parámetro de consulta page .
Por ejemplo, use la siguiente URL para llevar los periódicos 31 al 40 de Edward Witten.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
Para ir a la página siguiente, se puede seguir la next URL del objeto links en la respuesta (cuando se usa el formato JSON predeterminado).
El número de resultados por página se puede anular con el parámetro de consulta size . Para no sobrecargar el servidor, el valor máximo permitido es 1000 , y obtendrá una respuesta con el código de estado HTTP 400 si lo supera.
Por ejemplo, para obtener los 50 documentos más citados de Edward Witten a la vez, se puede usar la siguiente URL:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
Tenga en cuenta que, además del límite de resultados devueltos por página, actualmente existe una limitación técnica que impide la recuperación de más de 10000 resultados para una consulta de búsqueda dada. La solución es dividir la búsqueda única en varias búsquedas que tienen menos de 10000 resultados cada uno. Vea este comentario para obtener más información.
La respuesta para una búsqueda es un objeto JSON con las siguientes claves:
hits : contiene el número total de resultados en total y los registros en hits (que es una matriz cuyos elementos tienen la misma estructura que en la respuesta de un solo registro)links : enlaces a recursos relacionados, como serializaciones alternativas de los resultados de búsqueda y la siguiente página en next . Tenga en cuenta que los metadatos registrados (en hits.hits.metadata ) contienen más campos que en la respuesta de un solo registro. La mayoría de ellos son para uso interno: cualquier campo que no sea parte del esquema en el que no se debe confiar, y no hay garantía de que permanezca presente o que su contenido no cambie , con la excepción de:
/api/literature| llave | valor (ejemplo) | descripción |
|---|---|---|
earliest_date | 2020-03-18 | la fecha más temprana en el registro |
citation_count | 243 | El número total de citas recibidas por este registro |
citation_count_without_self_citations | 213 | el número de citas recibidas por este registro, excluyendo las autolcaciones. |
A veces, puede estar interesado solo en algunos campos específicos de los metadatos récord y no en todo el registro. Para evitar generar y descargar la respuesta completa, que puede ser bastante grande, se puede usar el parámetro de consulta fields . Debe establecerse en una lista de campos separados por comas que deben estar presentes en los metadatos registrados.
Por ejemplo, la siguiente URL devolverá solo los títulos, nombres de los autores y enlaces a los registros de afiliación de documentos con más de 1000 citas:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
El filtrado de metadatos solo está disponible en búsquedas, no para la respuesta de registro único. Sin embargo, si conoce un identificador del registro para el que desea obtener metadatos parciales, puede realizar una búsqueda de ese identificador, que solo devolverá un registro.
Por ejemplo, la siguiente URL le dará el recuento de citas del registro en https://inspirehep.net/api/literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
Tenga en cuenta que no es posible poner límites en el número de elementos de una matriz, pero solo seleccione si esa matriz debe aparecer en absoluto. Por ejemplo, no es posible seleccionar solo los primeros 10 autores, pero es posible evitar que los autores regresen no colocando authors (o cualquiera de sus subcampos) entre los fields .
Además de las bases de datos bibliográficas, Inspire ofrece una herramienta para generar una bibliografía a partir de un archivo TEX que contiene cite{...} (o variantes) con claves que respetan una convención específica que permite que el sistema infiera el registro citado. Hay instrucciones más detalladas disponibles en la herramienta interactiva.
Para acceder a él a través de la API, debe hacer una solicitud de publicación al punto final en https://inspirehep.net/api/bibliography-generator , con los siguientes datos:
format cuyo valor es bibtex , latex_eu o latex_us dependiendo del formato bibliográfico requeridofile único que contiene el archivo codificado por formulario como argumento. La respuesta será un objeto JSON con una sola clave data cuyo valor es un objeto que contiene la URL al archivo de bibliografía generado en download_url y una matriz de errores encontrados bajo errors (que está vacío si no hay errores en el proceso).
Por ejemplo con curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
Al usar el popular paquete requests de Python, esto se puede hacer tal como se explica en su documentación.
Varias herramientas en diferentes idiomas están utilizando esta API. Su código podría servir como una fuente útil de ejemplos del mundo real.
Si desea que se enumere su proyecto, no dude en informarnos.
