Name Resolver API

The Name Resolver API is intended to provide an Apache Solr-based interface to the Babel cliques of equivalent identifiers. Apache Solr is a document-based search engine: the documents in this case are descriptions of cliques as generated by the Babel pipeline in its Synonyms format, including lists of all known synonyms. Here is an example document for NCBIGene:1756 (compared with the same CURIE on NodeNorm):

{
    "curie": "NCBIGene:1756",
    "preferred_name": "DMD",
    "names": [
      "BMD",
      "DMD",
      "MRX85",
      "CMD3B",
      "DXS164",
      "DXS270",
      "DXS142",
      "DXS268",
      "DXS206",
      "DXS272",
      "DXS269",
      "DXS239",
      "DXS230",
      "DMD Gene",
      "DMD gene",
      "DYSTROPHIN",
      "dystrophin",
      "APO-DYSTROPHIN 1",
      "mutant dystrophin",
      "mental retardation, X-linked 85",
      "muscular dystrophy, Duchenne and Becker types",
      "Dystrophin (Muscular Dystrophy, Duchenne And Becker Types) Gene",
      "dystrophin (muscular dystrophy, Duchenne and Becker types), includes DXS142, DXS164, DXS206, DXS230, DXS239, DXS268, DXS269, DXS270, DXS272",
      "A0A087WV90_HUMAN Dystrophin (trembl)",
      "A0A0S2Z3B5_HUMAN Dystrophin isoform 2 (trembl)",
      "A0A0S2Z3J7_HUMAN Dystrophin isoform 1 (Fragment) (trembl)",
      "A0A5H1ZRP9_HUMAN Dystrophin (trembl)",
      "A0A5H1ZRQ1_HUMAN Dystrophin (trembl)",
      "A0A5H1ZRQ8_HUMAN Dystrophin (trembl)",
      "A0A5H1ZRR9_HUMAN Dystrophin (trembl)",
      "A0A804HKY9_HUMAN Dystrophin (trembl)",
      "A7E212_HUMAN Dystrophin (trembl)",
      "hDMD",
      "Dystrophin",
      "DMD protein, human",
      "dystrophin (human)",
      "Dp116 protein, human",
      "DMD_HUMAN Dystrophin (sprot)",
      "dystrophin (muscular dystrophy, Duchenne and Becker types) protein, human",
      "Q16484_HUMAN DMD protein (Fragment) (trembl)",
      "Q4G0X0_HUMAN DMD protein (trembl)"
    ],
    "types": [
      "Gene",
      "GeneOrGeneProduct",
      "GenomicEntity",
      "ChemicalEntityOrGeneOrGeneProduct",
      "PhysicalEssence",
      "OntologyClass",
      "BiologicalEntity",
      "ThingWithTaxon",
      "NamedThing",
      "Entity",
      "PhysicalEssenceOrOccurrent",
      "MacromolecularMachineMixin",
      "Protein",
      "GeneProductMixin",
      "Polypeptide",
      "ChemicalEntityOrProteinOrPolypeptide"
    ],
    "shortest_name_length": 3,
    "clique_identifier_count": 22,
    "taxa": [
      "NCBITaxon:9606"
    ],
    "curie_suffix": 1756,
    "id": "fd3cbf13-1aa7-4538-9df4-11cb80493295",
    "_version_": 1842436833304117200
  }

The Name Resolver largely consists of two search endpoints: /lookup (to search for normalized concepts), /bulk-lookup (to search for multiple normalized concepts), and one lookup endpoint: /synonyms (to look up for the synonyms for a normalized CURIE).

Conflation

Unlike the Node Normalizer, the Name Resolution Service does not currently support on-the-fly conflation. Instead, all the Babel conflations are turned on when Solr database is built. At the moment, this includes:

GeneProtein conflation: protein-encoding genes are conflated with the protein(s) they encode, and the gene identifier is used to identify this concept. Therefore, if you search for ""
DrugChemical conflation: drugs are conflated with their active ingredient, and the identifier for the active ingredient is used to identify this concept. This means that -- for example -- protein-encoding genes will include the synonyms found for the protein they encode, and that no separate entry will be available for those proteins.

Once you have an identifier from Name Resolver, you can use the Node Normalizer to look up the equivalent identifiers for that CURIE with and without conflation. Please use the Node Normalizer corresponding to the instance of Name Resolver you are using.

We are currently working on supporting on-the-fly conflation in Name Resolver.

Search endpoints

The search endpoints allow you to search for concepts by a fragment of a name or synonym. By default these endpoints use Solr's extended Dismax query parser to search for matches across preferred names and synonyms, with support for highlighting, filtering, pagination, and debugging. Setting the exact parameter switches them to whole-string exact matching instead (see Exact matching).

