# /pmda/drugs/search

`POST /api/pmda/drugs/search`

Price: 20 credits

Search Japan's register of prescription-drug package inserts. Narrows by generic or brand name, therapeutic class code, a term inside the insert's indications, warnings, contraindications or drug interactions, the marketing authorisation holder, and the date the insert was last updated. Every match carries the drug's generic and brand names, its marketing authorisation holder and distributors with their roles, the package insert's revision date and its PDF and XML links, and the links to the patient guide, interview form, risk management plan and its materials, the revision-instruction history and the review reports where the register publishes them.

## How to use it

Names, indications and section terms must be written in Japanese — the register holds no English text, so `aspirin` matches nothing while `アスピリン` does. A query matching more than 1000 inserts returns a 412 rather than the first 1000, so narrow it with `therapeutic_class` or an exact `name_match` instead of raising `count`. `therapeutic_class` is the Japanese commodity classification, not ATC: three digits is one class and two digits its parent, and the parent groups are usually wide enough to hit that limit. One row is one package insert, and the same drug appears once per manufacturer, so generic molecules return dozens of near-identical rows. Some matches are aggregate entries for a substance with no current insert of its own — several brand names and companies in one row, carrying only a revision-history link — and those are not returned, so the register's own match count runs ahead of what this endpoint can hand back. Feed `id` to pmda/drugs/package_insert for the insert's structured text.

## Parameters

- `access-token` (string, required)

## Request body

- `timeout` (integer) — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
- `name` (string, nullable) — Generic or brand name of the drug, in Japanese (examples: "ロキソプロフェン", "アスピリン"; minLength: 1)
- `name_field` (string) — Which name column name is matched against (default: "1"; one of: "1", "2", "3")
- `name_match` (string) — Whether name matches anywhere in the name or only at its start (default: "1"; one of: "1", "2")
- `therapeutic_class` (string, nullable) — Japanese Standard Commodity Classification therapeutic class code, two or three digits. Three digits is a single class, two digits its parent group (examples: "114", "429", "391"; minLength: 1)
- `indication` (string, nullable) — Term searched inside the package insert's indications section, in Japanese (examples: "関節リウマチ"; minLength: 1)
- `warning` (string, nullable) — Term searched inside the package insert's warnings section, in Japanese (examples: "ショック"; minLength: 1)
- `contraindication` (string, nullable) — Term searched inside the package insert's contraindications section, in Japanese (examples: "妊婦"; minLength: 1)
- `interaction` (string, nullable) — Term searched inside the package insert's drug-interactions section, in Japanese (examples: "ワルファリン"; minLength: 1)
- `marketing_authorisation_holder` (string, nullable) — Part of the name of the company that holds the marketing authorisation, in Japanese (examples: "第一三共", "沢井製薬"; minLength: 1)
- `updated_from` (string, nullable) — Keep package inserts updated on or after this date, YYYYMMDD or YYYY-MM-DD (examples: "20250101")
- `updated_to` (string, nullable) — Keep package inserts updated on or before this date, YYYYMMDD or YYYY-MM-DD (examples: "20251231")
- `count` (integer, required) — Max number of package inserts to return (min: 1; max: 1000)

## Response

### 200 — Successful Response

- `@type` (string) (default: "PmdaDrug")
- `id` (string, required)
- `generic_name` (string) (default: "")
- `general_name_code` (string) (default: "")
- `brand_name` (string) (default: "")
- `companies` (array) (default: [])
  - `@type` (string) (default: "PmdaCompany")
  - `role` (string) (default: "")
  - `name` (string) (default: "")
- `package_insert_revised_date` (string, nullable)
- `package_insert_pdf_url` (string, nullable)
- `package_insert_xml_url` (string, nullable)
- `patient_guides` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")
- `interview_forms` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")
- `risk_management_plans` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")
- `rmp_materials_for_professionals` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")
- `rmp_materials_for_patients` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")
- `revision_instruction_history` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")
- `review_reports` (array) (default: [])
  - `@type` (string) (default: "PmdaDocumentLink")
  - `document_title` (string) (default: "")
  - `url` (string) (default: "")

## Errors

### 422 — Validation Error

No search criterion was given, or an update date was not YYYYMMDD.

What to do: Check the fields against this schema. A URN with the wrong prefix is the most common cause.

- `detail` (array)
  - `loc` (array, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any)
  - `ctx` (object)

### 408

The request ran past its time limit

What to do: Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.

### 412

Nothing matched, or the query matched more than the 1000 inserts the register is willing to return at once and it returned none.

What to do: Retrying will not help: either the entity does not exist, or the input points at a different one.

### 429

Too many requests: a rate limit or a usage window is exhausted

What to do: When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.

### 500

Something broke on our side

What to do: Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.

### 529

Rate limit reached, or the endpoint is overloaded

What to do: Wait at least 30 seconds, then retry.

## Response envelope

Success: Array of objects (may be empty if no results)

Error: Error may coexist with partial results if it occurs mid-execution. Check X-Error header and status code.

Every response carries these headers:

- `X-Error` — Error message text (present only on error)
- `X-Request-ID` — Unique request identifier
- `X-Execution-Time` — Execution time in seconds
- `X-Result-Count` — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
- `X-Total-Available-Results` — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
- `X-Warning` — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
- `X-Retry-After` — Seconds to wait before retrying. Present only on 429.