Search#

Search Procedures #

API Query String Search #

The simplest API interface for searching references is the query string search at /v1/references/search/. This endpoint requires authentication.

Parameters #

The only required parameter is the query string q. Additional optional parameters can be provided to filter, sort, and page through results.

Query String (required)#

The q parameter is a query string in the Lucene syntax.

At it’s simplest, this can be a simple keyword search, which will search over title and abstract:

# Get references with "climate change" anywhere in the title or abstract:
?q=climate change

# Get references with both "climate change" and "health" anywhere in the title or abstract:
?q=climate change AND health

Note

Query parameters must be URL-encoded. For example, spaces must be encoded as %20 or +. Most HTTP client libraries will do this automatically.

More complex queries can be constructed using the search syntax and the set of searchable fields.

# Get references with "climate", "climatology" etc in the title and either "John Doe" or "Jane Smith" as an author:
?q=title:"climat*" AND authors:("John Doe" OR "Jane Smith")

# Get references with "adaptation" or "mitigation" in the abstract that haven't yet been classified against the `Intervention` taxonomy:
?q=abstract:(adaptation OR mitigation) AND NOT evaluated_schemes:classification:taxonomy:Intervention

# Get references with "climate change" in any order and a typoed "health":
?q="change climate"~2 AND helth~

Start Year and End Year#

The minimum and maximum publication years (inclusive) for references to return.

# Get references published from 2015 onwards:
?q=...&start_year=2015

# Get references published up to and including 2020:
?q=...&end_year=2020

# Get references published from 2015 to 2020:
?q=...&start_year=2015&end_year=2020

Annotations#

The annotation parameter can be used to filter results based on their annotations.

These are provided in the format <scheme>[/<label>][@score].

If an annotation is provided without a score, results will be filtered for that annotation being true
If a score is specified, results will be filtered for that annotation having a score greater than or equal to the given value.
If the label is omitted, results will be filtered if any annotation with the given scheme is true.

Multiple annotations can be provided; they will be combined using a logical AND.

# Get references annotated with `classification:taxonomy:Outcomes/Stroke` as true:
?q=...&annotation=classification:taxonomy:Outcomes/Stroke

# Get references with an inclusion:destiny score of at least 0.8:
?q=...&annotation=inclusion:destiny@0.8

# Get references annotated with `classification:taxonomy:Outcomes/Stroke` as true and inclusion:destiny as true:
?q=...&annotation=classification:taxonomy:Outcomes/Stroke&annotation=inclusion:destiny

Page#

The page number of results to return. Each page is 20 results.

If omitted, defaults to the first page.

# Get the 41st to 60th results:
?q=...&page=3

Sort#

The field(s) to sort the results by. Use - prefix to sort in descending order.

If not provided, defaults to relevance as scored by the search engine.

Multiple sort fields can be provided; they will be applied in the order given.

# Sort by inclusion score ascending:
?q=...&sort=inclusion:destiny

# Sort by publication year descending:
?q=...&sort=-publication_year

# Sort by publication year ascending, then inclusion score descending:
?q=...&sort=publication_year&sort=-inclusion:destiny

Returns #

Returns a ReferenceSearchResult object.

Limitations #

There is a hard cap on the number of results at 10,000. You cannot page past this point, nor will total show more than this.

API Lookup #

Though not strictly a search, the lookup endpoint at /v1/references/ can be used to retrieve references by their identifiers. This endpoint requires authentication.

Parameters #

Identifiers (required)#

The identifier(s) to look up. Multiple identifiers can be provided, either in a comma-separated list or as multiple parameters.

Identifiers are in the format [[<other>:]<type>:]<identifier>:

If looking up a reference by its Destiny UUID4 id, no type prefix is needed: 09547790-7dfe-455e-a8df-5dca91963a5b.
If looking up a reference by a supported identifier type, the type must be prefixed: doi:10.1000/xyz123.
If looking up a reference by a custom identifier type, the type must be prefixed with other:: other:custom:internal-id-001.

Returns #

Returns a list of Reference objects in deduplicated form.

Limitations #

There is a hard cap of 100 identifiers per request. If more are needed, multiple requests must be made.

Search Fields #

Search Field Selection #

References may have multiple sources of information, so search fields are collapsed into a single set of searchable fields. The relevant data is prioritised by:

Fields provided on the canonical reference are prioritised over those on duplicate references.
Then, the most recently added data is prioritised.

Bibliographic #

ReferenceSearchFieldsMixin.title str[source]: The title of the reference.

ReferenceSearchFieldsMixin.authors list[str][source]

The authors of the reference.

These are ordered by:

First author
Middle authors in alphabetical order
Last author

ReferenceSearchFieldsMixin.publication_year int[source]: The publication year of the reference.

Abstract #

ReferenceSearchFieldsMixin.abstract str[source]: The abstract of the reference.

Annotations #

ReferenceSearchFieldsMixin.annotations list[str][source]

Every true annotation on the reference.

These are in format <scheme>[/<label>].

Examples:

classification:taxonomy:Outcomes/Stroke
classification:taxonomy:Intervention/Climate policy instruments
inclusion:destiny (No label)

ReferenceSearchFieldsMixin.evaluated_schemes list[str][source]

Every scheme that has been evaluated for this reference.

Combining this with annotations allows you to determine which annotations were evaluated as false.

Examples:

inclusion:destiny
classifier:taxonomy:Outcomes

ReferenceSearchFieldsMixin.inclusion_destiny float[0-1][source]

The destiny inclusion score for this reference.

This is used to apply custom thresholds for inclusion. If you just want to know if the reference was included per the default threshold, check for inclusion:destiny in annotations.