rest api docダウンロードrest api docソースコードのダウンロード

rest api doc

その他のソースコード

v2021.2

ダウンロード

REST APIを刺激します

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 "
}

REST APIを刺激します
- 質問とコメント
- 利用規約
- APIの概要
- レート制限
- レコードを取得します
  - 内部識別子
  - 外部識別子
- 単一記録応答
  - リンク
  - メタデータ
- フォーマットの変更
- 検索
  - クエリを検索します
  - 並べ替え
  - ページネーション
  - 応答を検索します
  - メタデータフィルタリング
- 参考文献ジェネレーター
- 野生でのAPI使用

質問やコメント

APIを使用して問題がある場合、ヘルプが必要な場合、またはAPIまたはそのドキュメントを改善するための提案がある場合は、問題を開くか、お問い合わせください。

利用規約

APIの使用は、当社の利用規約によって管理されます。詳細に説明したように、メタデータのほとんどはCC0ライセンスの下で入手できますが、一部のフィールドには制限が適用され、電子メールアドレスの一括コレクションは許可されていません。

APIの概要

通常、APIはRESTFULであり、デフォルトでJSONで結果を返します。これは、たとえば、レコードが見つからない場合に404 HTTPステータスコードを返すことを意味します。

一般に、Webサイトを通過するほとんどのページには、 /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アドレスごとのレート制限を実施します。すべてのIPアドレスは、5Sウィンドウで15のリクエストを許可されます。これらの制限を超える場合、HTTPステータスコード429で応答を受け取ります。クォータに向かってレート制限カウントを超えるためにブロックされるリクエストに注意してください。もう一度試す前に。

レコードを取得します

メタデータを単一のレコードで取得するには、次のタイプのURLを使用してください。

 https://inspirehep.net/api/{identifier-type}/{identifier-value}

レコード識別子の2つの主要なカテゴリ（つまり、 {identifier-type}と{identifier-value}のペア）がサポートされています。

内部識別子

これらは、WebサイトのURLに表示されるのと同じ識別子であり、検索にも使用できます。 {identifier-type}は、次の値を取得できます。

literature
authors
institutions
conferences
seminars
journals
jobs
experiments
data

{identifier-value}は、Inspireデータベース（レコードIDまたはrecidとも呼ばれます）の指定されたレコードを識別する数字です。例えば、

 https://inspirehep.net/api/literature/451647

マルダセナの有名な広告/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オブジェクトには、適切なレコードのメタデータが含まれています。すべてのレコードには、レコードメタデータが従うJSONスキーマ（ドラフト4）にリンクする$schemaキーがあります。各スキーマの可能なフィールドとその意味に関する詳細なドキュメントは、スキーマドキュメントに記載されています。

たとえば、 Literature記録のmetadata 、 hepスキーマに準拠しており、そのフィールドはここに文書化されています。

フォーマットの変更

デフォルトのJSONとは異なる形式でレコード（または複数のレコード）の表現を取得することができます。これは、2つの代替方法で実行できます。

format={format-name} url query string、または
コンテンツネゴシエーションを通じて、 Accept HTTPヘッダーを特定のMIMEタイプに設定します。

現在、次の形式がサポートされています（ Literature記録のみ）。

`{format-name}`	MIMEタイプ	説明
JSON	アプリケーション/JSON	デフォルトのJSON形式
bibtex	アプリケーション/x-bibtex	bibtex引用形式
ラテックス-EU	Application/vnd+inspire.latex.eu+x-latex	ラテックス（EU）引用形式
ラテックスUS	Application/vnd+inspire.latex.us+x-latex	ラテックス（米国）引用形式
cv	text/vnd+inspire.html+html	CV HTML引用形式

代替形式へのリンクは、JSON応答内のlinksオブジェクトにもあります。

たとえば、Bibtex形式での弱い相互作用に関するGlashowの有名な論文を取得するには、形式のパラメーターを使用します。

 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}は次のいずれかでなければなりません。

literature
authors
institutions
conferences
seminars
journals
jobs
experiments
data

これらは内部識別子タイプと同じであることに注意してください。

{query-string}には{parameter}={value} & 。次のパラメーターは常にサポートされています。

`{parameter}`	`{value}`の説明
`q`	検索クエリ
`sort`	ソートオーダー
`size`	ページごとに返される結果の数
`page`	ページ番号
`fields`	返品されるメタデータのフィールド

さらに、 {record-type}に応じて、結果のセットを制限するために、異なるファセットフィルターを使用できます。彼らはウェブサイトとまったく同じように動作します。

たとえば、今後の6日から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 query文字列引数を使用すると、レコードのサブセットのみに一致する検索クエリを指定できます。

