Gateway to Research API 2

GTR-2 API accesses the data in a form that is independent from the current Gateway to Research (GtR) user interface. It can provide responses in JSON and XML data formats.

The API provides access to all the data available in the GtR user interface, which is available under the Open Government License. We expect users of the API to follow web etiquette and not to flood the service with requests and make it inoperable for other users. We would like users of the API to respect this freedom in a similar way that search engines respect the sites they index and moderate the requests they make in any particular time window.

Response versioning

When making a request to the GTR-2 API, you can specify the version data format that responses return by using the Accept header. If you do not specify a specific version and use the standard application/json or application/xml header, the API will default to the oldest supported version. If no Accept header is provided then the API will default to the oldest supported version of application/xml.

To request a specific version use the Accept header application/vnd.rcuk.gtr.json-v[n] for JSON formatted responses, and application/vnd.rcuk.gtr.xml-v[n] for XML formatted responses (where n is the version number of the response you required). The current version of the response is version 7 and versions 1 to 6 are still available.

XML namespaces

The following is a list of the XML schemas defined for the API.

Additions to the schema will result in a new version being issued. The version of the schema in use correlates directly with the version specified in the HTTP Accept header. Each schema document is available to download by making requests to the namespace URL. The Accept header can be used to request the schema for a specific response version.

How to use the API

For those of you who know how to use APIs you can dive right in and look at the GtR API examples, where you will find a listing of each of the available endpoints, with example usage. All requests use the HTTP GET method.

The available endpoints are as follows:

• Configuration and example endpoints
• Fund endpoints
• Organisation endpoints
• Outcome endpoints
• Person endpoints
• Project endpoints

How pagination works for lists of resources

If the results of an endpoint are paged, the response will include attributes that will provide you with information about the number of pages and the total number of results.

Below is an example of the pagination attributes returned by the projects endpoint, first in JSON and then in XML.

{
    "links": null,
    "ext": null,
    "page": 1,
    "size": 20,
    "totalPages": 7911,
    "totalSize": 158206,
    "project": [ .. ]                            
}

<?xml version="1.0" encoding="UTF-8"?>
<ns2:projects ns1:page="1"
                 ns1:size="20"
                 ns1:totalPages="7911"
                 ns1:totalSize="158206"
                 xmlns:ns1="http://gtr.rcuk.ac.uk/gtr/api"
                 xmlns:ns2="http://gtr.rcuk.ac.uk/gtr/api/project"
                 xmlns:ns3="http://gtr.rcuk.ac.uk/gtr/api/fund"
                 xmlns:ns4="http://gtr.rcuk.ac.uk/gtr/api/person"
                 xmlns:ns5="http://gtr.rcuk.ac.uk/gtr/api/project/outcome"
                 xmlns:ns6="http://gtr.rcuk.ac.uk/gtr/api/organisation">
    <ns2:project ns1:created="2024-07-07T22:28:13Z"
                    ns1:href="http://gtruat.ukri.org/gtr/api/projects/07D6E9EA-F096-44BF-BAF6-01F2D3DE4489"
                    ns1:id="07D6E9EA-F096-44BF-BAF6-01F2D3DE4489">
    ..
    </ns2:project>
</ns2:projects>

This will enable you to page through the endpoint results by increasing the required page number, using p (page) parameter. Exceeding the number of pages available will result in a HTTP response code of 404 (not found).

Page size will default to 20, but can be specified by using the s (size) parameter with a value from 10 to 100.

Linked relations

Most resources will contain link attributes which provide links to related resources. Below is an example of the links provided with a project.

"links": {
    "link": [
        {
            "href": "http://gtruat.ukri.org/gtr/api/persons/73094AD1-691D-4975-B4A7-E61D767A751B",
            "rel": "SUPER_PER",
            "start": null,
            "end": null,
            "otherAttributes": {}
        },
        {
            "href": "http://gtruat.ukri.org/gtr/api/persons/79907242-86A5-4B4E-9463-7E9BDE8E0E99",
            "rel": "STUDENT_PER",
            "start": null,
            "end": null,
            "otherAttributes": {}
        }
    ]
}

<ns1:links>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/persons/73094AD1-691D-4975-B4A7-E61D767A751B" ns1:rel="SUPER_PER"/>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/persons/79907242-86A5-4B4E-9463-7E9BDE8E0E99" ns1:rel="STUDENT_PER"/>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/organisations/E7BE255A-5E4B-4E40-9A39-F1458486B92F" ns1:rel="LEAD_ORG"/>
    <ns1:link ns1:end="2025-09-29T23:00:00Z" ns1:href="http://gtruat.ukri.org/gtr/api/funds/15B6A748-0126-4234-8C5E-D534FF482161" ns1:rel="FUND" ns1:start="2017-09-30T23:00:00Z"/>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/outcomes/keyfindings/594BBC81-8111-4ACD-9EC4-E6325965658A" ns1:rel="KEY_FINDING"/>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/outcomes/publications/C9047BFA-7EEC-4446-A2AF-FAEF5F9A5CED" ns1:rel="PUBLICATION"/>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/outcomes/publications/A4BB4CEB-2322-4743-AFBE-205039A19080" ns1:rel="PUBLICATION"/>
    <ns1:link ns1:href="http://gtruat.ukri.org/gtr/api/outcomes/publications/5D4883AF-0D7D-4309-B0C7-7DD8AC113E1F" ns1:rel="PUBLICATION"/>
    <ns1:link ns1:end="2024-09-29T23:00:00Z" ns1:href="http://gtruat.ukri.org/gtr/api/projects/5C9C7F94-C032-4DEE-BA1B-C630E823616A" ns1:rel="STUDENTSHIP_FROM" ns1:start="2017-09-30T23:00:00Z"/>
</ns1:links>

The following table defines the possible relationships.