Research Documents API Documentation

The Research Documents API is a clone of the IDS API.

This API is designed to be accessible to applications written for the IDS API. With minimal modifications they will be able to access the large collection of documents and meta data resources which we store.

Research Documents API

Accessing the API

The API has been designed to allow applications written for the IDS API to be simply modified to talk to a large collection of documents and resources drawn from across the datasets including in Linked Development. The API supports both JSON and XML response types across all of our endpoints.

API Versioning

Our API is versioned to allow consumers time to migrate between major API versions. Major versions of the API are indicated by subdomains like v1 or v2. Where the integer component indicates the major API version.

The latest api version can currently be found at v2.api.linked-development.org.

If you always want to use the latest API then requests to api.linked-development.org will always be 302 redirected to the latest API version, whilst requests to a specific API version will never be redirected, allowing you to lock yourself to a known version.

Old versions of the API may however be deprecated and switched off at our discretion.

API URL Patterns

We follow the IDS API's URL pattern for modelling our request methods, typically this means that API methods follow the following structure:

/openapi/{graph}/{function}/{object}/{identifier_or_type}/[detail][format]?{option_parameters}
Parameter Acceptable Values Description
graph all, eldis, r4d The graph parameter indicates the scope of your query. There are two main graphs, r4d and eldis and a union all graph for queries that wish to search across both platforms. The graphs are equivalent to the two primary datasets we hold in our Linked Data store.
function get, get_all, search, count The function represents the type of query you are performing. For example a get will typically return one result by its id, whilst a get_all or a search will tend to return many results in a paginated form. Calls to count will return the number of distinct objects that are found to match your query.
object themes, documents, regions, countries, research_outputs The function represents the type of query you are performing. For example a get will typically return one result by its id, whilst a get_all or a search will tend to return many results in a paginated form.
identifier_or_type N/A Typically this parameter is used to refer to a specific object by an identifier for example during a get request. Sometimes its use is overloaded depending on the function, for example count queries use it to specify the object types you are counting.
detail short, full This is an optional parameter that is supported on all routes. It allows the requestor to specify how much detail comes back with each request. If this parameter is not supplied it will default to short. Choosing a full level of detail will return a more complicated document back consisting of much more information than in the short view.
format .json, .xml Requests against the API must specify a format. This can be done either by providing the appropriate mime-type as an Accept header on the HTTP request, or by appending either .json or .xml to the requests URL string.
option_parameters num_results, start_offset ... Query string parameters can be provided with some requests to further refine them, however all requests returning many results support pagination via the parameters num_results and start_offset. For details on specific parameters please refer to the documentation for each object/function.

NOTE: Not all possible combinations of parameters are supported.

Multiple Results Metadata

All of the routes within the API that return multiple results, such as get_all, search and count return a metadata object which can be used to assist in paginating the results.

This can be found under a "metadata" key at the top level of the response document. The metadata object in turn can contain up to four keys:

Key Value Type Always Present Description
num_results Integer Y This value states the total number of results that have been matched. Responses typically only contain a paginated subset of all the results.
start_offset Integer Y This value states the currently requested offset. The offset represents the point at which the current pagination window starts amongst the total ordering of results.
next_page URL N Following this link will retrieve the next page of results. Users should test for the presence of the next_page key before accessing the value. If the key is not present the current page represents the final page of results.
prev_page URL N Following this link will retrieve the previous page of results. Users should test for the presence of the prev_page key before accessing the value. If the key is not present the current page represents the first page of results.

Supported Requests

Documents

get_all/documents

Supported on eldis, r4d and all graphs.

Example: Requesting the first page of all eldis documents at a full level of detail in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get_all/documents/full.json"

Example: Requesting the first page of all r4d documents at a full level of detail in XML format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/get_all/documents.xml"

Example: Requesting the first page of all documents at a full level of detail in JSON format:

$ curl -H "Accept: application/json" "http://v2.api.linked-development.org/openapi/eldis/get_all/documents/full?num_results=20&start_offset=20"

get/documents

Supported on eldis, r4d and all graphs.

Example: Requesting an eldis document by its id (A64559) in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get/documents/A64559/full.json"

Example: Requesting an r4d document by its id (185225) in XML format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/get/documents/185225/full.xml"

Example: Requesting an r4d document by its id (185225) from the all graph in XML format at a short level of detail:

$ curl "http://v2.api.linked-development.org/openapi/all/get/documents/185225/short.xml"

Counting Documents

