Drug Compare API

The drug-compare endpoint allows you to compare drug prices across different pharmacies using GoodRx integration. This endpoint provides price comparison data including pharmacy information, prices, and coupon details.

Endpoint

POST /drugs/drug-compare

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

Header	Required	Description
access-token	Yes	Access token from generate-client-auth-token
Content-Type	Yes	Must be application/json
domain	Yes	Domain/group name for the request

Request Body

{
  name?: string;              // Optional: Drug name (lowercase)
  dosage?: string;            // Optional: Drug dosage (e.g., "20mg", "40mg")
  form?: string;              // Optional: Drug form (e.g., "tablet", "capsule")
  user_quantity?: number;      // Optional: User quantity
  location?: string;          // Optional: Zip code or city+state
  exclude_local?: boolean;    // Optional: Exclude non-NABP approved pharmacies (default: false)
}

Request Parameters

name (optional)

• Type: string
• Description: Drug name for price comparison. Automatically converted to lowercase
• Example: "lipitor" or "atorvastatin"

dosage (optional)

• Type: string
• Description: Drug dosage/strength
• Example: "20mg", "40mg", "10mg"

form (optional)

• Type: string
• Description: Drug form (e.g., tablet, capsule, liquid)
• Example: "tablet", "capsule", "oral tablet"

user_quantity (optional)

• Type: number
• Description: Quantity of medication to compare prices for
• Example: 30, 90, 100

location (optional)

• Type: string
• Description: Location for price comparison (zip code or city+state format)
• Example: "10001" or "New York, NY"

exclude_local (optional)

• Type: boolean
• Description: Whether to exclude non-NABP approved pharmacies. When true, only NABP-approved pharmacies are included
• Default: false
• Example: true or false

Success Response

Status Code: 200

{
  statusCode: 200;
  data: {
    days_supply: number;                    // Days supply
    dosage: string;                         // Drug dosage
    display: string;                        // Display name
    quantity: number;                       // Quantity (deprecated)
    metric_quantity: number;                // Metric quantity
    user_quantity: number;                  // User quantity
    manufacturer_type: string;              // Manufacturer type
    form: string;                           // Drug form
    url: string;                            // GoodRx URL
    short_url: string;                      // Short GoodRx URL
    mobile_url: string;                     // Mobile GoodRx URL
    short_mobile_url: string;              // Short mobile GoodRx URL
    equivalent_drugs: {
      generic: string[];                    // Array of generic drug names
      brand: string[];                      // Array of brand drug names
    };
    prices: [
      {
        coupon_url: string;                 // Coupon URL
        coupon_key: string;                 // Coupon key
        type: 'cash' | 'coupon' | 'membership'; // Price type
        ncpdp: string | null;              // NCPDP pharmacy identifier
        chain_ncpdps: string[];            // Chain NCPDP identifiers
        pharmacy: string;                   // Pharmacy name
        pharmacy_type: 'RETAIL' | 'MAIL_ORDER'; // Pharmacy type
        program_cost: number | null;       // Program cost
        price: number;                      // Price
        savings: string | null;            // Savings amount
        retail_price: number | null;       // Retail price
        has_goodrx_advantage?: boolean;    // GoodRx Advantage flag
      },
      // ... more prices
    ];
  };
  message: "OKAY";
}

Response Fields

days_supply

• Type: number
• Description: Number of days the medication supply covers
• Example: 30, 90

dosage

• Type: string
• Description: Drug dosage/strength
• Example: "20mg", "40mg"

display

• Type: string
• Description: Display name for the drug
• Example: "Atorvastatin 20mg tablet"

form

• Type: string
• Description: Drug form
• Example: "tablet", "capsule"

equivalent_drugs

• Type: object
• Description: Lists of equivalent generic and brand drugs
• Fields:
  • generic: Array of generic drug names
  • brand: Array of brand drug names

prices

• Type: array
• Description: Array of price comparison results from different pharmacies
• Fields:
  • coupon_url: URL to the coupon
  • coupon_key: Key to retrieve coupon details
  • type: Type of pricing (cash, coupon, or membership)
  • pharmacy: Name of the pharmacy
  • pharmacy_type: Type of pharmacy (RETAIL or MAIL_ORDER)
  • price: Price at this pharmacy
  • savings: Savings amount (if applicable)
  • retail_price: Retail price before discounts

Error Responses

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";
}

Causes:

• Error communicating with GoodRx API
• Internal server error

Example Requests

Example 1: Compare Prices for Brand Drug

This example shows comparing prices for a brand drug:

