rest api doc
v2021.2
INSPIRE ist ein vertrauenswürdiger Community -Hub, der Forschern hilft, genaue wissenschaftliche Informationen in der hohen Energiephysik zu teilen und zu finden. Zusätzlich zu einer regelmäßigen Weboberfläche für den interaktiven Zugriff auf den Inhalt wird eine REST -API für den programmatischen Zugriff bereitgestellt. Das vorliegende Dokument erläutert, wie diese REST -API verwendet werden.
Wenn Sie die API in einer wissenschaftlichen Arbeit verwenden, zitieren Sie sie bitte mit den folgenden Metadaten:
@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 "
}Wenn Sie Probleme mit der API haben, Hilfe wünschen oder einige Vorschläge zur Verbesserung der API oder der Dokumentation haben, öffnen Sie bitte ein Problem oder kontaktieren Sie uns.
Die Nutzung der API unterliegt unseren Nutzungsbedingungen. Wie dort ausführlicher erläutert, ist der größte Teil der Metadaten im Rahmen einer CC0 -Lizenz verfügbar, die Beschränkungen gelten jedoch für einige Felder, und die Massenerfassung von E -Mail -Adressen ist nicht zulässig.
Die API ist im Allgemeinen erholsam und gibt standardmäßig zu JSON zurück. Dies bedeutet beispielsweise, dass ein 404 HTTP -Statuscode zurückgegeben wird, wenn ein Datensatz nicht gefunden werden kann.
Im Allgemeinen haben die meisten Seiten, die Sie über die Website erhalten, eine entsprechende Darstellung in der API, die durch Präfix der Pfadkomponente der URL mit /api/ erhalten wird. Zum Beispiel die angezeigten Daten bei
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
ist über die API bei erhältlich
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
Derzeit sind nur schreibgeschützte Vorgänge auf Datensätzen zulässig und alle verwenden die GET HTTP-Methode.
Beachten Sie, dass alle Beispiele auf menschlich lesbare Weise angezeigt werden, aber die Abfrageparameter müssen häufig URL-kodiert werden. Insbesondere müssen Räume durch %20 ersetzt werden.
Um den Server überwältigen zu vermeiden, erzwingen wir Tarifgrenzen pro IP -Adresse: Jede IP -Adresse ist 15 Anfragen in einem 5S -Fenster zulässig. Wenn Sie diese Grenzen überschreiten, erhalten Sie eine Antwort mit dem HTTP -Statuscode 429. Bitte beachten bevor es sich erneut bemüht.
Verwenden Sie die folgende URL -Art, um die Metadaten in einem einzigen Datensatz zu erhalten:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Zwei Hauptkategorien von Datensatzkennungen (dh Paare von {identifier-type} und {identifier-value} ) werden unterstützt.
Dies sind die gleichen Kennungen, die in den URLs auf der Website angezeigt werden und können auch für die Suche verwendet werden. Der {identifier-type} kann die folgenden Werte annehmen:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata und der {identifier-value} ist eine Nummer, die den angegebenen Datensatz in der Inspire-Datenbank (auch als Datensatz-ID oder recid genannt) identifiziert. Zum Beispiel,
https://inspirehep.net/api/literature/451647
ist die Aufzeichnung von Maldacenas berühmten Anzeigen/CFT -Papier, während
https://inspirehep.net/api/conferences/1642486
ist die Aufzeichnung der ICHEP 2018 -Konferenz.
Dies sind anhaltende Identifikatoren, die nicht von Inspire zugeordnet wurden, aber dennoch ein einzigartiger Datensatz in Inspire identifizieren (wenn ein Datensatz für die entsprechende Kennung im System vorliegt).
Die folgenden externen Kennungen können verwendet werden:
{identifier-type} | {identifier-value} (Beispiele) | Verwendung |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | eine Literaturaufzeichnung mit einem doi erhalten |
arxiv | 1207.7214 , hep-ph/0603175 | Um einen Literaturaufzeichnung mit einem Arxiv -Kennung zu erhalten |
orcid | 0000-0003-3897-046X | um einen Autor -Datensatz bei einer Orcid -ID zu erhalten |
Zum Beispiel,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
ist Stephen Hawkings Autorrekord.
Standardmäßig ist die API -Antwort beim Abrufen eines einzelnen Datensatzes im JSON -Format und enthält die folgenden Schlüssel:
| Schlüssel | Beschreibung |
|---|---|
id | Kennung zum Abrufen des Datensatzes |
created | Schöpfungsstempel des Rekords in UTC |
updated | Letzter Update -Zeitstempel des Datensatzes in UTC |
links | Links zu Ressourcen im Zusammenhang mit dem Datensatz |
metadata | Metadaten der Aufzeichnung |
Unabhängig davon, welcher Bezeichner zum Abrufen des Datensatzes verwendet wird, ist auch in metadata vorhanden (sowie die anderen zu diesem Aufzeichnung gehörenden Kennungen) vorhanden.
Das links -Objekt enthält Links zu Metadaten, die sich auf diesen Datensatz beziehen, jedoch nicht direkt in den Datensatz (z. B. Zitierinformationen) und alternative Serialisierungsformate (z. B. Bibtex) enthalten sind.
Das metadata enthält die Metadaten des richtigen Datensatzes. Alle Datensätze haben einen $schema -Schlüssel, der mit einem JSON -Schema (Entwurf 4) verknüpft ist, dem die Rekordmetadaten folgen. Eine detaillierte Dokumentation der möglichen Felder für jedes Schema und ihre Bedeutung finden Sie in der Schema -Dokumentation.
Zum Beispiel entspricht die metadata von Literature dem hep -Schema, dessen Felder hier dokumentiert sind.
Es ist möglich, eine Darstellung eines Datensatzes (oder mehrere Datensätze) in einem anderen Format als Standard JSON zu erhalten. Dies kann auf zwei alternative Weise erfolgen:
format={format-name} URL-Abfrage-Zeichenfolge oderAccept auf einen bestimmten MIME -Typ festgelegt wird. Derzeit werden die folgenden Formate unterstützt (nur für Literature ):
{format-name} | MIME -Typ | Beschreibung |
|---|---|---|
| JSON | Anwendung/JSON | Das Standard -JSON -Format |
| Bibtex | Anwendung/x-Bibtex | Das Bibtex -Zitierformat |
| Latex-EU | application/vnd+inspire.latex.eu+x-latex | Das Latex (EU) Zitatformat |
| Latex-us | application/vnd+inspire.latex.us+x-latex | Das Latex (US) Zitatformat |
| cv | text/vnd+inspire.html+html | Das CV -HTML -Zitatformat |
Links zu alternativen Formaten finden Sie auch im links -Objekt innerhalb der JSON -Antwort.
Verwenden Sie beispielsweise das berühmte Papier von Glashow über schwache Wechselwirkungen im Bibtex -Format entweder einen Formatparameter:
https://inspirehep.net/api/literature/4328?format=bibtex
oder entsprechend Inhaltsverhandlungen (das Beispiel verwendet das curl -Befehlszeilen -Tool, um den Header festzulegen):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
Verwenden Sie eine Basis -URL der folgenden Form:
https://inspirehep.net/api/{record-type}?{query-string}
Der {record-type} muss einer von: sein:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdataBeachten Sie, dass diese mit den internen Bezeichnungstypen übereinstimmen.
Der {query-string} kann mehrere {parameter}={value} -Paare enthalten, die durch & . Die folgenden Parameter werden immer unterstützt:
{parameter} | Beschreibung von {value} |
|---|---|
q | Die Suchabfrage |
sort | Die Sortierreihenfolge |
size | Die Anzahl der zurückgegebenen Ergebnisse pro Seite zurückgegeben |
page | Die Seitennummer |
fields | Die Felder in den Metadaten, die zurückgegeben werden sollen |
Zusätzlich stehen je nach {record-type} verschiedene Facettenfilter zur Verfügung, um die Ergebnisse der Ergebnisse einzuschränken. Sie arbeiten genauso wie auf der Website.
Um beispielsweise die 6. bis 10. kommenden Konferenzen zu erhalten, kann die folgende URL verwendet werden:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
Um die 10 neuesten Papiere zu erhalten, die mindestens 1000 Mal zitiert sind, verwenden Sie:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
Mit dem q -Abfrage -String -Argument können Sie eine Suchabfrage angeben, die nur mit einer Teilmenge von Datensätzen übereinstimmt.
Für Literaturdatensätze (erhalten über den /api/literature -Endpunkt) wird eine benutzerdefinierte Suchsyntax zur Rückwärtskompatibilität mit Biers und dem alten Inspire verwendet. Es wird hier erklärt. Zusätzlich kann jedes Feld der Datensatzmetadaten unter Verwendung seines Pfades durchsucht werden, indem die verschachtelten Schlüssel mit verkettet werden . , gefolgt von a : und der Wert, nach dem man suchen muss.
Um beispielsweise alle Papiere mit einer Abstract von Springer zu finden, kann die folgende Suche verwendet werden:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
Um alle Konferenzen zu finden, zitieren Sie Edward Witten, können Sie verwenden:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
Um zu überprüfen, ob ein Feld existiert, können Sie eine * Wildcard verwenden. Um beispielsweise alle Papiere mit einem doi zu finden, können Sie verwenden:
https://inspirehep.net/api/literature?q=dois.value:*
Für andere Arten von Datensätzen wird die Elasticsearch Query String Syntax verwendet. Auch hier kann jedes Feld der Datensatzmetadaten unter Verwendung seines Pfades durchsucht werden, indem die verschachtelten Schlüssel mit verkettet werden . , gefolgt von a : und der Wert, nach dem man suchen muss.
Zum Beispiel verwenden
https://inspirehep.net/api/experiments?q=accelerator.value:PS
In ähnlicher Weise, um einen Autor mit einer bestimmten Inspire -ID zu finden, verwenden Sie
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
Die Reihenfolge, in der Suchergebnisse zurückgegeben werden, hängt davon ab, ob eine Suchabfrage bereitgestellt wird.
Standardmäßig,
q -Abfrageparameter), werden die Ergebnisse zuerst mit den neuesten Datensätzen sortiert.q -Abfrageparameter), werden die Ergebnisse mit den relevantesten zuerst sortiert. Dieses Verhalten kann mit dem Parameter sort={sort-order} -Anterfrage überschrieben werden. Die folgenden Optionen werden unterstützt:
{record-type} | {sort-order} | Beschreibung |
|---|---|---|
literature | mostrecent | Die jüngsten Datensätze erscheinen zuerst (basierend auf dem frühesten Datum in Metadaten) |
literature | mostcited | Aufzeichnungen mit den meisten Zitaten erscheinen zuerst |
jobs | mostrecent | Zuletzt erstellte Jobs erscheinen zuerst |
jobs | deadline | Jobs mit der frühesten Frist erscheinen zuerst |
conferences | dateasc | Konferenzen mit dem frühesten Startdatum erscheinen zuerst |
conferences | datedesc | Konferenzen mit dem letzten Startdatum erscheinen zuerst |
seminars | dateasc | Seminare mit der frühesten Startzeit erscheinen zuerst |
seminars | datedesc | Seminare mit der neuesten Startzeit erscheinen zuerst |
Zum Beispiel wird die folgende URL die 10 am meisten zitierten Papiere von Edward Witten zurückgeben:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
Die Suchergebnisse werden in Seiten zurückgegeben, um die Größe der Antwort zu begrenzen. Standardmäßig werden 10 Ergebnisse pro Seite zurückgegeben und die erste Seite der Ergebnisse wird zurückgegeben. Um auf die nächsten Seiten zu gelangen, können Sie die Seitennummer an den Parameter der page übergeben.
Verwenden Sie beispielsweise die folgende URL, um Edward Wittens 31. bis 40. am meisten zitierte Papiere zu erhalten.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
Um die nächste Seite zu gehen, kann die next URL des links -Objekts in der Antwort befolgt werden (wenn das Standard -JSON -Format verwendet wird).
Die Anzahl der Ergebnisse pro Seite kann mit dem Parameter size überschrieben werden. Um den Server nicht zu überladen, beträgt der maximal zulässige Wert 1000 und Sie erhalten eine Antwort mit dem HTTP -Statuscode 400, wenn Sie ihn überschreiten.
Um beispielsweise die 50 am meisten zitierten Papiere von Edward Witten gleichzeitig zu erhalten, kann die folgende URL verwendet werden:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
Beachten Sie, dass zusätzlich zu der pro Seite zurückgegebenen Ergebnisse eine technische Einschränkung vorliegt, die das Abrufen von mehr als 10000 Ergebnissen für eine bestimmte Suchabfrage verhindert. Die Problemumgehung besteht darin, die einzelne Suche in mehrere Suchvorgänge mit jeweils weniger als 10000 Ergebnissen aufzubrechen. Weitere Informationen finden Sie in diesem Kommentar.
Die Antwort für eine Suche ist ein JSON -Objekt mit den folgenden Schlüssel:
hits : Enthält die Gesamtzahl der Ergebnisse total und die Datensätze in hits (ein Array, dessen Elemente die gleiche Struktur haben wie in der Einzelrekordantwort)links : Links zu verwandten Ressourcen, z. B. alternative Serialisierungen der Suchergebnisse und der nächsten Seite in next . Beachten Sie, dass die Datensatzmetadaten (in hits.hits.metadata ) mehr Felder enthält als in der Einzelrekordantwort. Die meisten von diesen sind für den internen Gebrauch: Auf jedes Feld, auf das nicht Teil des Schemas angewiesen ist, sollte nicht angewiesen werden, und es gibt keine Garantie dafür, dass es anwesend bleibt oder dass sich sein Inhalt nicht ändert , mit Ausnahme:
/api/literature| Schlüssel | Wert (Beispiel) | Beschreibung |
|---|---|---|
earliest_date | 2020-03-18 | das früheste Datum des Datensatzes |
citation_count | 243 | Die Gesamtzahl der in diesem Datensatz erhaltenen Zitate |
citation_count_without_self_citations | 213 | Die Anzahl der Zitate, die in diesem Datensatz erhalten wurden, ohne Selbstzitationen |
Manchmal interessieren Sie sich möglicherweise nur für bestimmte Felder der Plattenmetadaten und nicht an der gesamten Aufzeichnung. Um die vollständige Antwort zu vermeiden und herunterzuladen, die ziemlich groß sein kann, können die fields -Abfrageparameter verwendet werden. Es sollte auf eine von Kommas getrennte Liste von Feldern festgelegt werden, die in den Datensatzmetadaten vorhanden sein müssen.
Beispielsweise gibt die folgende URL nur die Titel, Autorennamen und Links zu Zugehörigkeitsunterlagen von Papieren mit mehr als 1000 Zitaten zurück:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
Die Metadatenfilterung ist nur in Suchanfragen verfügbar, nicht für die Einzelrekordantwort. Wenn Sie jedoch eine Kennung des Datensatzes kennen, für den Sie teilweise Metadaten erhalten möchten, können Sie eine Suche nach dieser Kennung durchführen, die nur einen Datensatz zurückgibt.
Beispielsweise erhalten Sie mit der folgenden URL die Zitat des Datensatzes unter https://inspireehep.net/api/literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
Beachten Sie, dass es nicht möglich ist, die Anzahl der Elemente eines Arrays Grenzen zu setzen, sondern nur, ob dieses Array überhaupt angezeigt wird. Zum Beispiel ist es nicht möglich, nur die ersten 10 Autoren auszuwählen, aber es ist möglich, die Rückkehrautoren zu vermeiden, indem keine authors (oder eines seiner Teilfelder) in die fields gebracht werden.
Zusätzlich zu den bibliografischen Datenbanken bietet Inspire ein Tool, um eine Bibliographie aus einer Tex -Datei zu generieren, die cite{...} Befehle (oder Varianten) mit Tasten enthält, die eine bestimmte Konvention respektieren, mit der das System den zitierten Datensatz schließen kann. Detailliertere Anweisungen finden Sie im interaktiven Tool.
Um über die API darauf zuzugreifen, müssen Sie mit den folgenden Daten eine Postanforderung an den Endpunkt unter https://inspirehep.net/api/bibliography-generator stellen: Generator: Generator:
format , dessen Wert entweder bibtex , latex_eu oder latex_us ist, abhängig vom erforderlichen bibliografischen Formatfile der die formkodierte Datei als Argument enthält. Die Antwort ist ein JSON -Objekt mit einem einzelnen data , dessen Wert ein Objekt ist, das die URL für die generierte Bibliographie -Datei unter download_url und ein Array von aufgetretenen Fehlern unter errors enthält (was leer ist, wenn keine Fehler im Prozess vorliegen).
Zum Beispiel mit curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
Bei der Verwendung des beliebten Python requests kann dies wie in seiner Dokumentation erläutert erfolgen.
Mehrere Tools in verschiedenen Sprachen verwenden diese API. Ihr Code könnte als nützliche Quelle für reale Beispiele dienen.
Wenn Sie möchten, dass Ihr Projekt aufgelistet wird, zögern Sie nicht, uns mitzuteilen.
