rest api doc
v2021.2
Inspire est un centre communautaire de confiance qui aide les chercheurs à partager et à trouver des informations savantes précises en physique de haute énergie. En plus d'une interface Web régulière pour un accès interactif à son contenu, une API REST est fournie pour un accès programmatique. Le présent document explique comment utiliser cette API REST.
Si vous utilisez l'API dans une œuvre savante, veuillez la citer en utilisant les métadonnées suivantes:
@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 vous avez des problèmes d'utilisation de l'API, que vous souhaitez de l'aide ou que vous avez des suggestions pour améliorer l'API ou sa documentation, veuillez ouvrir un problème ou nous contacter.
L'utilisation de l'API est régie par nos conditions d'utilisation. Comme expliqué plus en détail, la plupart des métadonnées sont disponibles sous une licence CC0, mais les restrictions s'appliquent à certains champs, et la collecte en vrac d'adresses e-mail n'est pas autorisée.
L'API est généralement reposante et renvoie les résultats en JSON par défaut. Cela signifie par exemple qu'il renverra un code d'état 404 HTTP si un enregistrement ne peut être trouvé.
En général, la plupart des pages que vous obtenez sur le site Web ont une représentation correspondante dans l'API obtenue en préfixant le composant chemin de l'URL avec /api/ . Par exemple, les données affichées à
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
est disponible via l'API à
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
Actuellement, seules les opérations en lecture seule sur les enregistrements sont autorisées et elles utilisent toutes la méthode GET HTTP.
Notez que tous les exemples sont affichés de manière lisible par l'homme, mais les paramètres de requête doivent souvent être codés par URL. En particulier, les espaces doivent être remplacés par %20 .
Afin d'éviter de submerger le serveur, nous appliquons des limites de taux par adresse IP: chaque adresse IP est autorisée 15 demandes dans une fenêtre 5S. Si vous dépassez ces limites, vous recevrez une réponse avec le code d'état HTTP 429. Veuillez noter que les demandes qui sont bloquées en raison de la dépression de la limite de taux pour le quota, vous devrez donc attendre au moins 5 s lors de la réception d'une réponse 429 avant de réessayer.
Pour obtenir les métadonnées en un seul enregistrement, utilisez le type d'URL suivant:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Deux catégories principales d'identifiants d'enregistrement (c'est-à-dire des paires de {identifier-type} et {identifier-value} ) sont prises en charge.
Ce sont les mêmes identificateurs que ceux qui apparaissent dans les URL sur le site Web et peuvent également être utilisés pour la recherche. Le {identifier-type} peut prendre les valeurs suivantes:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata et le {identifier-value} est un nombre identifiant l'enregistrement donné dans la base de données Inspire (également appelée ID de enregistrement ou recid ). Par exemple,
https://inspirehep.net/api/literature/451647
est le record du célèbre journal Ads / CFT de Maldacena, alors que
https://inspirehep.net/api/conferences/1642486
est le dossier de la conférence ICHEP 2018.
Ce sont des identifiants persistants qui n'ont pas été affectés par Inspire mais qui identifient néanmoins un enregistrement dans Inspire (si un enregistrement pour l'identifiant correspondant existe dans le système).
Les identifiants externes suivants peuvent être utilisés:
{identifier-type} | {identifier-value} (exemples) | Usage |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | Pour obtenir un dossier de littérature donné un doi |
arxiv | 1207.7214 , hep-ph/0603175 | Pour obtenir un dossier de littérature donné un identifiant ArXIV |
orcid | 0000-0003-3897-046X | Pour obtenir un enregistrement d'auteur donné un ID ORCID |
Par exemple,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
est le dossier d'auteur de Stephen Hawkings.
Par défaut, la réponse de l'API lors de la récupération d'un seul enregistrement sera au format JSON et contiendra les clés suivantes:
| Clé | Description |
|---|---|
id | Identifiant utilisé pour récupérer l'enregistrement |
created | Timestamp de création du disque dans UTC |
updated | Dernière mise à jour de mise à jour de l'enregistrement dans UTC |
links | Liens vers des ressources liées à l'enregistrement |
metadata | Métadonnées du disque |
Quel que soit l'identifiant utilisé pour récupérer l'enregistrement, il sera également présent (ainsi que les autres identifiants appartenant à ce dossier) à l'intérieur metadata .
L'objet links contient des liens vers des métadonnées liées à cet enregistrement mais pas directement incluses dans l'enregistrement (par exemple, les informations de citation) et des formats de sérialisation alternatifs (par exemple Bibtex).
L'objet metadata contient les métadonnées de l'enregistrement proprement dit. Tous les enregistrements ont une clé $schema , qui relie à un schéma JSON (projet 4) que les métadonnées enregistrées obéit. Une documentation détaillée sur les champs possibles pour chaque schéma et leur signification se trouvent dans la documentation du schéma.
Par exemple, les metadata des archives Literature sont conformes au schéma hep , dont les champs sont documentés ici.
Il est possible d'obtenir une représentation d'un enregistrement (ou de plusieurs enregistrements) dans un format différent de la JSON par défaut. Cela peut être fait de deux manières alternatives:
format={format-name} Url Query String, ouAccept sur un type MIME spécifique. Actuellement, les formats suivants sont pris en charge (uniquement pour les dossiers Literature ):
{format-name} | Type mime | Description |
|---|---|---|
| json | Application / JSON | Le format JSON par défaut |
| bibtex | Application / X-Bibtex | Le format de citation de Bibtex |
| Latex-UE | application / vnd + inspire.latex.eu + x-latex | Le format de citation du latex (UE) |
| Latex-US | application / vnd + inspire.latex.us + x-latex | Le format de citation du latex (US) |
| cv | text / vnd + inspire.html + html | Le format de citation CV HTML |
Les liens vers des formats alternatifs peuvent également être trouvés dans l'objet links à l'intérieur de la réponse JSON.
Par exemple, pour obtenir le célèbre article de Glashow sur les interactions faibles au format Bibtex, utilisez soit un paramètre de format:
https://inspirehep.net/api/literature/4328?format=bibtex
ou de manière équivalente, la négociation de contenu (l'exemple utilise l'outil de ligne de commande curl pour définir l'en-tête):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
Afin d'obtenir des résultats pour une recherche plutôt que d'obtenir les données d'un seul enregistrement par son identifiant, utilisez une URL de base du formulaire suivant:
https://inspirehep.net/api/{record-type}?{query-string}
Le {record-type} doit être l'un des:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdataNotez que ce sont les mêmes que les types d'identificateurs internes.
Le {query-string} peut contenir plusieurs paires {parameter}={value} séparées par & . Les paramètres suivants sont toujours pris en charge:
{parameter} | Description de {value} |
|---|---|
q | La requête de recherche |
sort | L'ordre de tri |
size | Le nombre de résultats renvoyés par page |
page | Le numéro de page |
fields | Les champs dans les métadonnées à retourner |
De plus, selon le {record-type} , différents filtres à facettes sont disponibles pour restreindre l'ensemble des résultats. Ils fonctionnent exactement de la même manière que sur le site Web.
Par exemple, pour obtenir les 6e au 10e conférences à venir, l'URL suivante peut être utilisée:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
Pour obtenir les 10 articles les plus récents cités au moins 1000 fois, utilisez:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
L'argument q Query String permet de spécifier une requête de recherche qui ne correspond qu'à un sous-ensemble d'enregistrements.
Pour les dossiers de la littérature (obtenus via le point de terminaison /api/literature ), une syntaxe de recherche personnalisée est utilisée pour une compatibilité vers l'arrière avec les flèches et l'ancien inspiration. Il est expliqué ici. De plus, tout champ des métadonnées d'enregistrement peut être recherché en utilisant son chemin donné en concaténant les clés imbriquées . , suivi de A : et la valeur à rechercher.
Par exemple, pour trouver tous les articles ayant un résumé de Springer, la recherche suivante peut être utilisée:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
Pour trouver tous les articles de conférences citant Edward Witten, vous pouvez utiliser:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
Pour vérifier s'il existe un champ, vous pouvez utiliser un * joker. Par exemple, pour trouver tous les articles ayant un doi, vous pouvez utiliser:
https://inspirehep.net/api/literature?q=dois.value:*
Pour d'autres types d'enregistrements, la syntaxe de chaîne de requête Elasticsearch est utilisée. Ici aussi, tout champ des métadonnées enregistrés peut être recherché en utilisant son chemin donné en concaténant les clés imbriquées . , suivi de A : et la valeur à rechercher.
Par exemple, pour trouver toutes les expériences à l'aide de l'accélérateur de Sern Proton-Synchotron (PS), utilisez
https://inspirehep.net/api/experiments?q=accelerator.value:PS
De même, pour trouver un auteur avec un identifiant Inspire donné, utilisez
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
L'ordre dans lequel les résultats de recherche sont renvoyés dépend de la fourniture d'une requête de recherche.
Par défaut,
q ), les résultats sont triés avec les enregistrements les plus récents, d'abord,q ), les résultats sont triés avec les plus pertinents en premier. Ce comportement peut être remplacé par le paramètre de requête sort={sort-order} . Les options suivantes sont prises en charge:
{record-type} | {sort-order} | Description |
|---|---|---|
literature | mostrecent | Les enregistrements les plus récents apparaissent en premier (sur la base de la date la plus précoce des métadonnées) |
literature | mostcited | Les enregistrements avec la plupart des citations apparaissent en premier |
jobs | mostrecent | Plus récemment, des emplois créés apparaissent en premier |
jobs | deadline | Les emplois avec la date limite la plus ancienne apparaissent en premier |
conferences | dateasc | Les conférences avec la première date de début apparaissent en premier |
conferences | datedesc | Les conférences avec la date de début la plus récente apparaissent en premier |
seminars | dateasc | Les séminaires avec les premières heures de début apparaissent en premier |
seminars | datedesc | Les séminaires avec la dernière heure de début apparaissent en premier |
Par exemple, l'URL suivante renverra les 10 articles les plus cités d'Edward Witten:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
Les résultats de la recherche sont retournés en pages pour limiter la taille de la réponse. Par défaut, 10 résultats sont retournés par page et la première page des résultats est renvoyée. Pour accéder aux pages suivantes, vous pouvez passer le numéro de page au paramètre de requête page .
Par exemple, utilisez l'URL suivante pour obtenir les 31e à la 40e documents les plus cités d'Edward Witten.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
Pour aller à la page suivante, l'URL next de l'objet links dans la réponse peut être suivie (lors de l'utilisation du format JSON par défaut).
Le nombre de résultats par page peut être remplacé avec le paramètre de requête size . Afin de ne pas surcharger le serveur, la valeur maximale autorisée est 1000 et vous obtiendrez une réponse avec le code d'état HTTP 400 si vous le dépassez.
Par exemple, pour obtenir les 50 articles les plus cités d'Edward Witten à la fois, l'URL suivante peut être utilisée:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
Notez que, en plus de la limite des résultats renvoyés par page, il existe actuellement une limitation technique empêchant la récupération de plus de 10000 résultats pour une requête de recherche donnée. La solution de contournement consiste à briser la recherche unique en plusieurs recherches ayant moins de 10000 résultats chacune. Voir ce commentaire pour plus d'informations.
La réponse pour une recherche est un objet JSON avec les touches suivantes:
hits : contient le nombre total de résultats dans total et les enregistrements en hits (qui est un tableau dont les éléments ont la même structure que dans la réponse à record unique)links : liens vers des ressources connexes, telles que des sérialisations alternatives des résultats de recherche et la page suivante de next . Notez que les métadonnées enregistrées (dans hits.hits.metadata ) contient plus de champs que dans la réponse à record unique. La plupart d'entre eux sont pour un usage interne: tout champ qui ne fait pas partie du schéma ne doit pas être invoqué, et rien ne garantit qu'il restera présent ou que son contenu ne changera pas , à l'exception de:
/api/literature| clé | valeur (exemple) | description |
|---|---|---|
earliest_date | 2020-03-18 | la date la plus ancienne du dossier |
citation_count | 243 | le nombre total de citations reçues par ce dossier |
citation_count_without_self_citations | 213 | le nombre de citations reçues par ce dossier, à l'exclusion des auto-justes |
Parfois, vous pourriez être intéressé par uniquement des domaines spécifiques des métadonnées record et non dans l'ensemble du record. Pour éviter de générer et de télécharger la réponse complète, qui peut être assez grande, le paramètre de requête fields peut être utilisé. Il doit être défini sur une liste de champs séparés par des virgules qui doivent être présents dans les métadonnées enregistrées.
Par exemple, l'URL suivante ne retournera que les titres, les noms d'auteur et les liens vers les dossiers d'affiliation des articles avec plus de 1000 citations:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
Le filtrage des métadonnées est uniquement disponible dans les recherches, et non pour la réponse d'enregistrement unique. Cependant, si vous connaissez un identifiant de l'enregistrement pour lequel vous souhaitez obtenir des métadonnées partielles, vous pouvez effectuer une recherche de cet identifiant, qui ne renverra qu'un seul enregistrement.
Par exemple, l'URL suivante vous donnera le nombre de citations de l'enregistrement à https://inspirehep.net/api/literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
Notez qu'il n'est pas possible de fixer des limites sur le nombre d'éléments d'un tableau, mais sélectionnez uniquement si ce tableau doit apparaître du tout. Par exemple, il n'est pas possible de sélectionner uniquement les 10 premiers auteurs, mais il est possible d'éviter de retourner des auteurs en ne mettant pas authors (ou l'un de ses sous-champs) parmi les fields .
En plus des bases de données bibliographiques, Inspire propose un outil pour générer une bibliographie à partir d'un fichier tex contenant cite{...} commandes (ou variantes) avec des clés qui respectent une convention spécifique qui permet au système de déduire l'enregistrement cité. Des instructions plus détaillées sont disponibles dans l'outil interactif.
Pour y accéder via l'API, vous devez faire une demande de poste au point de terminaison à https://inspirehep.net/api/bibliography-generator , avec les données suivantes:
format dont la valeur est soit bibtex , latex_eu ou latex_us en fonction du format bibliographique requisfile contenant le fichier codé de forme comme argument. La réponse sera un objet JSON avec une seule clé data dont la valeur est un objet contenant l'URL vers le fichier de bibliographie généré sous download_url et un tableau d'erreurs rencontrées sous errors (ce qui est vide s'il n'y a pas d'erreurs dans le processus).
Par exemple avec curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
Lorsque vous utilisez le package populaire requests Python, cela peut être fait comme expliqué dans sa documentation.
Plusieurs outils dans différentes langues utilisent cette API. Leur code pourrait servir de source utile d'exemples du monde réel.
Si vous souhaitez que votre projet soit répertorié, n'hésitez pas à nous le faire savoir.