curl -X POST https://api.example.com/drugs/drug-compare \
  -H "Content-Type: application/json" \
  -H "access-token: your-access-token" \
  -H "domain: your-domain" \
  -d '{
    "name": "lipitor",
    "dosage": "20mg",
    "form": "tablet",
    "user_quantity": 30,
    "location": "10001",
    "exclude_local": false
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "days_supply": 30,
    "dosage": "20mg",
    "display": "Lipitor 20mg tablet",
    "quantity": 30,
    "metric_quantity": 30,
    "user_quantity": 30,
    "manufacturer_type": "brand",
    "form": "tablet",
    "url": "https://www.goodrx.com/lipitor",
    "short_url": "https://gdrx.co/lipitor",
    "mobile_url": "https://www.goodrx.com/lipitor",
    "short_mobile_url": "https://gdrx.co/lipitor",
    "equivalent_drugs": {
      "generic": ["atorvastatin"],
      "brand": ["Lipitor"]
    },
    "prices": [
      {
        "coupon_url": "https://www.goodrx.com/lipitor?c=abc123",
        "coupon_key": "abc123",
        "type": "coupon",
        "ncpdp": "1234567",
        "chain_ncpdps": [],
        "pharmacy": "CVS Pharmacy",
        "pharmacy_type": "RETAIL",
        "program_cost": null,
        "price": 45.99,
        "savings": "$150.00",
        "retail_price": 195.99,
        "has_goodrx_advantage": false
      },
      {
        "coupon_url": "https://www.goodrx.com/lipitor?c=def456",
        "coupon_key": "def456",
        "type": "coupon",
        "ncpdp": "7654321",
        "chain_ncpdps": [],
        "pharmacy": "Walgreens",
        "pharmacy_type": "RETAIL",
        "program_cost": null,
        "price": 42.50,
        "savings": "$153.49",
        "retail_price": 195.99,
        "has_goodrx_advantage": false
      }
    ]
  },
  "message": "OKAY"
}

Example 2: Compare Prices for Generic Drug

This example shows comparing prices for a generic drug:

curl -X POST https://api.example.com/drugs/drug-compare \
  -H "Content-Type: application/json" \
  -H "access-token: your-access-token" \
  -H "domain: your-domain" \
  -d '{
    "name": "atorvastatin",
    "dosage": "20mg",
    "form": "tablet",
    "user_quantity": 90,
    "location": "90210",
    "exclude_local": true
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "days_supply": 90,
    "dosage": "20mg",
    "display": "Atorvastatin 20mg tablet",
    "quantity": 90,
    "metric_quantity": 90,
    "user_quantity": 90,
    "manufacturer_type": "generic",
    "form": "tablet",
    "url": "https://www.goodrx.com/atorvastatin",
    "short_url": "https://gdrx.co/atorvastatin",
    "mobile_url": "https://www.goodrx.com/atorvastatin",
    "short_mobile_url": "https://gdrx.co/atorvastatin",
    "equivalent_drugs": {
      "generic": ["atorvastatin"],
      "brand": ["Lipitor"]
    },
    "prices": [
      {
        "coupon_url": "https://www.goodrx.com/atorvastatin?c=xyz789",
        "coupon_key": "xyz789",
        "type": "coupon",
        "ncpdp": "1112222",
        "chain_ncpdps": [],
        "pharmacy": "Rite Aid",
        "pharmacy_type": "RETAIL",
        "program_cost": null,
        "price": 12.99,
        "savings": "$183.00",
        "retail_price": 195.99,
        "has_goodrx_advantage": false
      }
    ]
  },
  "message": "OKAY"
}

Behavior Notes

GoodRx Integration

• This endpoint integrates with the GoodRx API to provide price comparison data
• All parameters are passed through to GoodRx's /v2/price/compare endpoint
• Drug names are automatically converted to lowercase before sending to GoodRx

Location-Based Pricing

• Prices vary by location (zipcode or city+state)
• If location is not provided, GoodRx may use default pricing or require location
• Location format can be zip code (e.g., "10001") or city+state (e.g., "New York, NY")

Pharmacy Filtering

• When exclude_local is true, only NABP-approved pharmacies are included
• When exclude_local is false (default), all pharmacies are included
• The exclude_local parameter is converted to 0 or 1 before sending to GoodRx

Price Types

• cash: Cash price without coupons
• coupon: Price with GoodRx coupon
• membership: Price with GoodRx membership program

Equivalent Drugs

• The response includes lists of equivalent generic and brand drugs
• This helps identify alternative medications with the same active ingredients

Error Handling

• If GoodRx API returns an error, the endpoint returns a default response structure with empty arrays
• Network errors or API failures result in a 500 status code

Related Documentation

• Rx Overview - Learn about Rx API concepts
• Search API - Search for medications by name
• Get Drug Details API - Retrieve detailed drug information
• API Guidelines - General API response formats and error codes