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:

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