rest api doc
v2021.2
Inspire adalah pusat komunitas tepercaya yang membantu para peneliti untuk berbagi dan menemukan informasi ilmiah yang akurat dalam fisika energi tinggi. Selain antarmuka web biasa untuk akses interaktif ke kontennya, API REST disediakan untuk akses terprogram. Dokumen ini menjelaskan cara menggunakan API REST ini.
Jika Anda menggunakan API dalam pekerjaan ilmiah, silakan mengutipnya menggunakan metadata berikut:
@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 "
}Jika Anda memiliki masalah menggunakan API, ingin bantuan, atau memiliki beberapa saran untuk meningkatkan API atau dokumentasinya, buka masalah atau hubungi kami.
Penggunaan API diatur oleh ketentuan penggunaan kami. Seperti yang dijelaskan di sana secara lebih rinci, sebagian besar metadata tersedia di bawah lisensi CC0, tetapi pembatasan berlaku untuk beberapa bidang, dan koleksi massal alamat email tidak diizinkan.
API umumnya tenang dan hasilnya menghasilkan JSON secara default. Ini berarti misalnya bahwa ia akan mengembalikan kode status HTTP 404 jika catatan tidak dapat ditemukan.
Secara umum, sebagian besar halaman yang Anda dapatkan melalui situs web memiliki representasi yang sesuai di API yang diperoleh dengan mengawali komponen jalur URL dengan /api/ . Misalnya, data yang ditampilkan di
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
tersedia melalui API di
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
Saat ini hanya operasi read-only pada catatan yang diizinkan dan semuanya menggunakan metode GET HTTP.
Perhatikan bahwa semua contoh ditampilkan dengan cara yang dapat dibaca manusia, tetapi parameter kueri sering perlu dikodekan URL. Secara khusus, ruang perlu diganti dengan %20 .
Untuk menghindari membanjiri server, kami menegakkan batas tingkat per alamat IP: Setiap alamat IP diizinkan 15 permintaan di jendela 5S. Jika Anda melebihi batas -batas itu, Anda akan menerima tanggapan dengan kode status HTTP 429. Harap dicatat bahwa permintaan yang diblokir karena melebihi jumlah batas tarif menuju kuota, jadi Anda harus menunggu setidaknya 5s saat menerima respons 429 respons 429 sebelum mencoba lagi.
Untuk mendapatkan metadata dalam satu catatan, gunakan jenis URL berikut:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Dua kategori utama pengidentifikasi catatan (yaitu pasangan {identifier-type} dan {identifier-value} ) didukung.
Ini adalah pengidentifikasi yang sama seperti yang muncul di URL di situs web dan juga dapat digunakan untuk mencari. {identifier-type} dapat mengambil nilai berikut:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata dan {identifier-value} adalah angka yang mengidentifikasi catatan yang diberikan dalam database Inspire (juga disebut Record ID atau recid ). Misalnya,
https://inspirehep.net/api/literature/451647
adalah catatan kertas iklan/cft Maldacena yang terkenal, sedangkan
https://inspirehep.net/api/conferences/1642486
adalah catatan konferensi ICHEP 2018.
Ini adalah pengidentifikasi persisten yang tidak ditugaskan oleh Inspire tetapi tetap secara unik mengidentifikasi catatan dalam Inspire (jika catatan untuk pengidentifikasi yang sesuai ada dalam sistem).
Pengidentifikasi eksternal berikut dapat digunakan:
{identifier-type} | {identifier-value} (contoh) | Penggunaan |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | Untuk mendapatkan catatan literatur yang diberikan doi |
arxiv | 1207.7214 , hep-ph/0603175 | Untuk mendapatkan catatan literatur yang diberikan pengidentifikasi arxiv |
orcid | 0000-0003-3897-046X | Untuk mendapatkan catatan penulis yang diberikan ID orcid |
Misalnya,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
adalah catatan penulis Stephen Hawkings.
Secara default, respons API saat mengambil satu catatan akan berada dalam format JSON dan berisi tombol -tombol berikut:
| Kunci | Keterangan |
|---|---|
id | Identifier digunakan untuk mengambil catatan |
created | Creation Timestamp dari catatan di UTC |
updated | Cap waktu pembaruan terakhir dari catatan di UTC |
links | Tautan ke sumber daya yang terkait dengan catatan |
metadata | Metadata catatan |
Apa pun pengidentifikasi yang digunakan untuk mengambil catatan, itu juga akan hadir (serta pengidentifikasi lainnya yang termasuk dalam catatan ini) di dalam metadata .
Objek links berisi tautan ke metadata yang terkait dengan catatan ini tetapi tidak secara langsung termasuk dalam catatan (misalnya informasi kutipan), dan format serialisasi alternatif (misalnya Bibtex).
Objek metadata berisi metadata catatan yang tepat. Semua catatan memiliki kunci $schema , yang menautkan ke skema JSON (draft 4) yang menurut metadata catatan. Dokumentasi terperinci tentang kemungkinan bidang untuk setiap skema dan artinya dapat ditemukan dalam dokumentasi skema.
Misalnya, metadata catatan Literature sesuai dengan skema hep , yang bidangnya didokumentasikan di sini.
Dimungkinkan untuk mendapatkan representasi catatan (atau beberapa catatan) dalam format yang berbeda dari JSON default. Ini dapat dilakukan dengan dua cara alternatif:
format={format-name} URL Query String, atauAccept ke jenis MIME tertentu. Saat ini, format berikut didukung (hanya untuk catatan Literature ):
{format-name} | Jenis pantomim | Keterangan |
|---|---|---|
| json | Aplikasi/JSON | Format JSON default |
| Bibtex | Aplikasi/X-BIBTEX | Format Kutipan Bibtex |
| Lateks-EU | Aplikasi/VND+INSPIRE.LATEX.EU+X-LATEX | Format Kutipan Lateks (EU) |
| Lateks-AS | Aplikasi/VND+INSPIRE.LATEX.US+X-LATEX | Format Kutipan Lateks (AS) |
| cv | Teks/VND+Inspire.html+html | Format Kutipan CV HTML |
Tautan ke format alternatif juga dapat ditemukan di objek links di dalam respons JSON.
Misalnya, untuk mendapatkan makalah terkenal Glashow tentang interaksi yang lemah dalam format Bibtex, gunakan parameter format:
https://inspirehep.net/api/literature/4328?format=bibtex
atau setara, negosiasi konten (contoh menggunakan alat baris perintah curl untuk mengatur header):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
Untuk mendapatkan hasil untuk pencarian daripada mendapatkan data dari satu catatan dengan pengidentifikasinya, gunakan URL dasar dari formulir berikut:
https://inspirehep.net/api/{record-type}?{query-string}
{record-type} harus menjadi salah satu dari:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdataPerhatikan bahwa ini sama dengan tipe pengidentifikasi internal.
{query-string} dapat berisi beberapa {parameter}={value} pasangan dipisahkan oleh & . Parameter berikut selalu didukung:
{parameter} | Deskripsi {value} |
|---|---|
q | Kueri pencarian |
sort | Pesanan Sortir |
size | Jumlah hasil yang dikembalikan per halaman |
page | Nomor halaman |
fields | Ladang di metadata akan dikembalikan |
Selain itu, tergantung pada {record-type} , filter facet yang berbeda tersedia untuk membatasi set hasil. Mereka bekerja dengan cara yang persis sama seperti di situs web.
Misalnya, untuk mendapatkan konferensi ke -6 hingga 10 yang akan datang, URL berikut dapat digunakan:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
Untuk mendapatkan 10 makalah terbaru yang dikutip setidaknya 1000 kali, gunakan:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
Argumen String q Query memungkinkan untuk menentukan kueri pencarian yang hanya cocok dengan subset catatan.
Untuk catatan literatur (diperoleh melalui titik akhir /api/literature ), sintaks pencarian khusus digunakan untuk kompatibilitas ke belakang dengan menara dan inspirasi lama. Itu dijelaskan di sini. Selain itu, bidang apa pun dari metadata catatan dapat dicari menggunakan jalurnya yang diberikan dengan menggabungkan kunci bersarang . , diikuti oleh : dan nilai yang akan dicari.
Misalnya, untuk menemukan semua makalah yang memiliki abstrak dari Springer, pencarian berikut dapat digunakan:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
Untuk menemukan semua makalah konferensi yang mengutip Edward Witten, Anda dapat menggunakan:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
Untuk memeriksa apakah ada bidang, Anda dapat menggunakan * wildcard. Misalnya, untuk menemukan semua kertas memiliki doi, Anda dapat menggunakan:
https://inspirehep.net/api/literature?q=dois.value:*
Untuk jenis catatan lain, sintaks string query Elasticsearch digunakan. Di sini juga, bidang apa pun dari metadata catatan dapat dicari menggunakan jalurnya yang diberikan dengan menggabungkan kunci bersarang . , diikuti oleh : dan nilai yang akan dicari.
Misalnya, untuk menemukan semua percobaan menggunakan akselerator CERN Proton-Synchotron (PS), gunakan
https://inspirehep.net/api/experiments?q=accelerator.value:PS
Demikian pula, untuk menemukan penulis dengan ID Inspire yang diberikan, gunakan
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
Urutan di mana hasil pencarian dikembalikan tergantung pada apakah kueri pencarian disediakan.
Secara default,
q query), hasilnya diurutkan dengan catatan terbaru terlebih dahulu,q ), hasilnya diurutkan dengan yang paling relevan terlebih dahulu. Perilaku ini dapat ditimpa dengan parameter kueri sort={sort-order} . Opsi berikut didukung:
{record-type} | {sort-order} | Keterangan |
|---|---|---|
literature | mostrecent | Catatan terbaru muncul pertama (berdasarkan tanggal paling awal di metadata) |
literature | mostcited | Catatan dengan sebagian besar kutipan muncul pertama kali |
jobs | mostrecent | Pekerjaan yang paling baru dibuat muncul lebih dulu |
jobs | deadline | Pekerjaan dengan tenggat waktu paling awal muncul lebih dulu |
conferences | dateasc | Konferensi dengan tanggal mulai yang paling awal muncul lebih dulu |
conferences | datedesc | Konferensi dengan tanggal mulai terbaru muncul pertama kali |
seminars | dateasc | Seminar dengan waktu mulai paling awal muncul lebih dulu |
seminars | datedesc | Seminar dengan waktu mulai terbaru muncul pertama kali |
Misalnya, URL berikut akan mengembalikan 10 makalah Edward Witten yang paling banyak dikutip:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
Hasil pencarian dikembalikan di halaman untuk membatasi ukuran respons. Secara default, 10 hasil dikembalikan per halaman dan halaman pertama hasil dikembalikan. Untuk sampai ke halaman berikutnya, Anda dapat meneruskan nomor halaman ke parameter kueri page .
Misalnya, gunakan URL berikut untuk mendapatkan makalah Edward Witten yang paling banyak dikutip.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
Untuk pergi ke halaman berikutnya, URL next dari objek links dalam respons dapat diikuti (saat menggunakan format JSON default).
Jumlah hasil per halaman dapat ditimpa dengan parameter kueri size . Agar tidak kelebihan beban server, nilai maksimum yang diizinkan adalah 1000 , dan Anda akan mendapatkan respons dengan kode status HTTP 400 jika Anda melampaui itu.
Misalnya, untuk mendapatkan 50 makalah yang paling banyak dikutip dari Edward Witten sekaligus, URL berikut dapat digunakan:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
Perhatikan bahwa, selain batas hasil yang dikembalikan per halaman, saat ini ada batasan teknis yang mencegah pengambilan lebih dari 10.000 hasil untuk permintaan pencarian yang diberikan. Penanganan solusi adalah memecah pencarian tunggal menjadi beberapa pencarian yang masing -masing memiliki kurang dari 10000 hasil. Lihat komentar ini untuk informasi lebih lanjut.
Respons untuk pencarian adalah objek JSON dengan kunci berikut:
hits : Berisi jumlah total hasil secara total dan catatan dalam hits (yang merupakan array yang elemennya memiliki struktur yang sama seperti dalam respons rekor tunggal)links : Tautan ke Sumber Daya Terkait, seperti Serializasi Alternatif dari Hasil Pencarian dan Halaman Berikutnya di next . Perhatikan bahwa metadata catatan (dalam hits.hits.metadata ) berisi lebih banyak bidang daripada dalam respons rekaman tunggal. Sebagian besar dari mereka adalah untuk penggunaan internal: bidang apa pun yang bukan bagian dari skema tidak boleh diandalkan, dan tidak ada jaminan bahwa itu akan tetap ada atau bahwa isinya tidak akan berubah , dengan pengecualian dari:
/api/literature| kunci | nilai (contoh) | keterangan |
|---|---|---|
earliest_date | 2020-03-18 | tanggal paling awal dalam catatan |
citation_count | 243 | Jumlah total kutipan yang diterima oleh catatan ini |
citation_count_without_self_citations | 213 | Jumlah kutipan yang diterima dengan catatan ini, tidak termasuk diri sendiri |
Terkadang, Anda mungkin hanya tertarik pada beberapa bidang spesifik dari metadata catatan dan tidak dalam seluruh catatan. Untuk menghindari menghasilkan dan mengunduh respons penuh, yang bisa sangat besar, parameter fields Query dapat digunakan. Ini harus diatur ke daftar bidang yang dipisahkan koma yang perlu hadir dalam metadata catatan.
Misalnya, URL berikut hanya akan mengembalikan judul, nama penulis dan tautan ke catatan afiliasi makalah dengan lebih dari 1000 kutipan:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
Penyaringan metadata hanya tersedia dalam pencarian, bukan untuk respons rekaman tunggal. Namun, jika Anda mengetahui pengidentifikasi catatan yang Anda inginkan untuk mendapatkan metadata parsial, Anda dapat melakukan pencarian untuk pengidentifikasi itu, yang hanya akan mengembalikan satu catatan.
Misalnya, URL berikut akan memberi Anda jumlah kutipan dari catatan di https://inspirehep.net/api/literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
Perhatikan bahwa tidak mungkin untuk membatasi jumlah elemen array, tetapi hanya memilih apakah array itu akan muncul sama sekali. Misalnya, tidak mungkin untuk memilih hanya 10 penulis pertama, tetapi dimungkinkan untuk menghindari penulis yang kembali dengan tidak menempatkan authors (atau salah satu subbidangnya) di antara fields .
Selain database bibliografi, Inspire menawarkan alat untuk menghasilkan daftar pustaka dari file TEX yang berisi perintah cite{...} (atau varian) dengan kunci yang menghormati konvensi spesifik yang memungkinkan sistem untuk menyimpulkan catatan yang dikutip. Instruksi yang lebih rinci tersedia di alat interaktif.
Untuk mengaksesnya melalui API, Anda perlu membuat permintaan pos ke titik akhir di https://inspirehep.net/api/bibliography-generator , dengan data berikut:
format yang nilainya adalah bibtex , latex_eu atau latex_us tergantung pada format bibliografi yang diperlukanfile tunggal yang berisi file yang dikodekan formulir sebagai argumen. Responsnya akan menjadi objek JSON dengan kunci data tunggal yang nilainya adalah objek yang berisi URL ke file bibliografi yang dihasilkan di bawah download_url dan array kesalahan yang ditemui di bawah errors (yang kosong jika tidak ada kesalahan dalam proses).
Misalnya dengan curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
Saat menggunakan paket requests Python yang populer, ini dapat dilakukan seperti yang dijelaskan dalam dokumentasinya.
Beberapa alat dalam berbagai bahasa menggunakan API ini. Kode mereka mungkin berfungsi sebagai sumber yang berguna dari contoh dunia nyata.
Jika Anda ingin proyek Anda terdaftar, jangan ragu untuk memberi tahu kami.