Counts are always of documents but by another object criteria, and are therefore not supported on the document routes directly. Please consult the other object types for how to count documents.

Searching for Documents

Supported on eldis, r4d and all graphs.

Searches for documents which are part of themes that match the supplied criteria. Criteria can be combined through conjunction (boolean AND) to narrow results further.

Query Parameter Supported Value Types Supported Graphs Description
q Text String eldis, r4d, all This parameter does a free text query across document titles and abstracts.
country ISO2 Country Code, ELDIS Country ID eldis, r4d, all This parameter narrows results to documents covering the specified country. ELDIS country ID's can only be used on the eldis and all graphs. Whilst ISO2 country codes are supported on all graphs.
region UN Code, ELDIS region ID eldis, r4d, all This parameter narrows results to documents covering the specified region. ELDIS region ID's can only be used on the eldis and all graphs. Whilst UN codes are supported on all graphs.
theme Theme name, AGROVOC ID, ELDIS theme ID eldis, r4d, all This parameter narrows results to documents that are associated with the set of themes matching this query parameter. Returned results are the union of matches across AGROVOC ID's, ELDIS ID's and theme names.
iati-identifier IATI identifier r4d, all This parameter narrows results to R4D documents that are associated with the corresponding programme. It is only supported on the r4d and all graphs.

Example: Searching R4D documents where their titles or abstracts include the word "water" and returning a JSON response:

$ curl "http://v2.api.linked-development.org/openapi/r4d/search/documents/full.json?q=water"

Example: Requesting all documents from all graphs where their title or abstract includes the word "water" that cover Great Britain. This demonstrates how criteria can be combined:

$ curl "http://v2.api.linked-development.org/openapi/all/search/documents/full.xml?q=water&country=GB"

Example: Requesting all documents from all graphs that cover Europe (Eldis ID C24):

$ curl "http://v2.api.linked-development.org/openapi/all/search/documents/full.json?region=C24"

Example: Requesting all R4D documents in JSON (20 at a time) that refer to the DFID Programme for Enhancement of Research Information (Identified by IATI ID: GB-1-112059)

$ curl "http://v2.api.linked-development.org/openapi/r4d/search/documents/full.json?iati-identifier=GB-1-112059&num_results=20"

Themes

get_all/themes

Supported on eldis, r4d and all graphs.

Example: Requesting the first page of all eldis themes at a full level of detail in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get_all/themes/full.json"

Example: Requesting the first page of all eldis themes at a full level of detail in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/get_all/themes.xml"

Example: Requesting the first page of all themes at a full level of detail in JSON format:

$ curl -H "Accept: application/json" "http://v2.api.linked-development.org/openapi/eldis/get_all/themes/full?num_results=20&start_offset=20"

get/themes

Supported on eldis, r4d and all graphs.

Example: Requesting an eldis theme by its id (C782) in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get/themes/C782/full.json"

Example: Requesting an r4d theme by its id (knowledge_sharing) in XML format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/get/themes/knowledge_sharing/full.xml"

Example: Requesting an r4d theme by its id (knowledge_sharing) from the all graph in XML format at a short level of detail:

$ curl "http://v2.api.linked-development.org/openapi/all/get/themes/knowledge_sharing/short.xml"

count/themes

Supported on eldis, r4d and all graphs.

Returns the counts of the number of documents associated with each them

Example: Requesting counts of documents associated with all eldis themes in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/count/documents/theme.json"

Example: Requesting counts of documents associated with all r4d themes in XML format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/count/documents/theme.xml"

Example: Requesting counts of documents associated with all themes in JSON format, paginated into pages of 2 results at a time starting at offset 10.

$ curl -H "Accept: application/json" "http://v2.api.linked-development.org/openapi/all/count/documents/theme?num_results=2&start_offset=10"

Countries

get_all/countries

Supported on eldis, r4d and all graphs.

Returns all the countries from the specified graph. NOTE that no attempt is made to reconcile country records across datasets/graphs, this means that the same country can be represented by a different record in r4d/eldis.

Example: Requesting all countries at full detail 10 at a time from all graphs in JSON:

$ curl "http://v2.api.linked-development.org/openapi/all/get_all/countries/full.json"

Example: Requesting all countries from eldis, at short detail, 20 at a time in JSON:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get_all/countries/short.json"

get/countries

Supported on eldis, r4d and all graphs.

Request data on a single country from the specified graph.

Example: Requesting "Nauru" by its ELDIS country ID (A1151) at full detail in JSON:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get/countries/A1151.json"