The default search is tokenized, not fuzzy: your search string is broken into tokens, and a concept matches if its name or synonyms contain those tokens, in any order and not necessarily adjacent. Word order and adjacency are rewarded with a higher score rather than required, which is why disease Parkinson still finds Parkinson disease. What the default search does not do is tolerate misspellings: there is no edit-distance matching, so parkinsen finds nothing. (Solr's fuzzy ~ operator is escaped out of the query string along with the other special characters, so it cannot be requested either.) The one exception is autocomplete=true, which treats the final token as a prefix so that a half-typed word still matches.

`/lookup`

Search for cliques by a fragment of a name or synonym.

Endpoint: GET /lookup or POST /lookup

Parameters:

string (required, string): The string to search for. Must be at least the configured minimum length (see minimum_query_length in /status, default 2) after leading/trailing whitespace is stripped; shorter queries are rejected with HTTP 422, in the same body shape as any other parameter validation failure. The minimum does not apply when exact is set — exact matching is a single filter query rather than a tokenized search, and short labels such as the gene T are legitimate targets for it — but an empty string is rejected in every mode.
autocomplete (optional, boolean, default: false): If true, treats the input string as incomplete and looks for terms that start with the final word. If false, treats the entire phrase as complete (entity linker mode).
highlighting (optional, boolean, default: false): If true, returns information on which labels and synonyms matched the search query.
offset (optional, integer, default: 0, minimum: 0): The number of results to skip. Used for pagination.
limit (optional, integer, default: 10, minimum: 0, maximum: 1000): The number of results to return. Used for pagination.
biolink_type (optional, list of strings): Filter results to specific Biolink types. Types can be specified with or without the biolink: prefix (e.g., biolink:Disease or Disease). Multiple types are combined with OR logic, so filtering for PhenotypicFeature and Disease will return concepts that are either phenotypic features OR diseases.
only_prefixes (optional, string): Pipe-separated, case-sensitive list of CURIE prefixes to include (e.g., MONDO|EFO). Only results with matching prefixes will be returned.
exclude_prefixes (optional, string): Pipe-separated, case-sensitive list of CURIE prefixes to exclude (e.g., UMLS|EFO). Results with matching prefixes will be filtered out.
only_taxa (optional, string): Pipe-separated, case-sensitive list of taxa to filter to (e.g., NCBITaxon:9606|NCBITaxon:10090|NCBITaxon:10116|NCBITaxon:7955). Results without a specified taxon or with a matching taxon will be included.
debug (optional, string, one of: none, query, timing, results, all, default: none): Return debugging information from the underlying Solr query. See Solr debug documentation for details.
exact (optional, string, one of: label, synonyms, any): Require the whole search string to match, instead of matching its tokens individually. See Exact matching below. Omit for the default tokenized search.

Returns: A list of LookupResult objects, each containing:

curie: The CURIE of the concept.
label: The preferred name of the concept.
highlighting: An object with labels and synonyms arrays showing which matches were found (only included if highlighting=true).
synonyms: A list of all known synonyms for this concept.
score: The Solr search score for this result.
taxa: A list of taxa associated with this concept.
types: A list of Biolink types for this concept (prefixed with biolink:).
clique_identifier_count: The number of identifiers in this clique.
explain: Explanation of the score for this result (only included if debug is results or all).
debug: Debugging information for the entire query (only included if debug is not none). To avoid duplication, explains within this structure will be replaced with a {"_comment": "..."}.
- timing: Providing timing information for the Solr query (only included if debug is timing or all).
- parsedquery: The parsed query string (only included if debug is query or all).

Example requests:

GET request to search for "diabetes":

GET /lookup?string=diabetes&limit=5

POST request to search for "cancer" with filters:

POST /lookup?string=cancer&biolink_type=Disease&only_prefixes=MONDO&limit=10

GET request with autocomplete enabled:

GET /lookup?string=dmd&autocomplete=true&highlighting=true

Notes:

CURIEs are conflated with both GeneProtein and DrugChemical conflation. For example, when searching for a protein, the identifier of the gene that encodes the protein may also be returned. See the Conflation section for more information.
Search results are sorted by score (descending), then by clique identifier count (descending), then by CURIE suffix (ascending).

`/bulk-lookup`

Search for cliques for multiple strings in a single request.

Endpoint: POST /bulk-lookup

Request body: A JSON object with a NameResQuery structure:

{
  "strings": ["diabetes", "cancer"],
  "autocomplete": false,
  "highlighting": false,
  "offset": 0,
  "limit": 10,
  "biolink_types": [],
  "only_prefixes": "",
  "exclude_prefixes": "",
  "only_taxa": "",
  "debug": "none",
  "exact": null
}

Parameters: Same as /lookup, except:

strings (required, list of strings): A list of strings to search for. The returned results will be in a dictionary with these values as keys.
All other parameters are optional and apply to all searches.

Returns: A dictionary where each key is a string from the input strings array, and each value is a list of LookupResult objects (same structure as /lookup results). Unlike /lookup, a string shorter than the configured minimum length (see minimum_query_length in /status, default 2) is not rejected: it simply maps to an empty list, so one too-short string does not fail the whole batch. An empty string, and a string shorter than the minimum in exact mode, are treated the same way.

Example request:

POST /bulk-lookup with body:

{
  "strings": ["diabetes", "hypertension", "asthma"],
  "limit": 5,
  "biolink_types": ["Disease"]
}

Example response:

{
  "diabetes": [
    {
      "curie": "MONDO:0005148",
      "label": "diabetes mellitus",
      "highlighting": {},
      "synonyms": ["diabetes", ...],
      "score": 42.5,
      "taxa": [],
      "types": ["biolink:Disease", ...],
      "clique_identifier_count": 125
    },
    ...
  ],
  "hypertension": [...],
  "asthma": [...]
}

Notes:

This endpoint is useful for batch processing multiple queries at once, which can be more efficient than making multiple /lookup requests.
All results for a given string share the same filter and search parameters.
The individual lookups behind a single request are sent to Solr concurrently, up to a bounded number at a time (SOLR_MAX_CONCURRENT_LOOKUPS, default 100). Results are still returned keyed by the input string, so the response does not depend on the order in which they complete. Note that the bound applies per request, so the total number of queries this service has in flight against Solr is that limit multiplied by the number of bulk lookups being served at once.

Exact matching

Both /lookup and /bulk-lookup accept an exact parameter, which replaces the default tokenized eDisMax search with whole-string matching against the preferred_name_exactish and names_exactish fields. These fields are indexed with a keyword tokenizer and a lowercase filter, so the entire string must match, but matching is case-insensitive. A search for parkinson will not match the label parkinsonian disorder, whereas Parkinsonian Disorder will.

`exact`	Matches against
`label`	The preferred name only (`preferred_name_exactish`).
`synonyms`	The synonyms only (`names_exactish`).
`any`	Either the preferred name or a synonym.
(omitted)	Nothing changes: the usual tokenized eDisMax search is used.

Note that a concept's preferred name is not necessarily one of its synonyms, so label and synonyms can genuinely disagree. For example, HP:0001300 has the preferred name parkinsonian disorder and the single synonym Parkinsonian disease; searching for parkinsonian disorder with exact=label finds it, but with exact=synonyms it does not.

Exact matching is implemented as a Solr filter query, which is cheaper than the equivalent tokenized search because there is nothing to score: no eDisMax parsing, no phrase or field boosts, just a term lookup against a field that holds each name as a single token. It is intended for callers such as named entity recognition pipelines that need to resolve large numbers of exact strings.

That filter is deliberately marked uncached ({!cache=false}). Solr's filterCache is bounded by entry count rather than memory, and it holds the shared, reusable filters — types:, taxa:, curie: — that nearly every search benefits from. An exact-match clause is one distinct entry per distinct search string, so caching it would let a single bulk NER request evict the entire cache and slow down the ordinary search path, in exchange for a hit rate near zero on its own entries. Repeated identical exact lookups are still served from the queryResultCache, which caches the whole result and is bounded by RAM.

Because there is no relevance score to rank by in exact mode, results are sorted by clique_identifier_count (descending) and then CURIE suffix (ascending), rather than by score. The score field is still present in each result, but it carries no ranking information.

Exact matching and the other parameters

autocomplete cannot be used with exact. The two contradict each other — autocomplete treats the final word as an incomplete prefix, while exact requires the whole string to match — so the combination is rejected with a 400 rather than one of them being silently ignored.
Typographic quotes are not rewritten in exact mode. The default search folds ‘ ’ “ ” to their ASCII equivalents, since input is sometimes mangled by Windows and the tokenizer discards the punctuation regardless. Exact mode deliberately does not: the *_exactish fields keep whatever characters Babel emitted, so rewriting the query would search for a string you did not type and would put any label containing a typographic quote out of reach. Search for the string exactly as it appears in the data.
highlighting works, and always marks up the whole value. Every match in exact mode is a whole-value match, so a highlighted result is the entire matching name wrapped in <strong>…</strong> — parkinsonian disorder matched with exact=label returns {"labels": ["<strong>parkinsonian disorder</strong>"], "synonyms": []}. The name is returned in its own capitalisation, not the query's, so a case-insensitive match is still visible as one.

Example:

GET /lookup?string=parkinsonian%20disorder&exact=label

Lookup endpoints

The lookup endpoints allow you to retrieve all synonyms and information for a known CURIE (concept unique resource identifier). Unlike the search endpoints, these do not perform text matching; they retrieve data for exact CURIEs.

`/synonyms`

Look up all synonyms and information for a CURIE.

Endpoint: GET /synonyms or POST /synonyms

Parameters:

preferred_curies (required, list of strings): A list of CURIEs to look up synonyms for. You can normalize a CURIE to a preferred CURIE using NodeNorm.

Returns: A dictionary where each key is a CURIE from the input list, and each value is a document object containing:

curie: The CURIE identifier.
preferred_name: The preferred name for this concept.
names: A list of all known synonyms for this concept.
types: A list of Biolink types for this concept.
taxa: A list of taxa associated with this concept.
clique_identifier_count: The number of identifiers in this clique.
Additional metadata fields such as curie_suffix, id, and _version_.

Example requests:

GET request to look up a single CURIE:

GET /synonyms?preferred_curies=NCBIGene:1756

GET request to look up multiple CURIEs:

GET /synonyms?preferred_curies=MONDO:0005148&preferred_curies=NCBIGene:1756

POST /synonyms with body:

{
  "preferred_curies": ["MONDO:0005148", "NCBIGene:1756"]
}

Example response:

{
  "MONDO:0005148": {
    "curie": "MONDO:0005148",
    "preferred_name": "diabetes mellitus",
    "names": ["diabetes mellitus", "diabetes", "DM", ...],
    "types": ["Disease", "DiseaseOrPhenotypicFeature", ...],
    "taxa": [],
    "clique_identifier_count": 125,
    ...
  },
  "NCBIGene:1756": {
    "curie": "NCBIGene:1756",
    "preferred_name": "DMD",
    "names": ["DMD", "dystrophin", "BMD", ...],
    "types": ["Gene", "GeneOrGeneProduct", ...],
    "taxa": ["NCBITaxon:9606"],
    "clique_identifier_count": 22,
    ...
  }
}

Notes:

This endpoint provides a complete view of all synonyms and properties for a given concept.
CURIEs are conflated with both GeneProtein and DrugChemical conflation. For example, when looking up a protein CURIE, the synonyms for the gene that encodes the protein will also be included. See the Conflation section for more information.
If a CURIE is not found in the database, it will still appear in the response dictionary with an empty object as its value.
For large batches of CURIEs, consider using this endpoint instead of making individual requests, as it is optimized for batch lookups.

Health endpoints

`/status`

Returns the status of the service. Most importantly, this returns the Babel version and changelog URL, which can be used to determine which version of Babel is currently loaded in this service. It also includes the NameRes version (also visible in the OpenAPI documentation) and the Biolink Model version used to build the Solr database, as well as bunch of information from the underlying Solr database. The config object reports publicly-relevant configuration for this instance; currently just minimum_query_length, the shortest query (in characters, after whitespace is stripped) that /lookup and /bulk-lookup will search for in the default tokenized search. It defaults to 2 and can be set per deployment with the NAMERES_MINIMUM_QUERY_LENGTH environment variable. It does not constrain exact matching, which accepts any non-empty string.

{
  "status": "ok",
  "message": "Reporting results from primary core.",
  "babel_version": "2025sep1",
  "babel_version_url": "https://github.com/ncatstranslator/Babel/blob/master/releases/2025sep1.md",
  "biolink_model": {
    "tag": "v4.2.6-rc5",
    "url": "https://github.com/biolink/biolink-model/tree/v4.2.6-rc5",
    "download_url": "https://raw.githubusercontent.com/biolink/biolink-model/v4.2.6-rc5/biolink-model.yaml"
  },
  "nameres_version": "v1.5.1",
  "config": {
    "minimum_query_length": 2
  },
  "startTime": "2025-12-19T11:53:09.638Z",
  "numDocs": 425583391,
  "maxDoc": 425586610,
  "deletedDocs": 3219,
  "version": 34838,
  "segmentCount": 57,
  "lastModified": "2025-09-24T19:09:56.524Z",
  "size": "142.17 GB"
}

Navigation Menu

Uh oh!

Name Resolver API

Conflation

Search endpoints

`/lookup`

`/bulk-lookup`

Exact matching

Exact matching and the other parameters

Lookup endpoints

`/synonyms`

Health endpoints

`/status`

Uh oh!

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Name Resolver API

Conflation

Search endpoints

/lookup

/bulk-lookup

Exact matching

Exact matching and the other parameters

Lookup endpoints

/synonyms

Health endpoints

/status

`/lookup`

`/bulk-lookup`

`/synonyms`

`/status`