rest api doc
v2021.2
Inspire是一個值得信賴的社區樞紐，可幫助研究人員在高能量物理學中共享並找到準確的學術信息。除了用於交互式訪問其內容的常規Web界面外，還為程序化訪問提供了REST API。本文檔說明瞭如何使用此REST API。
如果您在學術工作中使用API，請使用以下元數據引用它：
@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 "
}如果您使用API有任何問題，需要一些幫助，或者有一些建議改善API或其文檔，請打開問題或與我們聯繫。
API的使用受我們的使用條款的約束。如此處所述，大多數元數據都在CC0許可證下可用，但是限制適用於某些字段，並且不允許大量的電子郵件地址收集。
API通常是恢復的，默認情況下將返回JSON。例如，這意味著如果找不到記錄，它將返回404 HTTP狀態代碼。
通常，您通過網站獲得的大多數頁面在API中具有相應的表示，通過將URL的路徑組件（以/api/的形式提供給。例如，顯示在
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
可通過API獲得
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
當前，僅允許在記錄上進行僅閱讀操作，並且它們都使用GET HTTP方法。
請注意，所有示例均以人為可讀的方式顯示，但是查詢參數通常需要編碼URL。特別是，需要將空間替換為%20 。
為了避免淹沒服務器，我們每個IP地址強制執行速率限制：在5S窗口中允許每個IP地址15個請求。如果您超出了這些限制，您將收到具有HTTP狀態代碼429的響應。請注意，由於超過速率限制對配額的速率限製而被阻止的請求，因此在收到429響應時，您需要至少等待5s在重試之前。
要在單個記錄中獲取元數據，請使用以下類型的URL：
https://inspirehep.net/api/{identifier-type}/{identifier-value}
支持記錄標識符的兩個主要類別（即{identifier-type}和{identifier-value} ）的兩個主要類別。
這些是與網站上URL中顯示的標識符相同的標識符，也可以用於搜索。 {identifier-type}可以採用以下值：
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata {identifier-value}是一個數字，在Inspire數據庫中識別給定記錄（也稱為記錄ID或recid ）。例如，
https://inspirehep.net/api/literature/451647
是Maldacena著名的廣告/CFT紙的記錄，而
https://inspirehep.net/api/conferences/1642486
是ICHEP 2018會議的記錄。
這些是持續的標識符，不是由Inspire分配的，但仍然唯一地標識了Inspire（如果系統中存在相應標識符的記錄）。
可以使用以下外部標識符：
{identifier-type} | {identifier-value} （示例） | 用法 |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | 獲得文學記錄給定doi |
arxiv | 1207.7214 ， hep-ph/0603175 | 為了獲得ARXIV標識符的文獻記錄 |
orcid | 0000-0003-3897-046X | 要獲得給定orcid ID的作者記錄 |
例如，
https://inspirehep.net/api/orcid/0000-0002-9079-593X
是斯蒂芬·霍金斯（Stephen Hawkings）的作者記錄。
默認情況下，檢索單個記錄時的API響應將處於JSON格式，並包含以下鍵：
| 鑰匙 | 描述 |
|---|---|
id | 標識符用於檢索記錄 |
created | UTC中記錄的創建時間戳 |
updated | UTC中記錄的最後更新時間戳 |
links | 鏈接與記錄相關的資源 |
metadata | 記錄的元數據 |
無論使用什麼標識符來檢索記錄，它也將存在metadata內部（以及屬於此記錄的其他標識符）。
links對象包含與此記錄相關的元數據的鏈接，但未直接包含在記錄中（例如引用信息）和替代序列化格式（例如Bibtex）。
metadata對象包含正確的記錄的元數據。所有記錄都有一個$schema密鑰，該密鑰鏈接到記錄元數據的JSON模式（草案4）。有關每個模式的可能字段及其含義的詳細文檔可以在模式文檔中找到。
例如， Literature的metadata記錄符合hep模式，HEP模式在這裡記錄了其字段。
可以獲得與默認JSON不同格式的記錄（或多個記錄）的表示形式。這可以通過兩種替代方式完成：
format={format-name} url查詢字符串，或Accept HTTP標頭設置為特定的MIME類型。當前，支持以下格式（僅用於Literature記錄）：
{format-name} | 啞劇類型 | 描述 |
|---|---|---|
| JSON | 應用程序/JSON | 默認的JSON格式 |
| Bibtex | 應用程序/X-Bibtex | Bibtex引文格式 |
| 乳膠 - 歐盟 | 應用程序/vnd+inspire.latex.eu+x-latex | 乳膠（EU）引文格式 |
| 乳膠 - US | 應用程序/vnd+inspire.latex.us+x-latex | 乳膠（美國）引文格式 |
| 簡歷 | text/vnd+inspire.html+html | CV HTML引文格式 |
在JSON響應中的links對像中也可以找到指向替代格式的鏈接。
例如，要獲取Glashow關於Bibtex格式弱相互作用的著名論文，請使用格式參數：
https://inspirehep.net/api/literature/4328?format=bibtex
或等同於內容談判（示例使用curl命令行工具來設置標題）：
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
為了獲得搜索結果，而不是通過其標識符獲取單個記錄的數據，請使用以下表格的基本URL：
https://inspirehep.net/api/{record-type}?{query-string}
{record-type}必須是：
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata請注意，這些與內部標識符類型相同。
{query-string}可能包含幾個{parameter}={value}對由&分開的。始終支持以下參數：
{parameter} | {value}的描述 |
|---|---|
q | 搜索查詢 |
sort | 排序順序 |
size | 每個頁面返回的結果數 |
page | 頁碼 |
fields | 元數據中的田地 |
此外，根據{record-type}不同，可以使用不同的方面過濾器來限制結果集。它們的工作方式與網站上的方式完全相同。
例如，要獲得第六至第10個即將舉行的會議，可以使用以下URL：
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
要獲得至少1000次引用的10篇最新論文，請使用：
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
q查詢字符串參數允許指定僅與記錄子集匹配的搜索查詢。
對於文獻記錄（通過/api/literature端點獲得），自定義搜索語法用於與Spiers和舊Inspire的向後兼容。這裡解釋了。此外，可以使用將嵌套鍵與與嵌套密鑰相連給定的路徑來搜索記錄元數據的任何字段. ，然後是:以及搜索的價值。
例如，要查找來自Springer摘要的所有論文，可以使用以下搜索：
https://inspirehep.net/api/literature?q=abstracts.source:Springer
要查找以愛德華·維滕（Edward Witten）為由的所有會議論文，您可以使用：
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
要檢查是否存在字段，您可以使用*通配符。例如，要查找所有具有DOI的論文，您可以使用：
https://inspirehep.net/api/literature?q=dois.value:*
對於其他類型的記錄，使用Elasticsearch查詢字符串語法。在這裡，也可以使用將嵌套鍵與與之相連的路徑來搜索記錄元數據的任何字段. ，然後是:以及搜索的價值。
例如，要使用CERN質子合成器（PS）加速器找到所有實驗，請使用
https://inspirehep.net/api/experiments?q=accelerator.value:PS
同樣，要找到具有給定Inspire ID的作者，請使用
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
返回搜索結果的順序取決於是否提供了搜索查詢。
默認情況下，
q查詢參數），則將結果與最新記錄進行排序，q查詢參數），則首先將結果與最相關的結果進行排序。可以用sort={sort-order}查詢參數覆蓋此行為。支持以下選項：
{record-type} | {sort-order} | 描述 |
|---|---|---|
literature | mostrecent | 最近的記錄首先出現（根據元數據的最早日期） |
literature | mostcited | 大多數引用的記錄首先出現 |
jobs | mostrecent | 最近創建的作業出現了 |
jobs | deadline | 最早截止日期的工作出現在第一個 |
conferences | dateasc | 最早開始的會議出現 |
conferences | datedesc | 與最新開始日期的會議出現 |
seminars | dateasc | 最早開始的研討會首次出現 |
seminars | datedesc | 最新開始時間的研討會首次出現 |
例如，以下URL將返回愛德華·維滕（Edward Witten）的10篇論文：
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
搜索結果以頁面返回以限制響應的大小。默認情況下，每個頁面返回10個結果，並返回結果的第一頁。要進入下一個頁面，您可以將頁碼傳遞到page查詢參數。
例如，使用以下URL獲取愛德華·維滕（Edward Witten）的第31至40個最多引用的論文。
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
要進行下一頁，可以遵循響應中links對象的next URL（使用默認JSON格式時）。
每個頁面的結果數可以用size查詢參數覆蓋。為了不超載服務器，最大允許的值為1000 ，如果超過該服務器，則使用HTTP狀態代碼400獲得響應。
例如，要立即獲得愛德華·維滕（Edward Witten）的50篇論文，可以使用以下URL：
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
請注意，除了每個頁面返回的結果的限制外，當前還有一個技術限制，可以防止為給定的搜索查詢檢索10000多個結果。解決方法是將單個搜索分解為幾個搜索，每個搜索的結果少於10000個。有關更多信息，請參見此評論。
搜索的響應是帶有以下鍵的JSON對象：
hits ：包含總計結果total和hits記錄的總數（這是一個數組，其元素的結構與單記錄響應中的結構相同）links ：指向相關資源的鏈接，例如搜索結果的替代序列化以及next 。請注意，記錄元數據（以hits.hits.metadata為單位）包含的字段多於單記錄響應。其中大多數是用於內部用途的：不應依靠架構的任何一部分的任何字段，也不能保證它會保留或它的內容不會改變，但除了：
/api/literature| 鑰匙 | 價值（示例） | 描述 |
|---|---|---|
earliest_date | 2020-03-18 | 記錄最早的日期 |
citation_count | 243 | 此記錄收到的引用總數 |
citation_count_without_self_citations | 213 | 該記錄收到的引用數量，不包括自我引用 |
有時，您可能只對記錄元數據的某些特定領域感興趣，而不是整個記錄。為了避免生成和下載可以很大的響應，可以使用fields查詢參數。它應設置為需要在記錄元數據中存在的逗號分隔的字段列表。
例如，以下URL將僅返回具有1000多個引用的論文的標題，作者姓名和鏈接：
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
元數據過濾僅在搜索中可用，而不是用於單個記錄響應。但是，如果您知道要獲得部分元數據的記錄標識符，則可以對該標識符進行搜索，這將僅返回一個記錄。
例如，以下URL將在https://inspirehep.net/api/literature/4328中為您提供記錄的引用計數：
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
請注意，不可能對數組的元素數量限制，但只能選擇該數組是否應該出現。例如，不可能僅選擇前10位作者，但是可以通過不將authors （或其任何子場）在fields中避免回歸作者。
除書目數據庫外，Inspire還提供了一種工具，可以從包含cite{...}命令（或變體）的Tex文件中生成參考書目，其鍵尊重特定的慣例，該鍵允許系統推斷引用的記錄。交互式工具中提供了更詳細的說明。
要通過API訪問它，您需要在https://inspirehep.net/api/bibliography-generator上向端點提出發布請求，並提供以下數據：
format請求參數，其值為bibtex ， latex_eu或latex_us具體取決於所需的書目格式file鍵，其中包含形式編碼的文件作為參數。響應將是一個帶有單個data密鑰的JSON對象，其值是在download_url下包含生成的書目文件的對象，並且在errors下遇到錯誤的錯誤（如果該過程中沒有錯誤，則為空）。
例如用curl ：
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
當使用流行的Python requests包時，可以按照其文檔中的解釋來完成此操作。
幾種不同語言的工具正在使用此API。他們的代碼可能是實際示例的有用來源。
如果您想列出您的項目，請隨時告訴我們。
