GTRAPI documentation

Introduction

The GTRAPI is the same API that is used by the GtR web portal. There is a direct correlation between the visible information on the web portal pages and the output from the API.

The GTRAPI contains the following APIs:

The GTAPI will produce output in both XML and JSON formats. The format required can be requested by adding a HTTP accept header for the output required, application/xml for XML and application/json for JSON.

The GtRAPI provides access to all the data available in the GtR portal, which is available under the Open Government License. We expect users of this 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.

Changes to GTRAPI in June 2024

To resolve an issue with the GTRAPI not working the endpoint URLs for all the GTRAPI endpoints had been updated to include api in the URL. See the release history for more detals.

How pagination works

All the endpoints which return lists of resources will return them in pages of 25 items. You can specify other pages in the results by using the page parameter. You can also specify a different page size using the fetchSize parameter (page sizes must be between 25 and 100). For example, the following will return the second page with 100 items on each page: 

https://gtr.ukri.org/search/project?term=boat&page=2&fetchSize=100

Pagination information is returned by the three HTTP response headers: Link-Records, Link-Pages and Link.

Link-Records response header

The Link-Records response header gives the total number of items the request would return.

Link-Pages response header

The Link-Pages response header gives the total number of pages available to scroll through.

Link response header

The link response header is a standard HTTP response header which is defined in RFC 5988. It will contain a semi-colon delimited list of links for related pages with the following structure:

rel=<relationship>, <URL>

where <relationship> will be one of

  • next - <URL> will be the next page of results
  • previous - <URL> will be the previous page of results
  • first - <URL> will be the first page of results
  • last - <URL> will be the last page of results

Failure scenarios

The GTRAPI may return one of these four HTTP status codes:

  • 200 (success) - the request has been processed successfully
  • 400 (bad request) - the client provided invalid data or parameters to the request
  • 404 (not found) - the requested resource does not exist, or no matches have been found for a search
  • 500 (internal server error) - an unexpected error has occurred when processing the request

Other HTTP status codes may be returned but are not specifically used by the GTR application.