文献記録（ /api/literatureエンドポイントを介して取得）の場合、カスタム検索構文は、スパイと古いインスパイアとの逆方向の互換性に使用されます。ここで説明しています。さらに、レコードメタデータの任意のフィールドは、ネストされたキーを連結することにより与えられたパスを使用して検索できます. 、A :および検索する値が続きます。
たとえば、Springerの要約を持つすべての論文を見つけるために、次の検索を使用できます。

 https://inspirehep.net/api/literature?q=abstracts.source:Springer

エドワード・ウィッテンを引用しているすべての会議の論文を見つけるには、以下を使用できます。

 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クエリ文字列構文が使用されます。ここでも、ネストされたキーを連結することで与えられたパスを使用して、レコードメタデータの任意のフィールドを検索できます. 、A :および検索する値が続きます。
たとえば、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が最初に表示されます
`jobs`	`deadline`	最古の締め切りのある仕事が最初に現れます
`conferences`	`dateasc`	最も早い開始日との会議が最初に表示されます
`conferences`	`datedesc`	最新の開始日との会議が最初に表示されます
`seminars`	`dateasc`	最も早い開始時間のセミナーが最初に表示されます
`seminars`	`datedesc`	最新の開始時間のセミナーが最初に表示されます

たとえば、次のURLはエドワードウィッテンの最も引用された10の論文を返します。

 https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1

ページネーション

検索結果は、応答のサイズを制限するためにページに返されます。デフォルトでは、ページごとに10の結果が返され、結果の最初のページが返されます。次のページにアクセスするには、ページ番号をpageクエリパラメーターに渡すことができます。

たとえば、次のURLを使用して、エドワードウィッテンの31〜40番目に引用された論文を取得します。

 https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1

次のページに移動するには、応答のlinksオブジェクトのnext URLに従うことができます（デフォルトのJSON形式を使用する場合）。

ページごとの結果数は、 sizeクエリパラメーターでオーバーライデンになる可能性があります。サーバーに過負荷をかけないために、最大許容値は1000であり、HTTPステータスコード400を超えると応答が得られます。

たとえば、エドワードウィッテンの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は、タイトル、著者の名前、リンクのみを返します。

 https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+

メタデータフィルタリングは、単一のレコード応答ではなく、検索でのみ使用できます。ただし、部分的なメタデータを取得したいレコードの識別子を知っている場合は、その識別子の検索を実行できます。これにより、1つのレコードのみが返されます。

たとえば、次のURLでは、https：//inspirehep.net/api/literature/4328でレコードの引用数を提供します。

 https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328

配列の要素の数に制限を設けることはできないが、その配列がまったく表示されるかどうかを選択することのみであることに注意してください。たとえば、最初の10人の著者のみを選択することはできませんが、 fieldsにauthors （またはそのサブフィールド）を入れないことで著者を返すことを避けることは可能です。

参考文献ジェネレーター

書誌データベースに加えて、Inspireは、システムが引用されたレコードを推測できる特定の規則を尊重するキーを含むcite{...}コマンド（またはバリアント）を含むTexファイルから参考文献を生成するツールを提供します。より詳細な指示は、インタラクティブツールで入手できます。

APIを介してアクセスするには、次のデータを使用して、https： https://inspirehep.net/api/bibliography-generatorのエンドポイントへの投稿リクエストを行う必要があります。

必要な参考文献形式に応じて、値がbibtex 、 latex_eu 、またはlatex_usのいずれかであるformat要求引数
引数としてフォームエンコードされたファイルを含む単一のfileキーを備えたフォームエンコードボディ。

応答は、 download_urlの下で生成された参考文献ファイルにURLを含むオブジェクトと、 errorsの下での遭遇したエラーの配列を持つ単一のdataキーを持つJSONオブジェクトになります（プロセスにエラーがない場合は空です）。

たとえば、 curlで：

 curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"

人気のあるPython requestsパッケージを使用する場合、これはドキュメントで説明されているように実行できます。

野生でのAPI使用

異なる言語のいくつかのツールがこのAPIを使用しています。彼らのコードは、実際の例の有用なソースとして機能する可能性があります。

PHP：
- Inspirejson
Python：
- citations.py
- ADS2INSPIRE
- 共著者
- track_inspire-hep_citations
- 鼓舞する
- InspireHepcitationStracker
Perl：
- Inspirejson
Objective-C：
- spires.app/inspire.app
- ビブデスク
JavaScript：
- Zotero Inspire Metadata Updater
タイプスクリプト：
- Raycast Inspire HEP検索拡張機能
emacs lisp：
- inspirehep.el