PharmGKB Data REST API request grammar

Contract

Enforce the PharmGKB (now branded ClinPGx) Data REST API request grammar: the fixed base URL, the exact camelCase resource tokens, accession-by-path vs criteria-by-query lookups, the view detail parameter, nested dot-notation filters, and the {data, status} response envelope. Apply whenever you build, describe, or debug an HTTP call to PharmGKB.

Rules

1. Base URL — every call targets https://api.pharmgkb.org/v1/data. The host is api.pharmgkb.org

(never www.pharmgkb.org) and the path prefix is exactly /v1/data (a v1 version segment, then data) — never /api/v1, never /rest, never /v1 alone.

1. Resource token — the next path segment is exactly ONE resource type, always a singular camelCase

token from this set: gene variant chemical haplotype pathway disease clinicalAnnotation variantAnnotation guidelineAnnotation drugLabel label Never pluralize (genes), never snake_case (clinical_annotation), never capitalize the first letter (Gene).

1. A drug is a chemical. PharmGKB models any drug as the chemical resource — not drug, not

medication.

1. Dosing / prescribing guidelines are guidelineAnnotation — NOT dosingGuideline (that resource

does not exist; the API rejects it as an invalid type), not guideline, not guidelines.

1. Two lookup shapes:

• By accession → put the accession as a PATH segment: gene/PA124. Returns a single object under

data.

• By symbol / name / criteria → use a QUERY string: gene?symbol=CYP2C19. Returns an array under

data.

1. Accession scheme — every PharmGKB identifier is the letters PA followed by digits (e.g. PA124,

PA166154053, PA449726). Never place a gene symbol, an rsID, or a bare number where an accession path segment belongs.

1. Detail level — the view query parameter selects verbosity; the allowed values are min, base,

max. Use view=max for the full record and view=min for a compact one (base is the middle default). Do not invent detail=, fields=, full=, or format=.

1. Filter by a related object — use dot-notation on the nested field's accessionId, e.g.

clinicalAnnotation?relatedChemicals.accessionId=PA449726. Only real object properties are accepted; do not invent flat params like chemicalId=, drug=, or chemical=.

1. No pagination params — the API has no limit, page, per_page, or offset. Unknown query keys

are matched to object properties and rejected (No such property: 'limit'). Cap results client-side or request view=min.

1. Response envelope — parse a top-level object: {"data": ..., "status": "success"} on success;

{"status": "fail", "data": {"errors": [{"message": "..."}]}} on failure. Every record carries an objCls type field (e.g. "objCls":"Gene"). It is never a bare top-level array.

1. Rate limit — at most 2 requests/second; exceeding it returns HTTP 429. Throttle client-side.

Worked examples

• Gene by symbol —
• wrong default: GET https://www.pharmgkb.org/api/genes?name=CYP2C19
• conforming: GET https://api.pharmgkb.org/v1/data/gene?symbol=CYP2C19
• Gene by accession, full detail —
• wrong: GET https://api.pharmgkb.org/v1/data/gene?id=PA124&detail=full
• conforming: GET https://api.pharmgkb.org/v1/data/gene/PA124?view=max
• Dosing guideline —
• wrong: GET https://api.pharmgkb.org/v1/data/dosingGuideline?drug=clopidogrel
• conforming: GET https://api.pharmgkb.org/v1/data/guidelineAnnotation?view=max
• Clinical annotations for a drug —
• wrong: GET .../clinicalAnnotations?chemical=galantamine&limit=10
• conforming: GET .../clinicalAnnotation?relatedChemicals.accessionId=PA449726&view=min
• Variant by rsID —
• wrong: GET .../snp/rs4244285
• conforming: GET .../variant?symbol=rs4244285

Edge cases & exceptions

• rsIDs are not accessions. Resolve a variant by rsID with variant?symbol=rs4244285 (query), then use

the returned PA... id for a direct variant/PA166154053 fetch.

• Drug known only by name. Call chemical?name=... first to obtain its PA accession, then filter

annotations by relatedChemicals.accessionId=<that PA>.

• "Guideline" ambiguity. Curated dosing/prescribing guidance is guidelineAnnotation; there is no

dosingGuideline or guideline resource.

• Capping results. There is no server-side count param; slice the returned data array client-side or

request view=min.

• Empty vs error. status:"success" with an empty data array means "no matches"; status:"fail"

with data.errors[].message means a bad request (e.g. an unknown property).

Do / Don't

• DO use host api.pharmgkb.org with /v1/data. DON'T use www.pharmgkb.org, /api/v1, or /rest.
• DO use singular camelCase resource tokens. DON'T pluralize or snake_case them.
• DO use guidelineAnnotation for dosing guidance. DON'T use dosingGuideline.
• DO use chemical for a drug. DON'T use drug or medication.
• DO fetch a known record by accession path segment (gene/PA124). DON'T pass it as ?id=.
• DO select detail with view=min|base|max. DON'T invent detail=, fields=, or format=.
• DO filter with relatedChemicals.accessionId=. DON'T invent chemicalId= or drug=.
• DO throttle to <=2 req/s. DON'T append limit, page, or offset.

Common mistakes

• Using www.pharmgkb.org or an /api/v1 path instead of api.pharmgkb.org/v1/data.
• Pluralizing paths (genes, variants, clinicalAnnotations).
• dosingGuideline instead of guidelineAnnotation.
• drug / drugs instead of chemical.
• Passing an rsID or gene symbol where a PA accession path segment belongs.
• Adding limit= / page= (rejected as an unknown property).
• Expecting a bare JSON array instead of the {data, status} envelope.

Quick checklist

• ] Base https://api.pharmgkb.org/v1/data
• ] Singular camelCase resource token
• ] chemical for drugs; guidelineAnnotation for dosing guidance
• ] Known record → accession path segment (PA...); search → ?symbol= / ?name=
• ] view=min|base|max for detail
• ] Related filter via relatedChemicals.accessionId=
• ] No limit / page / offset; <=2 req/s
• ] Parse {data, status} envelope + objCls