What is the REF2014 Case Study API?
The REF2014 Case Study API provides programmatic access to the REF2014 case studies database.
The database provides access to documents submitted as part of the 2014 Research Excellence Framework,
making them searchable and providing filtering functionality based on tags applied to them. The API
exists to encourage analyses of the data and facilitate integration of the case study content and
associated metadata into new resources.
Who can use this API?
The API and associated documentation are designed for use by anyone with technical experience of
APIs and ingesting JSON or XML.
Getting started
The base URL for all API calls is:
http://impact.ref.ac.uk/casestudiesapi/REFAPI.svc/.
The API for the REF2014 case studies database provides methods to search and sort through case studies,
returning (as JSON or XML) details of all case studies matching specified search criteria. Methods for
exploring tag types and finding similar case studies are also provided.
Searching and filtering case studies
The primary method for searching through case studies is SearchCaseStudies. To return all the case studies
submitted to a specific Unit of Assessment (e.g. for UOA 01), the call should look like:
http://impact.ref.ac.uk/casestudiesapi/REFAPI.svc/SearchCaseStudies?UoA=1
All optional parameters of SearchCaseStudies, with the exception of {IDlist} and {format}, act in combination
(through logical AND) to filter case studies from the entire case study database.
SearchCaseStudies can take the parameters listed in this table:
| Method |
Parameter |
Values |
Description |
| SearchCaseStudies |
[format] |
[JSON],XML |
Specify output type. Defaults to JSON |
| |
[ID] |
{IDlist} |
List of one or more case study IDs, comma separated.
If {IDlist} is present then all other optional parameters
will be ignored
|
| |
[UKPRN] |
{UKPRN} |
Specify a specific institution with its {UKPRN} |
| |
[UoA] |
{UoA} |
Specify Unit of Assessment, {UoA} |
| |
[tags] |
{tagList} |
Comma separated list of tag IDs (see ListTagTypes). Multiple tags in {taglist} are
combined with logical AND, so only case studies containing all the tag IDs in {tagList}
will be returned
|
| |
[phrase] |
{phrase} |
Specify that {phrase} is present in the case study text, where {phrase} can be any
valid text expression conforming to Lucene search query syntax
|
For example, to list all case studies from UOA16 with tag id 18035
(for the Arts and Humanities Research Council):
http://impact.ref.ac.uk/casestudiesapi/REFAPI.svc/SearchCaseStudies?UoA=16&tags=18035
Available tag types for filtering
All case studies are submitted by at least one institution, into a Unit of Assessment (UOA).
All submitting institutions and available UOAs, as well as all other metadata tags assigned to
case studies, can be explored using the following:
| Method |
Parameter |
Values |
Description |
| ListInstitutions |
[format] |
[JSON],XML |
List of institution details, including UKPRN |
| ListUnitsOfAssessment |
[format] |
[JSON],XML |
List of UoAs, including ID and main panel |
| ListTagTypes |
[format] |
[JSON],XML |
List of tag types and type IDs |
| ListTagValues/{TagTypeID} |
[format] |
[JSON],XML |
Lists all tag IDs and names for specified TagTypeID |
For example to list all possible values for the tag with id =1 (impact type):
http://impact.ref.ac.uk/casestudiesapi/REFAPI.svc/ListTagValues/1
Exploring similar case studies
The similarity of case studies is estimated by text analysis of Section 2 (Underpinning research),
using Latent Semantic Analysis (LSA). This gives a compact representation of key semantic concepts
contained in documents as defined by the co-occurrence of words within documents. Similar documents
are defined as those that refer to the same semantic concepts. Pairs of documents are scored on
similarity from 0 to 1.0 (where 1.0 = identity).
To explore case studies similar to a specific document, the method SimilarCaseStudies is available:
| Method |
Parameter |
Values |
Description |
| SimilarCaseStudies/{CS_ID} |
[format] |
[JSON],XML |
Outputs all case studies similar to CS_ID |
| |
[sim] |
float in range 0.0 -1.0 [0.5] |
Specify minimum similarity value; this defaults to 0.5 |
For example, to output as XML all case studies similar to the case study with id=11807:
http://impact.ref.ac.uk/casestudiesapi/REFAPI.svc/SimilarCaseStudies/11807?format=XML&sim=0.7
Which data are accessible for each case study?
The API allows access to the full text and metadata associated with each case study.
For more detail about the structure of a case study, and for explanation of the categorisation and
classification that produces metadata tags, see FAQs. For each case study the following fields are
contained in the JSON/XML output:
| Field name |
Description |
| CaseStudyId |
A unique id for the case study |
| Continent |
The continents associated with the place-names tagged in the case study. GeoNames ids are included. |
| Country |
The countries associated with the place-names tagged in the case study. GeoNames ids are included. |
| Funders |
The project funders tagged in the case study text |
| ImpactDetails |
The cleaned text from the “details of the impact” section of the case study |
| ImpactSummary |
The cleaned text from the “summary of impact” section of the case study |
| ImpactType |
The summary impact type assigned to the case study |
| Institution |
The named Higher Education Institution on the original case study |
| Institutions |
The names and associated metadata of Higher Education Institutions that submitted this case study |
| Panel |
The main panel to which the case study was submitted |
| PlaceName |
Any geographical location identified in the case study text.
This is principally city/town names, but also includes geographical regions
such as UK counties or US states. It excludes countries. GeoNames ids are included.
|
| References |
The cleaned text from the “references” section of the case study |
| ResearchSubjectAreas |
The research subject areas tagged in the case study |
| Sources |
The cleaned text from the “sources to corroborate impact” section of the case study |
| Title |
The case study title |
| UKLocation |
Any place-name tagged in the case study that has as its parent one of the UK regions. GeoNames ids are included. |
| UKRegion |
The top level UK admin regions, i.e. England, Scotland,
Wales, Northern Ireland associated with place-names tagged in the case study.
GeoNames ids are included.
|
| UnderpinningResearch |
The cleaned text from the “underpinning research” section of the case study |
| UOA |
The Unit of Assessment to which the case study was submitted |
API Error Handling
As A REST service, the REF2014 API is not able to return a SOAP error object.
Use is therefore made of the standard HTTP error codes to convey error information,
supplemented by an error description that is contained in the response content returned
by the API in the event of an error condition being encountered. Note that the HTTP error
type and error detail messages are not visible if using a browser to access the API directly via a URL.
The error detail message is only accessible via code within the client application that invokes
the API method.
| API Method |
HTTP Code |
Error Type |
Error detail message |
| ListTagValues |
400 |
BadRequest |
Invalid TagTypeId supplied |
| SimilarCaseStudies |
404 |
NotFound |
No similar case studies found with specified similarity factor |
| SearchCaseStudies |
400 |
BadRequest |
Invalid case study ID(s) supplied |
| SearchCaseStudies |
404 |
NotFound |
No case studies found with specified search term |
| SearchCaseStudies |
404 |
NotFound |
No case studies found with specified tag values |
| SearchCaseStudies |
400 |
BadRequest |
Invalid UKPRN supplied |
| SearchCaseStudies |
400 |
BadRequest |
Invalid UOA ID supplied |
| SearchCaseStudies |
404 |
NotFound |
No case studies found with specified filters |