Search API

You can use the search API to search through the four different resource entities. The resource entities you can search are as follows:

• Projects
• People
• Publications
• Organisations

Search API query parameters

term

The search API has a single mandatory query parameter call term where you specify the term or phrase you want to search the resources for. For example, to search for projects which include the term “boat” you would use the following URL:

https://gtr.ukri.org/api/search/project?term=boat

As the search term is included in the URL the values should be URL encoded. For example, to search for the term “Oxford University”, the term query parameter should be term=%22Oxford%20University%22. For more information about search terms and the search engine vocabulary see About searching.

fetchSize

The fetchSize parameter allows you to specify how many results to display for each request. The parameter allows for any integer value between 25 and 100, and defaults to 25 if not provided. See How pagination works for more information on using this parameter.

page

When more than one page of results are available you can use the page parameter to request other pages in the results. When not provided, the parameter will default to 1. See How pagination works for more information on using this parameter.

selectedSortableField

You can use this parameter to request which field the results should be sorted by. The response from the API will provide the list of fields available. If not provided, a suitable default field will be used.

selectedFacets

You can further filter the results by selected facets from the list of facets returned in the response. This parameter takes a base64 encoded comma delimited list of facet identifiers, which are used to filter the results.

fields

The fields parameter allows you to specify a comma delimited list of field identifiers for the fields which are searched for the term or phrase. The list of possible fields is returned in the response.

About searching

Searching in GtR is carried out by the Lucene based search service. Lucene enables complex searches known as queries. We've provided a basic introduction to performing searches using Lucene queries below. More information about Lucene is available at Apache Lucene or Welcome to Apache Lucene.

Lucene searches are not case sensitive.

Term

A term is a single word, for example test. The term test will match Test, TEST or TesT.

Phrase

A phrase is a set of terms, for example blood test. Phrases are also not case sensitive, and a match will occur if one or more words in the phrase are found. Therefore test, Test, Blood and blood will match the phrase blood test.

Quoted phrase

A phrase enclosed in double quotes, for example "blood test". Quoted phrases are only matched if the full quoted phrase appears, therefore "blood test" will only match if words blood and test appear together in the specified order.

Wildcards

The ? character can be used to match any single character and the * character can be used to match any number of any character. For example t?nt will match tent, tint and TNT, and t*nt will match tent, tint, TNT, taint, taunt etc. Searches cannot begin with the wildcard characters, but the * character can be used on its own to return all results.

Proximity search

Using the ~ character, you can specify how close together words in a quoted phrase are located to each other. For example, searching for “blood test”~10 would look for the words blood and test where they are within 10 words of each other.

Boolean operators

The following boolean operators are available (boolean operators should be in upper case):

• AND - finds results with both terms exist. For example, test AND "blood sugar", will return results where both the term test and the phrase blood sugar exists.
• OR - finds the results where one or both terms exist. For eaxmple, test OR research, will return results where either the term test or the term research exist.
• NOT - excludes results which match a term. For example, blood AND NOT test, will return results where the term blood exist and where the term test does not exist.
• + - return results which include the term. For example, +blood test, will return results which include blood and may include test.
• - - excludes results which include the term. For example, -blood test will return results which include test but does not include blood.

Grouping

Parentheses can be used to group boolean searches together. For example, (blood OR sugar OR insulin) AND test, will return results with the term test in them and one of the terms blood, sugar or insulin.

Escape character

To use the characters + - & | ! ( ) { } [ ] ^ “ ~ * ? : \ in a search term or phrase you need to precede the character with a \, for example to search for (A + B):C you will need to use the search term \(A + B\)\:C.