rest api doc
v2021.2
Inspire - это надежный общественный центр, который помогает исследователям делиться и найти точную научную информацию в области физики с высокой энергией. В дополнение к обычному веб -интерфейсу для интерактивного доступа к его контенту, для программного доступа предоставляется API REST. В настоящем документе объясняется, как использовать этот API REST.
Если вы используете 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 по умолчанию. Это означает, например, что он вернет код состояния HTTP 404, если запись не может быть найдена.
В целом, большинство страниц, которые вы получаете через веб -сайт, имеют соответствующее представление в 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 -адрес разрешен 15 запросов в окне 5S. Если вы превышаете эти пределы, вы получите ответ с кодом состояния HTTP 429. Обратите внимание, что запросы, которые заблокированы из -за превышения количества пределов ставки в направлении квоты, поэтому вам нужно ждать не менее 5 с при получении ответа 429 Прежде чем попробовать снова.
Чтобы получить метаданные в одной записи, используйте следующий тип URL:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Поддерживаются две основные категории идентификаторов записей (то есть пары {identifier-type} и {identifier-value} ).
Это те же идентификаторы, которые появляются в URL -адресах на веб -сайте, а также могут использоваться для поиска. {identifier-type} может принимать следующие значения:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata и {identifier-value} -это число, идентифицирующее данную запись в базе данных Inspire (также называется идентификатором записи или recid ). Например,
https://inspirehep.net/api/literature/451647
это запись знаменитой рекламы/CFT бумаги Maldacena, тогда как
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 | Чтобы получить запись автора, с учетом идентификатора орцида |
Например,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
это запись автора Стивена Хокинга.
По умолчанию ответ API при получении одной записи будет в формате JSON и содержит следующие ключи:
| Ключ | Описание |
|---|---|
id | Идентификатор, используемый для извлечения записи |
created | Триметичка создания записи в UTC |
updated | Последнее обновление временной метки записи в UTC |
links | Ссылки на ресурсы, связанные с записи |
metadata | Метаданные записи |
Какой бы идентификатор использовался для получения записи, он также будет присутствовать (а также другие идентификаторы, принадлежащие к этой записи) внутри metadata .
Объект links содержит ссылки на метаданные, связанные с этой записью, но не включают непосредственно в запись (например, информация о цитировании) и альтернативные форматы сериализации (например, Bibtex).
Объект metadata содержит метаданные собственной записи. Все записи имеют ключ $schema , который ссылается на схему JSON (проект 4), которую подчиняется записи метаданных. Подробная документация о возможных полях для каждой схемы и их значения можно найти в документации схемы.
Например, metadata Literature записи соответствуют схеме hep , чьи поля задокументированы здесь.
Можно получить представление записи (или нескольких записей) в другом формате из JSON по умолчанию. Это можно сделать двумя альтернативными способами:
format={format-name} строка URL-запроса илиAccept HTTP на конкретный тип MIME. В настоящее время поддерживаются следующие форматы (только для Literature записей):
{format-name} | Тип мима | Описание |
|---|---|---|
| json | Приложение/JSON | Формат JSON по умолчанию |
| Бибтекс | приложение/x-bibtex | Формат цитирования Bibtex |
| латекс-ев | Application/vnd+Inspire.latex.eu+x-latex | Формат цитирования латекса (ЕС) |
| Латекс-США | Application/vnd+Inspire.latex.us+X-Latex | Формат цитирования латекса (США) |
| резюме | Text/vnd+Inspire.html+html | Формат цитирования CV HTML |
Ссылки на альтернативные форматы также можно найти в объекте links внутри ответа JSON.
Например, чтобы получить знаменитую статью Глашова о слабых взаимодействиях в формате 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} , доступны различные аспектные фильтры для ограничения набора результатов. Они работают точно так же, как и на сайте.
Например, чтобы получить 6 -й по 10 -й предстоящие конференции, можно использовать следующий URL:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
Чтобы получить 10 самых последних работ, цитируемых не менее 1000 раз, используйте:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
Аргумент строки q Запрос позволяет указать поисковый запрос, который соответствует только подмножеству записей.
Для литературных записей (полученных через конечную точку /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 Query. Здесь также можно искать любую область метаданных записей, используя его путь, приведенный путем объединения вложенных ключей . , затем A : и значение для поиска.
Например, чтобы найти все эксперименты с использованием акселератора CERN Proton-Synchotron (PS), используйте
https://inspirehep.net/api/experiments?q=accelerator.value:PS
Точно так же, чтобы найти автора с данным идентификатором Inspire, используйте
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 вернет 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
Чтобы перейти на следующую страницу, можно соблюдать next URL -адрес объекта links в ответе (при использовании формата 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 вернет только названия, имена авторов и ссылки на записи о принадлежности документов с более чем 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 предлагает инструмент для генерации библиографии из файла TEX, содержащего cite{...} команды (или варианты) с ключами, которые уважают конкретное соглашение, которое позволяет системе вывода цитируемой записи. Более подробные инструкции доступны в интерактивном инструменте.
Чтобы получить доступ к нему через API, вам необходимо сделать запрос в конечной точке по адресу https://inspirehep.net/api/bibliography-generator , со следующими данными:
format , значение которого состоит либо bibtex , latex_eu , либо latex_us в зависимости от необходимого библиографического форматаfile содержащий файл, кодируемый формой, в качестве аргумента. Ответ будет объектом JSON с одним ключом data , значение которого является объектом, содержащим URL -адрес сгенерированного файла библиографии в разделе download_url , и массив встречаемых ошибок при errors (что пусто, если в процессе нет ошибок).
Например, с curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
При использовании популярного пакета requests Python это можно сделать, как объяснено в его документации.
Несколько инструментов на разных языках используют этот API. Их код может служить полезным источником реальных примеров.
Если вы хотите, чтобы ваш проект был перечислен, не стесняйтесь сообщить нам об этом.
