Skip to main content

Search API

The search endpoint allows you to search for medications by name. The search uses fuzzy matching to find both brand and generic drugs, returning results ranked by similarity score.

Endpoint​

POST /drugs/search

Authentication​

This endpoint requires authentication using the access token obtained from generate-client-auth-token.

Include the token in the access-token header:

access-token: {access_token}

Request Headers​

HeaderRequiredDescription
access-tokenYesAccess token from generate-client-auth-token
Content-TypeYesMust be application/json
domainYesDomain/group name for the request

Request Body​

{
  query: string;  // Required: Search query for drug name
}

Request Parameters​

query (required)​

  • Type: string
  • Description: Search query to find matching medications. Can be a brand name (e.g., "Lipitor") or generic name (e.g., "atorvastatin")
  • Example: "lipitor" or "ibuprofen"

Success Response​

Status Code: 200

{
  statusCode: 200;
  data: {
    drugs: [
      {
        is_brand: boolean;              // Whether this is a brand drug
        drug_name: string;               // Drug name (uppercase)
        drug_brand_name: string;         // Brand name (uppercase)
        drug_generic_name: string | null; // Generic name (uppercase) or null
        drug_brand_image: string | null; // Brand image URL or null
        drug_brand_website: string | null; // Brand website URL or null
        similarity_score: number;        // Similarity score (higher is better)
      },
      // ... more drugs (up to 10)
    ];
  };
  message: "OKAY";
}

Response Fields​

Each drug in the array contains:

is_brand​

  • Type: boolean
  • Description: Indicates whether this is a brand drug (true) or generic drug (false)
  • Example: true for "LIPITOR", false for "ATORVASTATIN"

drug_name​

  • Type: string
  • Description: The drug name used for display (uppercase)
  • Example: "LIPITOR" or "ATORVASTATIN"

drug_brand_name​

  • Type: string
  • Description: The brand name associated with this drug (uppercase)
  • Example: "LIPITOR"

drug_generic_name​

  • Type: string | null
  • Description: The generic name for this drug (uppercase), or null if this is a brand drug
  • Example: "ATORVASTATIN" or null

drug_brand_image​

  • Type: string | null
  • Description: URL to the brand drug image, or null if not available
  • Example: "https://example.com/images/lipitor.jpg" or null

drug_brand_website​

  • Type: string | null
  • Description: URL to the brand drug website, or null if not available
  • Example: "https://www.lipitor.com" or null

similarity_score​

  • Type: number
  • Description: Similarity score indicating how well the drug matches the search query (higher is better)
  • Example: 0.95 (very similar) or 0.65 (moderately similar)

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Query is required";
}

Causes:

  • Missing query parameter in request body

Unauthorized (403)​

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

  • Missing or invalid access-token header
  • Expired or invalid access token

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "SERVER_FAULT";
}

Example Requests​

Example 1: Search for Brand Drug​

This example shows searching for a brand medication:

curl -X POST https://api.example.com/drugs/search \
  -H "Content-Type: application/json" \
  -H "access-token: your-access-token" \
  -H "domain: your-domain" \
  -d '{
    "query": "lipitor"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "drugs": [
      {
        "is_brand": true,
        "drug_name": "LIPITOR",
        "drug_brand_name": "LIPITOR",
        "drug_generic_name": null,
        "drug_brand_image": "https://example.com/images/lipitor.jpg",
        "drug_brand_website": "https://www.lipitor.com",
        "similarity_score": 0.98
      },
      {
        "is_brand": false,
        "drug_name": "ATORVASTATIN",
        "drug_brand_name": "LIPITOR",
        "drug_generic_name": "ATORVASTATIN",
        "drug_brand_image": "https://example.com/images/lipitor.jpg",
        "drug_brand_website": "https://www.lipitor.com",
        "similarity_score": 0.75
      }
    ]
  },
  "message": "OKAY"
}

Example 2: Search for Generic Drug​

This example shows searching for a generic medication:

curl -X POST https://api.example.com/drugs/search \
  -H "Content-Type: application/json" \
  -H "access-token: your-access-token" \
  -H "domain: your-domain" \
  -d '{
    "query": "ibuprofen"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "drugs": [
      {
        "is_brand": false,
        "drug_name": "IBUPROFEN",
        "drug_brand_name": "ADVIL",
        "drug_generic_name": "IBUPROFEN",
        "drug_brand_image": "https://example.com/images/advil.jpg",
        "drug_brand_website": "https://www.advil.com",
        "similarity_score": 0.95
      },
      {
        "is_brand": true,
        "drug_name": "ADVIL",
        "drug_brand_name": "ADVIL",
        "drug_generic_name": null,
        "drug_brand_image": "https://example.com/images/advil.jpg",
        "drug_brand_website": "https://www.advil.com",
        "similarity_score": 0.85
      }
    ]
  },
  "message": "OKAY"
}

Behavior Notes​

Search Algorithm​

  • Uses fuzzy matching with similarity scoring
  • Searches both brand names and generic names
  • Returns up to 2 brand matches and up to 3 generic matches
  • Combines results and sorts by similarity score

Result Ordering​

Results are ordered by:

  1. Similarity Score (descending) - Most similar matches first
  2. Brand Priority (descending) - Brand drugs prioritized over generics
  3. Drug Name (ascending) - Alphabetical order for ties

Result Limit​

  • Maximum of 10 drugs returned per search
  • If more than 10 matches exist, only the top 10 are returned

Case Sensitivity​

  • Search is case-insensitive
  • All returned drug names are uppercase

Empty Results​

  • If no drugs match the query, an empty array [] is returned
  • This is not an error condition - try a different or more general query