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

Concepts

The concept parameter filters results by their linked-data concept URIs (matched against the linked_data_concepts field).

• Each concept value is a fully-qualified concept URI, or a comma-separated list of URIs.

• Within a single concept value, URIs are combined using a logical OR - a reference matches if it carries any one of them.

• Multiple concept parameters are combined using a logical AND - a reference must match each one.

# Get references annotated with the C00001 concept:
?q=...&concept=https://vocab.evidence-repository.org/scheme/C00001

# Get references annotated with either the C00001 or C00002 concept:
?q=...&concept=https://vocab.evidence-repository.org/scheme/C00001,https://vocab.evidence-repository.org/scheme/C00002

# Get references annotated with (C00001 OR C00002) AND a third concept:
?q=...&concept=https://vocab.evidence-repository.org/scheme/C00001,https://vocab.evidence-repository.org/scheme/C00002&concept=https://vocab.evidence-repository.org/scheme/C00003

Countries

The country parameter filters results by ISO 3166-1 alpha-2 country codes.

• Each country value is a single code, or a comma-separated list of codes.

• Within a single value, codes are combined using OR; multiple country parameters AND.

• Codes are validated for shape only (two letters) and uppercased on input — e.g. us and US both pass through. Codes that don’t match the [A-Z]{2} shape return 400.

# Get references tagged with the United States:
?q=...&country=US

# Get references tagged with the United States, the UK, or France:
?q=...&country=US,GB,FR

# Get references tagged with (US OR GB) AND (FR OR DE):
?q=...&country=US,GB&country=FR,DE

World Bank Regions

The country_wb_region parameter filters results by World Bank region IDs.

• Each value is a single region ID, or a comma-separated list of IDs.

• Within a single value, IDs are combined using OR; multiple parameters AND.

• IDs come from a closed set: EAS, ECS, LCN, MEA, NAC, SAS, SSF. Unknown IDs return 400.

# Get references tagged with North American countries:
?q=...&country_wb_region=NAC

# Get references tagged with North America or East Asia & Pacific:
?q=...&country_wb_region=NAC,EAS

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.

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

If sort is omitted, results default to relevance in descending order.

Sort by mapped fields

Mapped fields (such as publication_year or inclusion_destiny) sort in ascending order. Prefix a field with - to sort it in descending order instead.

Sorting by relevance

The special relevance key sorts by the search engine’s relevance score rather than a mapped field. Unlike mapped fields, relevance defaults to descending order to provide best matches first. To reverse this and return the least relevant results first, prefix it as -relevance.

Any of the searchable fields may be sorted on, except free-text fields (title, abstract, authors and linked_data_labels), which cannot be used as sort keys.

# Sort by relevance, same as no sort parameter:
?q=...&sort=relevance

# 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

# Sort by relevance first, then break ties by newest publication year:
?q=...&sort=relevance&sort=-publication_year

Returns

Returns a ReferenceSearchResult object.

Limitations

Pagination is limited to the first page.max_result_window results, currently 10,000. The total counts all matching references exactly, including matches beyond that limit. To find how many pages can be reached, clamp the total to the window and divide by the page size.

API Facet Counts

The facets endpoint at /v1/references/search/facets/ returns per-facet term counts across the references matching the search.

Accepts the same filter parameters as /v1/references/search/ plus one or more facet values. Only the requested facet types appear in the response.

# Count concepts across all references matching a query:
?q=climate&facet=concepts

When you filter on a field and request that field’s facet, the bucket counts show what you’d see if your selection were toggled - not the co-occurrence under your filter. The behaviour is OR within a sibling family and AND with everything else.

There are two flavours, distinguished by how siblings are defined:

Concepts. A concept’s siblings are every member of its scheme in the SKOS vocabulary, so concept= must be supplied alongside vocabulary= when requesting facet=concepts. Each concept= parameter is one scheme’s selection.

For example, concept=Botany,Zoology AND concept=Africa with facet=concepts:

• The Botany/Zoology group’s counts show every concept in the Topics scheme (Biology, Chemistry, Botany, Zoology, Microbiology, …) as if you swapped the selection, with the Africa filter still applied.

