Complete, Filterable Concept Mappings

This summer we are focused on improving the experience of using the API. If you build code lists, resolve FHIR codings, or use the MCP server, at least one of these improves your automation.

Concept mappings limits removed

GET /v1/concepts/{concept_id}/mappings applied a fixed limit of 100 rows.

The endpoint is now paginated:

curl "https://api.omophub.com/v1/concepts/201826/mappings?page=2&page_size=100"

Every response now carries the real numbers:

{
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 1500,
      "total_pages": 15,
      "has_next": true,
      "has_previous": false
    }
  }
}

page_size defaults to 100 as before, now with the metadata that tells you whether it was the whole story. The effective maximum is 200.

MCP Server v1.6.0 - v1.6.2

Three releases this month with improvements.

search_concepts was ignoring vocabulary_ids. It sent the filter under the wrong parameter name, and the API ignores unrecognised query parameters rather than rejecting them. Now it's resolved. search_concepts dropped concept validity. The API returns valid_start_date, valid_end_date and invalid_reason on every concept; the formatter discarded all three. Results now show validity dates and an explicit [INVALID: <reason>] marker.

• map_concept returned at most 100 mappings with no way to get more. It now takes page and page_size, and its text output states when it is showing a partial set, which matters because that output is read by a model deciding whether it has finished.
• explore_concept could report "no mappings found" for a concept that has mappings, if the first 100 relationships it fetched happened to be hierarchy links. Filtering now happens server-side.

npm install -g @omophub/omophub-mcp@1.6.2

Hosted users at mcp.omophub.com already have all of this.

SDKs: mapping pagination everywhere

All three SDKs gained the mapping pagination described above, plus a helper that walks every page so you do not have to think about it.

# Every mapping, not the first page of them
for mapping in client.mappings.get_iter(201826):
    ...

all_mappings <- client$mappings$get_all(201826)

const { data } = await client.mappings.getAll(201826);

All three also expose relationship_ids, so the two filters the API stopped ignoring are reachable without dropping to a raw request:

# Both halves of a composite concept, not just the first
client.mappings.get(4167462, relationship_ids=["Maps to", "Maps to value"])

R SDK: a shape change you may have already hit

result$mappings works now as documented and the pagination metadata is attached as an attribute rather than by moving your data:

result <- client$mappings$get(201826)
result$mappings
attr(result, "pagination")$total_items

Also this month

• AI assistants can read the concept pages now directly from our site: omophub.com/concepts/{concept_id}.
• Our website offers additional help for LLMs about the OMOPHub features: https://omophub.com/llms.txt

Links

• Mappings API reference
• Vocabulary versions
• MCP Server on GitHub
• Dashboard

Found something that returns a confident wrong answer? That is the category we most want to hear about - tell us what you asked for and what came back.