API for Developers
For Developers: API documentation (v1.0, 14 September 2018)
This API allows anyone to download the XML and PDF of specific articles as well as to download links to the XML of the entire corpus of articles. The content is indexed using Apache Solr
, which is open-source software that allows simple queries to be built in order to search and retrieve the content required.
Each article is assigned a unique DOI that can be resolved at doi.org
. An example of a DOI for a Gates Open Research article is https://doi.org/10.12688/gatesopenres.12838.2
. Solr queries will return the DOIs of articles that match the search. See below for details of how to build a Solr query, and the parameters and terms that you can use to refine your search.
Once you have the DOI of the articles you are interested in, the XML or PDF can be retrieved thus:
Request XML for a specific DOI:
Request PDF for a specific DOI:
To download links to the XML of the entire corpus, use: https://gatesopenresearch.org/published-xml-urls
Building a Solr query
You do not need to register on the site to get an API key, you can just build the Solr query as described and run it.
The base HTTP GET request is:
Each query will need the parameter ‘q’, followed by the query parameters and/or terms required.
Multiple fields can be searched using the Boolean operators AND, OR and ANDNOT.
Tables of valid query parameters and terms at the end of this page.
The response to the GET request can be delivered as an XML or a JSON file. By default, you will receive an XML file. To get a JSON file, use
Some example queries
To get all articles with “immunization” in the abstract:
To get all articles with “immunization” or “vaccine” in the abstract:
https://gatesopenresearch.org/extapi/search?q=R_ABS:"immunization" OR R_ABS:"vaccine"
To add in another variable, for example, you only want articles with “immunization” in the abstract and that have an author affiliated with a certain institution:
https://gatesopenresearch.org/extapi/search?q=R_ABS:"immunization" AND R_INS:"World Health Organization"
And here, we want articles with “vaccine” in the title that were published after a specific date:
https://gatesopenresearch.org/extapi/search?q=R_TI:"vaccine" AND R_PUD:[1528270617465 TO *]
If you want to get results containing more than one study type or more than one article type, you must use the operator OR not AND, for example:
https://gatesopenresearch.org/extapi/search?q=R_TY:"CASE_REPORT" OR R_TY:"RESEARCH_ARTICLE"
For a tutorial on the syntax of building regular Solr queries, go to SolrTutorial.com
Limitations on requests
Frequency of requests
Please note, user can only make 100 requests per 60 seconds; if the requests exceed this, an unauthorized status 401 will be returned.
Number of results per request
There is a limit of 100 results per request.
The file will include the total number of pages that the Solr query would return if there was no limit set so that you can then run further requests to get all the results.
For example, if a request returns >100 results (there is no need to put a page number to get the first page of results as that is the default of the parameter – see the Parameters and terms table below), then the file will have the following information at the top:
"totalNumberOfPages" : 2,
"numberOfResultsInPage" : 100
This indicates that you only need to run one more request with the page number filter set to 2 to get the rest of the results (append
&page=2 to the query).
Parameters and terms
|Query terms (see the table below)
Retrieve a specific page from the results (e.g. return page 3); default is page 1
|Number of results to include per page; default/maximum is 100
|Start point in page; default is 0
|Values: ‘xml’, ‘json’
Type of file retrieved; default is ‘xml’
The filters correspond to the filtering and advanced search options found on Gates Open Research’s browse pages
|What the filter will retrieve
|All (Can be any option in this table)
|Study type — see list of options below *
|Article type — see list of options below #
|Publication date of article (version 1) (in milliseconds) — see how to convert to time in ms below $
|Publication date of most recent version (in milliseconds) — see how to convert to time in ms below $
* Article types
# Study types