• The Africa group’s counts show every concept in the Region scheme (Africa, Asia, Europe, …), with the (Botany OR Zoology) filter still applied.

• An “unselected” bucket surfaces any other concepts present on the matching references.

# (Botany OR Zoology) AND Africa, with sibling-aware concept counts.
?q=*&concept=https://vocab.evidence-repository.org/Botany,https://vocab.evidence-repository.org/Zoology
    &concept=https://vocab.evidence-repository.org/Africa
    &facet=concepts
    &vocabulary=https://vocab.evidence-repository.org/vocabulary/v1

Restrictions (400 on violation):

1. URIs inside one concept= must belong to the same scheme.

2. Different concept= filters must be in different schemes.

3. Every URI must resolve in the supplied vocabulary.

Countries and WB regions. There’s no vocabulary hierarchy here - the entire field is treated as one sibling family.

?q=*&country=KE&facet=countries

Restrictions (400 on violation):

1. Only a single OR’d filter is supported when requesting the facet counts.

Returns

Returns a ReferenceFacetResult object. Each bucket’s count is “references matching if you toggled this value’s selection state and left everything else alone.”

Limitations

Each facet returns at most ES_AGGREGATION_MAX_BUCKETS buckets (default 1000). For concept facets, if a sibling group’s vocabulary set exceeds this the request is refused rather than silently truncated.

API Cross-Facet Counts

The cross-facets endpoint at /v1/references/search/cross-facets/ cross-tabulates two axes over the references matching the search, for evidence maps. It accepts the same filter parameters as /v1/references/search/ plus two axes.

Each axis is one of:

• a concept-scheme URI

• the literal countries

• the literal country_wb_regions

Mixed types are allowed. When an axis is a concept-scheme URI, supply vocabulary= — its concepts scope that axis (via the SKOS membership of the scheme, at every depth). Cell values are reported in the same order the axes are given.

# WHO region x thematic focus, across malaria references since 2015:
?q=malaria
    &axes=https://vocab.evidence-repository.org/scheme/WHORegion
    &axes=https://vocab.evidence-repository.org/scheme/Themes
    &vocabulary=https://vocab.evidence-repository.org/vocabulary/v1
    &start_year=2015

Counting is simpler than the facets endpoint: each returned cell is a strict intersection - references matching both its axis values, all panel filters and the query string. Only non-zero cells are returned.

Returns

Returns a ReferenceCrossFacetResult: two exact totals plus the non-zero {axes, count} cells (axes is a 2-tuple in the requested order), sorted by descending count. totals.search counts every reference matching the search; totals.mapped counts the subset with a value on both axes. Cells may sum to more than totals.mapped because a reference can carry multiple values on an axis, but never to less.

Restrictions (400 on violation):

1. A concept-scheme axis requires vocabulary= (whose host must be a subdomain of the configured vocabulary host), and the scheme must resolve to at least one concept in it.

2. A matrix whose bucket count would exceed ES_CROSS_FACET_MAX_CELLS (default 50,000) is refused rather than aborting server-side.

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 UUID 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

The title of the reference.

ReferenceSearchFieldsMixin.authors list[str]

The authors of the reference.

These are ordered by:

• First author

• Middle authors in alphabetical order

• Last author

ReferenceSearchFieldsMixin.publication_year int

The publication year of the reference.

Abstract

ReferenceSearchFieldsMixin.abstract str

The abstract of the reference.

Annotations

ReferenceSearchFieldsMixin.annotations list[str]

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]

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]

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.

Linked Data

ReferenceSearchFieldsMixin.linked_data_concepts list[str]

Full concept URIs from LinkedDataEnhancements.

ReferenceSearchFieldsMixin.linked_data_labels list[str]

SKOS prefLabel values for linked data concepts, for text search.

ReferenceSearchFieldsMixin.linked_data_evaluated_properties list[str]

Property URIs for all evaluated linked data dimensions.

ReferenceSearchFieldsMixin.linked_data_countries list[str]

ISO country codes from LinkedDataEnhancements, for exact-match filtering.

ReferenceSearchFieldsMixin.linked_data_country_wb_regions list[str]

World Bank regions derived from linked_data_countries.