Example: Requesting "Nauru" by its ELDIS country ID (A1151) at full detail in JSON:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get/countries/A1151.json"

count/countries

Supported on eldis, r4d and all graphs.

Returns the counts of the number of documents associated with each theme.

Example: Requesting counts of documents associated with all eldis themes in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/count/documents/country.json"

Example: Requesting counts of documents associated with all r4d themes in XML format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/count/documents/country.xml"

Example: Requesting counts of documents associated with all countries in JSON format, paginated into pages of 2 results at a time starting at offset 10.

$ curl -H "Accept: application/json" "http://v2.api.linked-development.org/openapi/all/count/documents/country?num_results=2&start_offset=10"

Regions

get_all/regions

Supported on eldis, r4d and all graphs.

Returns all the regions from the specified graph. NOTE that no attempt is made to reconcile country records across datasets/graphs, this means that the same region can be represented by a different record in r4d/eldis.

Example: Requesting all regions at full detail 10 at a time from all graphs in JSON:

$ curl "http://v2.api.linked-development.org/openapi/all/get_all/regions/full.json"

Example: Requesting all regions from eldis, at short detail, 20 at a time in JSON:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get_all/regions/short.json"

get/regions

Supported on eldis, r4d and all graphs.

Request data on a single region from the specified graph.

Example: Requesting "Nauru" by its ELDIS region ID (A1151) at full detail in JSON:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get/regions/A1151.json"

Example: Requesting "Nauru" by its ELDIS region ID (A1151) at full detail in JSON:

$ curl "http://v2.api.linked-development.org/openapi/eldis/get/regions/A1151.json"

count/regions

Supported on eldis, r4d and all graphs.

Returns the counts of the number of documents associated with each theme.

Example: Requesting counts of documents associated with all eldis themes in JSON format:

$ curl "http://v2.api.linked-development.org/openapi/eldis/count/documents/region.json"

Example: Requesting counts of documents associated with all r4d themes in XML format:

$ curl "http://v2.api.linked-development.org/openapi/r4d/count/documents/region.xml"

Example: Requesting counts of documents associated with all regions in JSON format, paginated into pages of 2 results at a time starting at offset 10.

$ curl -H "Accept: application/json" "http://v2.api.linked-development.org/openapi/all/count/documents/region?num_results=2&start_offset=10"

Research Outputs

As R4D data splits the research outputs linked to a given IATI identifier into sub-projects, an additional call has been added called 'research_outputs' which shows a list of research outputs for an IATI ID, grouped by their associated project.

count and search are not implemented for this object type.

get_all/research_outputs

Query Parameter Supported Value Types Description
per_project Integer Specifies the maximum number of research_outputs to return for each research_project. Defaults to 5.

Supported on the r4d and all graphs only.

Example: Getting all research_projects with a maximum of 10 research_outputs per project, paginated into pages of 20 research_projects at a time.

$ curl "http://v2.api.linked-development.org/openapi/r4d/get_all/research_outputs.json?per_project=10&num_results=20"

get/research_outputs

Allows searching of research_projects by IATI identifier. Unlike other get calls this can return multiple results. Consequently this means that the content of the response will contain a metadata section as with get_all and search requests.

Query Parameter Supported Value Types Description
per_project Integer Specifies the maximum number of research_outputs to return for each research_project. Defaults to 5.

Supported on the r4d and all graphs only.

Example: Getting research_projects associated with DFID "Professional Evidence and Applied Knowledge Services" funding stream, with a maximum of 10 research_outputs per project, paginated into pages of 20 research_projects at a time.

$ curl "http://v2.api.linked-development.org/openapi/r4d/get/research_outputs/GB-1-114192.json?per_project=10&num_results=20"

Errors

HTTP Error Codes

Error type HTTP status code Notes
Response too large 400 We will include a text message in the response body including the phrase "Response too large."
SPARQL Syntax Error 400 We will include a text message in the response body with details of the error.
Resource Not Found 404 Returned if you request a resource or URL that doesn't exist
Not Acceptable 406 Returned if you request a non-supported data format
Unexpected Errors 500
Query Timeouts 503 The timeout for requesting data from our database will initially be set to 10 seconds.

Response Messages

In addition to a HTTP response code, in the case of an error the response will contain a document containing a description of the error encountered.

For example if a JSON object is requested a JSON object will be returned who's error key will contain a description of the error.

{error: "Graph test is not supported for this object type. Valid graphs are: all, eldis, r4d."}