INSPIRE is a trusted community hub that helps researchers to share and find accurate scholarly information in high energy physics. In addition to a regular web interface for interactive access to its content, a REST API is provided for programmatic access. The present document explains how to use this REST API.
If you use the API in a scholarly work, please cite it using the following metadata:
@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"
}- INSPIRE REST API
If you have any issues using the API, would like some help, or have some suggestions for improving the API or its documentation, please open an issue or contact us.
Usage of the API is governed by our terms of use. As explained there in more detail, most of the metadata is available under a CC0 license, but restrictions apply to some fields, and bulk collection of email addresses is not allowed.
The API is generally RESTful and returns results in JSON by default. This means for example that it will return a 404 HTTP status code if a record can't be found.
In general, most pages you get through the website have a corresponding representation in the API obtained by prefixing the path component of the URL with /api/.
For example, the data displayed at
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
is available through the API at
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
Currently only read-only operations on records are allowed and they all use the GET HTTP method.
Note that all examples are displayed in a human-readable way, but the query parameters often need to be URL-encoded. In particular, spaces need to be replaced by %20.
In order to avoid overwhelming the server, we enforce rate limits per IP address: every IP address is allowed 15 requests in a 5s window. If you exceed those limits, you will receive a response with HTTP status code 429. Please note that requests that are blocked due to exceeding the rate limit count towards the quota, so you'll need to wait at least 5s when receiving a 429 response before trying again.
To get the metadata in a single record, use the following type of URL:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
Two main categories of record identifiers (that is pairs of {identifier-type} and {identifier-value}) are supported.
These are the same identifiers as appear in the URLs on the website and can also be used for searching. The {identifier-type} can take the following values:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata
and the {identifier-value} is a number identifying the given record in the INSPIRE database (also called record ID or recid). For example,
https://inspirehep.net/api/literature/451647
is the record of Maldacena's famous AdS/CFT paper, whereas
https://inspirehep.net/api/conferences/1642486
is the record of the ICHEP 2018 conference.
These are persistent identifiers that were not assigned by INSPIRE but nevertheless uniquely identify a record in INSPIRE (if a record for the corresponding identifier exists in the system).
The following external identifiers can be used:
{identifier-type} |
{identifier-value} (examples) |
Usage |
|---|---|---|
doi |
10.1103/PhysRevLett.19.1264 |
to get a literature record given a DOI |
arxiv |
1207.7214, hep-ph/0603175 |
to get a literature record given an arXiv identifier |
orcid |
0000-0003-3897-046X |
to get an author record given an ORCID iD |
For example,
https://inspirehep.net/api/orcid/0000-0002-9079-593X
is Stephen Hawkings's author record.
By default, the API response when retrieving a single record will be in the JSON format and contain the following keys:
| Key | Description |
|---|---|
id |
Identifier used to retrieve the record |
created |
Creation timestamp of the record in UTC |
updated |
Last update timestamp of the record in UTC |
links |
Links to resources related to the record |
metadata |
Metadata of the record |
Whatever identifier is used to retrieve the record, it will also be present (as well as the other identifiers belonging to this record) inside metadata.
The links object contains links to metadata related to this record but not directly included in the record (e.g. citation information), and alternative serialization formats (e.g. BibTeX).
The metadata object contains the metadata of the record proper. All records have a $schema key, which links to a JSON schema (draft 4) that the record metadata obeys. Detailed documentation about the possible fields for each schema and their meaning can be found in the schema documentation.
For example, the metadata of Literature records conforms to the hep schema, whose fields are documented here.
It is possible to obtain a representation of a record (or several records) in a different format from the default JSON. This can be done in two alternative ways:
- using the
format={format-name}URL query string, or - through content negotiation, by setting the
AcceptHTTP header to a specific MIME type.
Currently, the following formats are supported (only for Literature records):
{format-name} |
MIME type | Description |
|---|---|---|
| json | application/json | The default JSON format |
| bibtex | application/x-bibtex | The BibTeX citation format |
| latex-eu | application/vnd+inspire.latex.eu+x-latex | The LaTeX (EU) citation format |
| latex-us | application/vnd+inspire.latex.us+x-latex | The LaTeX (US) citation format |
| cv | text/vnd+inspire.html+html | The CV HTML citation format |
Links to alternative formats can also be found in the links object inside the JSON response.
For example, to obtain Glashow's famous paper on weak interactions in BibTeX format, use either a format parameter:
https://inspirehep.net/api/literature/4328?format=bibtex
or equivalently, content negotiation (the example uses the curl command line tool to set the header):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
In order to get results for a search rather than getting the data of a single record by its identifier, use a base URL of the following form:
https://inspirehep.net/api/{record-type}?{query-string}
The {record-type} must be one of:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata
Note that these are the same as the internal identifier types.
The {query-string} may contain several {parameter}={value} pairs separated by &. The following parameters are always supported:
{parameter} |
Description of {value} |
|---|---|
q |
The search query |
sort |
The sort order |
size |
The number of results returned per page |
page |
The page number |
fields |
The fields in the metadata to be returned |
Additionally, depending on the {record-type}, different facet filters are available to restrict the set of results. They work exactly the same way as on the website.
For example, to obtain the 6th to 10th upcoming conferences, the following URL can be used:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
To obtain the 10 most recent papers cited at least 1000 times, use:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
The q query string argument allows to specify a search query that only matches a subset of records.
-
For Literature records (obtained through the
/api/literatureendpoint), a custom search syntax is used for backwards compatibility with SPIRES and the old INSPIRE. It is explained here. Additionally, any field of the record metadata can be searched using its path given by concatenating the nested keys with., followed by a:and the value to search for.For example, to find all papers having an abstract from Springer, the following search can be used:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
To find all conferences papers citing Edward Witten, you can use:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
To check whether a field exists, you can use a * wildcard. For example, to find all papers having a DOI, you can use:
https://inspirehep.net/api/literature?q=dois.value:*
-
For other types of records, the ElasticSearch query string syntax is used. Here too, any field of the record metadata can be searched using its path given by concatenating the nested keys with
., followed by a:and the value to search for.For example, to find all experiments using the CERN Proton-Synchotron (PS) accelerator, use
https://inspirehep.net/api/experiments?q=accelerator.value:PS
Similarly, to find an author with a given INSPIRE ID, use
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
The order in which search results are returned depends on whether a search query is provided.
By default,
- if no search query is provided (no
qquery parameter), results are sorted with the most recent records first, - if a search query is provided (through a
qquery parameter), results are sorted with the most relevant first.
This behavior can be overridden with the sort={sort-order} query parameter. The following options are supported:
{record-type} |
{sort-order} |
Description |
|---|---|---|
literature |
mostrecent |
Most recent records appear first (based on earliest date in metadata) |
literature |
mostcited |
Records with most citations appear first |
jobs |
mostrecent |
Most recently created jobs appear first |
jobs |
deadline |
Jobs with the earliest deadline appear first |
conferences |
dateasc |
Conferences with the earliest starting date appear first |
conferences |
datedesc |
Conferences with the most recent starting date appear first |
seminars |
dateasc |
Seminars with the earliest starting time appear first |
seminars |
datedesc |
Seminars with the most recent starting time appear first |
For example, the following URL will return Edward Witten's 10 most cited papers:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
Search results are returned in pages to limit the size of the response. By default, 10 results are returned per page and the first page of results is returned.
To get to the next pages, you can pass the page number to the page query parameter.
For example, use the following URL to get Edward Witten's 31st to 40th most cited papers.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
To go the next page, the next URL of the links object in the response can be followed (when using the default JSON format).
The number of results per page can be overriden with the size query parameter. In order not to overload the server, the maximum allowed value is 1000, and you'll get a response with HTTP status code 400 if you exceed it.
For example, to get the 50 most cited papers of Edward Witten at once, the following URL can be used:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
Note that, in addition to the limit of results returned per page, there is currently a technical limitation preventing the retrieval of more than 10000 results for a given search query. The workaround is to break up the single search into several searches having less than 10000 results each. See this comment for more information.
The response for a search is a JSON object with the following keys:
hits: contains the total number of results intotaland the records inhits(which is an array whose elements have the same structure as in the single-record response)links: links to related resources, such as alternative serializations of the search results and the next page innext.
Note that the record metadata (in hits.hits.metadata) contains more fields than in the single-record response. Most of those are for internal use: any field not part of the schema should not be relied on, and there is no guarantee that it will remain present or that its content won't change, with the exception of:
- for
/api/literature
| key | value (example) | description |
|---|---|---|
earliest_date |
2020-03-18 |
the earliest date on the record |
citation_count |
243 | the total number of citations received by this record |
citation_count_without_self_citations |
213 | the number of citations received by this record, excluding self-citations |
Sometimes, you might be interested in only some specific fields of the record metadata and not in the whole record. To avoid generating and downloading the full response, which can be quite large, the fields query parameter can be used. It should be set to a comma-separated list of fields that need to be present in the record metadata.
For example, the following URL will return only the titles, author names and links to affiliation records of papers with more than 1000 citations:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
Metadata filtering is only available in searches, not for the single record response. However, if you know an identifier of the record you want to get partial metadata for, you can perform a search for that identifier, which will return only one record.
For example, the following URL will give you the citation count of the record at https://inspirehep.net/api/literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
Note that it is not possible to put limits on the number of elements of an array, but only select whether that array should appear at all. For example, it's not possible to select only the first 10 authors, but it's possible to avoid returning authors by not putting authors (or any of its subfields) among the fields.
In addition to the bibliographic databases, INSPIRE offers a tool to generate a bibliography from a TeX file containing \cite{...} commands (or variants) with keys that respect a specific convention that allows the system to infer the cited record. More detailed instructions are available in the interactive tool.
To access it through the API, you need to make a POST request to the endpoint at https://inspirehep.net/api/bibliography-generator, with the following data:
- a
formatrequest argument whose value is eitherbibtex,latex_euorlatex_usdepending on the required bibliographic format - a form-encoded body with a single
filekey containing the form-encoded file as an argument.
The response will be a JSON object with a single data key whose value is an object containing the URL to the generated bibliography file under download_url and an array of encountered errors under errors (which is empty if there are no errors in the process).
For example with curl:
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
When using the popular Python requests package, this can be done as explained in its documentation.
Several tools in different languages are using this API. Their code might serve as a useful source of real-world examples.
- PHP:
- Python:
- Perl:
- Objective-C:
- JavaScript:
- TypeScript:
- Emacs Lisp:
If you would like your project to be listed, don't hesitate to let us know.
