GET
/api/iqvia/rx-velocityIQVIA NPA Rx velocity
Weekly TRx / NRx / NBRx with plan-vs-actual variance.
Simulates the IQVIA NPA (National Prescription Audit) weekly Rx feed. The mock generates a sigmoid launch curve peaking around week 24 post-launch, with actuals diverging ~15% below plan after week 5 — the 'missed launch' post-mortem scenario (Pharmaceutical Commerce: 15% lower early script volume attributed to misaligned data).
Query parameters
| Name | Type | Description |
|---|---|---|
productrequired | string | Brand name. Any value accepted; same value returns deterministic data. e.g. ZENVARA |
weeks | integer | Trailing window length. Capped at 52. default: 12 |
territory | enum | Sub-national rollup. default: nationalallowed: nationalnortheastsoutheastmidwestwest |
Response schema
| Path | Type | Description |
|---|---|---|
product | string | Echo of the product param. |
territory | string | Echo of the territory param. |
unit | string | Always 'TRx' (total prescriptions). |
current_week_ending | string (ISO date) | Most recent Friday week-ending. |
weeks_since_launch | integer | Assumed week-of-launch position. Fixed at 22 in the mock. |
data[] | array | Weekly records, oldest first. |
data[].week_ending | string | Friday week-ending — NPA convention. Source: IQVIA NPA fact sheet |
data[].trx | integer | Total prescriptions = NRx + RRx (refills). Source: IQVIA NPA |
data[].nrx | integer | New prescriptions (first-fill + renewal of expired). NRx ≤ TRx. Source: IQVIA NPA |
data[].nbrx | integer | New-to-brand — patient never had brand before. NBRx ≤ NRx. Source: IQVIA — Five Things About NBRx |
data[].trx_plan | integer | Plan target TRx for the week. |
data[].variance_pct | number | (actual − plan) / plan × 100, rounded to one decimal. |
data[].cumulative_trx | integer | Running TRx sum across the window. |
totals.by_channel | object | Channel split. Keys: RETAIL / MAIL / LTC. Sums to ~1.0. Source: IQVIA NPA channels |
totals.by_payment | object | Method of payment. Keys: CASH / MEDICAID / MEDICARE_D / COMMERCIAL. Sums to ~1.0. Source: IQVIA NPA payment methods |
Behaviour notes
- ·week_ending is always Friday — NPA convention.
- ·NRx ≤ TRx and NBRx ≤ NRx are mathematical invariants enforced by the mock.
- ·Variance pattern: actuals track plan through week 5, then drift -10% to -25% — the 'missed launch' demo scenario.
- ·Volumes calibrated to land week-12 national TRx in the 800–2,500 range per IQVIA launch benchmarks.
- ·Sub-territories sum to roughly national (±15%).
Examples
Last 12 weeks national
curl 'http://localhost:3000/api/iqvia/rx-velocity?product=ZENVARA&weeks=12&territory=national'Last 26 weeks northeast
curl 'http://localhost:3000/api/iqvia/rx-velocity?product=ZENVARA&weeks=26&territory=northeast'Sources
- IQVIA NPA / NSP fact sheet 2024https://www.iqvia.com/-/media/iqvia/pdfs/us/fact-sheet/2024/iqvia-national-sales-and-prescription-insights.pdf
- IQVIA — Five Things About NBRxhttps://www.iqvia.com/locations/united-states/blogs/2022/10/five-things-to-know-about-using-nbrx-in-your-incentive-compensation-ic-plan
- Tellius — IMS 150-launch study synthesishttps://www.tellius.com/resources/blog/the-complete-guide-to-patient-journey-analytics-apld-analysis-and-lot-analytics-in-pharma