Bulk Search - OMOPHub.com API

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S"
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "diabetes"
      },
      {
        "search_id": "s2",
        "query": "hypertension"
      },
      {
        "search_id": "s3",
        "query": "aspirin",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

{
  "success": true,
  "data": [
    {
      "search_id": "s1",
      "query": "diabetes",
      "status": "completed",
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 4000678,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 856
    },
    {
      "search_id": "s2",
      "query": "hypertension",
      "status": "completed",
      "results": [
        {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 316866,
          "concept_name": "Hypertensive disorder",
          "concept_code": "38341003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 1034
    },
    {
      "search_id": "s3",
      "query": "aspirin",
      "status": "completed",
      "results": [
        {
          "concept_id": 1112807,
          "concept_name": "Aspirin",
          "concept_code": "1191",
          "vocabulary_id": "RxNorm",
          "domain_id": "Drug",
          "concept_class_id": "Ingredient",
          "standard_concept": "S",
          "search_score": 100
        }
      ],
      "duration": 957
    }
  ],
  "meta": {
    "request_id": "req_bulk_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S"
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "diabetes"
      },
      {
        "search_id": "s2",
        "query": "hypertension"
      },
      {
        "search_id": "s3",
        "query": "aspirin",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

{
  "success": true,
  "data": [
    {
      "search_id": "s1",
      "query": "diabetes",
      "status": "completed",
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 4000678,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 856
    },
    {
      "search_id": "s2",
      "query": "hypertension",
      "status": "completed",
      "results": [
        {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 316866,
          "concept_name": "Hypertensive disorder",
          "concept_code": "38341003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 1034
    },
    {
      "search_id": "s3",
      "query": "aspirin",
      "status": "completed",
      "results": [
        {
          "concept_id": 1112807,
          "concept_name": "Aspirin",
          "concept_code": "1191",
          "vocabulary_id": "RxNorm",
          "domain_id": "Drug",
          "concept_class_id": "Ingredient",
          "standard_concept": "S",
          "search_score": 100
        }
      ],
      "duration": 957
    }
  ],
  "meta": {
    "request_id": "req_bulk_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

Overview

This endpoint allows you to submit multiple search queries in a single request, enabling efficient batch processing of search operations. It’s ideal for applications that need to search for many terms simultaneously, such as data processing pipelines, bulk concept mapping, or batch validation workflows. Each query uses full-text search with a default limit of 20 results per query (configurable via page_size, max 100). Up to 50 queries can be submitted per request.

For paginated results or semantic search, use the Basic Search or Semantic Search endpoints instead.

Request Body

searches

array

required

Array of search query objects (1-50 items)

Show Search Object

search_id

string

required

Unique identifier for this search within the batch

query

string

required

Search term or phrase

bulk_mode

boolean

default:"true"

Enable bulk-optimized search mode for better performance

vocabulary_ids

string[]

Filter results to specific vocabularies (e.g., ["SNOMED", "ICD10CM"]). Overrides defaults.vocabulary_ids for this search.

domain_ids

string[]

Filter results to specific domains (e.g., ["Condition", "Drug"]). Overrides defaults.domain_ids for this search.

concept_class_ids

string[]

Filter results to specific concept classes (e.g., ["Clinical Finding"]). Overrides defaults.concept_class_ids for this search.

standard_concept

string

Filter by standard concept status: "S" (Standard) or "C" (Classification). Overrides defaults.standard_concept for this search.

include_invalid

boolean

default:"false"

Include invalid/deprecated concepts. Overrides defaults.include_invalid for this search.

page_size

integer

default:"20"

Number of results per search (1-100). Overrides defaults.page_size for this search.

defaults

object

Default filter parameters applied to all searches. Individual searches can override any default.

Show Defaults Object

vocabulary_ids

string[]

Default vocabulary filter for all searches (e.g., ["SNOMED"])

domain_ids

string[]

Default domain filter for all searches (e.g., ["Condition"])

concept_class_ids

string[]

Default concept class filter for all searches

standard_concept

string

Default standard concept filter: "S" or "C"

include_invalid

boolean

default:"false"

Default invalid concept inclusion

page_size

integer

default:"20"

Default results per search (1-100)

Query Parameters

vocab_release

string

Specific vocabulary release version (defaults to latest)

Response

success

boolean

Indicates if the request was successful

data

array

Array of search results, one per query

Show Search Result

search_id

string

Identifier matching the request’s search_id

query

string

Original search query

status

string

Query execution status: completed or failed

results

array

Array of matching concepts

Show Concept Result

concept_id

integer

Unique concept identifier

concept_name

string

Primary concept name

concept_code

string

Concept code

vocabulary_id

string

Source vocabulary

domain_id

string

Domain classification

concept_class_id

string

Concept class

standard_concept

string

Standard concept indicator

search_score

number

Search relevance score

error

string

Error message (if query failed)

duration

number

Processing time for this query in milliseconds

Usage Examples

Basic Bulk Search

Search multiple terms simultaneously without filters:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"search_id": "s1", "query": "diabetes"},
      {"search_id": "s2", "query": "hypertension"},
      {"search_id": "s3", "query": "asthma"}
    ]
  }'

Filtered Bulk Search with Defaults

Apply common filters to all searches using defaults, with per-search overrides:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "domain_ids": ["Condition"],
      "standard_concept": "S"
    },
    "searches": [
      {"search_id": "s1", "query": "diabetes"},
      {"search_id": "s2", "query": "heart failure"},
      {"search_id": "s3", "query": "metformin", "vocabulary_ids": ["RxNorm"], "domain_ids": ["Drug"]}
    ]
  }'

In this example, searches s1 and s2 use the defaults (SNOMED, Condition domain, standard concepts only). Search s3 overrides with RxNorm vocabulary and Drug domain. Apply different filters to each search individually:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"search_id": "s1", "query": "diabetes", "vocabulary_ids": ["SNOMED"], "domain_ids": ["Condition"]},
      {"search_id": "s2", "query": "metformin", "vocabulary_ids": ["RxNorm"], "domain_ids": ["Drug"]},
      {"search_id": "s3", "query": "HbA1c", "vocabulary_ids": ["LOINC"], "domain_ids": ["Measurement"]}
    ]
  }'

High-Volume Processing

Process larger batches from a file:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @bulk_queries.json

Example bulk_queries.json:

{
  "defaults": {
    "vocabulary_ids": ["SNOMED"],
    "standard_concept": "S"
  },
  "searches": [
    {"search_id": "q1", "query": "diabetes mellitus"},
    {"search_id": "q2", "query": "essential hypertension"},
    {"search_id": "q3", "query": "chronic kidney disease"},
    {"search_id": "q4", "query": "atrial fibrillation"},
    {"search_id": "q5", "query": "congestive heart failure"}
  ]
}

Optimization Strategies

Query Grouping

Batch Size: Optimal batch size is 10-50 queries per request
Bulk Mode: The bulk_mode parameter (default true) enables optimized query execution for better throughput
Result Limit: Each query returns up to 20 results by default (configurable via page_size, max 100)

Performance Tips

Use concise, specific search terms for faster results
Split very large query sets into multiple requests of 50 queries each
Use the search_id field to correlate results with your source data
Use defaults to apply common filters instead of repeating them per search
Applying filters (vocabulary, domain) generally improves performance by narrowing the search space

Error Handling

Each query in the batch is processed independently
Failed queries return status: "failed" with an error message
Successful queries are not affected by failures in other queries

Basic Search - Single query search with pagination
Advanced Search - Complex search with advanced filters
Semantic Search - AI-powered contextual search

Advanced Search Bulk Semantic Search

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Basic Bulk Search

​Filtered Bulk Search with Defaults

​Per-Search Filters

​High-Volume Processing

​Optimization Strategies

​Query Grouping

​Performance Tips

​Error Handling

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Bulk Search

Filtered Bulk Search with Defaults

Per-Search Filters

High-Volume Processing

Optimization Strategies

Query Grouping

Performance Tips

Error Handling

Related Endpoints