openapi: 3.1.0
info:
  title: OpenPrescribing API
  version: "1.0"
  summary: Free, open, key-less REST API over English NHS primary-care prescribing data.
  description: >-
    OpenPrescribing.net exposes NHS England primary-care (GP) prescribing data as a free,
    public, RESTful API. It is built and operated by the Bennett Institute for Applied Data
    Science at the University of Oxford on top of the English Prescribing Dataset published
    monthly by the NHS Business Services Authority. The API returns prescribing spending,
    quantity and item counts by BNF code and by NHS organisation (practice, PCN, Sub-ICB
    Location / CCG, ICB / STP, Regional Team), standardised prescribing-quality measures,
    drug-tariff and price-per-unit data, ghost-generic savings, and organisation reference
    and boundary lookups. Responses are JSON or CSV; organisation-location endpoints return
    GeoJSON. No registration, API key or OAuth is required.
    This specification was generated by API Evangelist by reading the public, MIT-licensed
    Django source (openprescribing/api/urls.py and the api/views_*.py modules); it is not a
    provider-published spec.
  license:
    name: MIT
    url: https://github.com/bennettoxford/openprescribing/blob/main/LICENSE.txt
  contact:
    name: Bennett Institute for Applied Data Science
    url: https://openprescribing.net/api/
servers:
  - url: https://openprescribing.net/api/1.0
    description: Production
tags:
  - name: Spending
    description: Prescribing spending, quantity and item counts by BNF code and organisation.
  - name: Measures
    description: Standardised NHS prescribing-quality and safety measures.
  - name: Tariff
    description: Drug-tariff prices and price-per-unit / ghost-generic savings data.
  - name: Reference
    description: BNF code, organisation code and organisation-location reference lookups.
paths:
  /spending/:
    get:
      operationId: getSpending
      summary: Total prescribing spending across all England
      description: >-
        Total prescribing spending, quantity and items across the last five years of the
        English Prescribing Dataset for one or more BNF codes, aggregated across England.
      tags: [Spending]
      parameters:
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/SpendingList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /spending_by_org/:
    get:
      operationId: getSpendingByOrg
      summary: Prescribing spending by organisation
      description: >-
        Prescribing spending, quantity and items by BNF code, broken down by NHS organisation
        of the requested org_type (practice, pcn, ccg / sicbl, stp / icb, regional_team).
      tags: [Spending]
      parameters:
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/org'
        - $ref: '#/components/parameters/orgType'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/SpendingList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
  /spending_by_sicbl/:
    get:
      operationId: getSpendingBySicbl
      summary: Prescribing spending by Sub-ICB Location (CCG)
      description: Prescribing spending by BNF code broken down by Sub-ICB Location (formerly CCG).
      tags: [Spending]
      parameters:
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/org'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/SpendingList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /spending_by_practice/:
    get:
      operationId: getSpendingByPractice
      summary: Prescribing spending by GP practice
      description: Prescribing spending by BNF code broken down by GP practice.
      tags: [Spending]
      parameters:
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/org'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/SpendingList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /bubble/:
    get:
      operationId: getBubble
      summary: Price-per-unit bubble-chart data
      description: >-
        Price-per-unit data for a single BNF presentation in a shape suitable for a Highcharts
        bubble chart, optionally highlighting/focusing a single organisation.
      tags: [Tariff]
      parameters:
        - name: bnf_code
          in: query
          required: true
          schema: { type: string }
          description: BNF presentation code.
        - name: date
          in: query
          required: true
          schema: { type: string, format: date }
          description: Month (YYYY-MM-DD, first of month) within the available 5-year window.
        - name: highlight
          in: query
          schema: { type: string }
          description: Organisation code to highlight (practice or CCG/Sub-ICB Location).
        - name: focus
          in: query
          schema: { type: string }
          description: When set together with highlight, restricts the chart to the highlighted org.
      responses:
        '200': { $ref: '#/components/responses/Bubble' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /tariff/:
    get:
      operationId: getTariff
      summary: Drug-tariff prices
      description: >-
        Drug-tariff prices (including NCSO price-concession data) for one or more BNF codes.
        Requesting no codes returns the entire (large) tariff and is cached.
      tags: [Tariff]
      parameters:
        - name: codes
          in: query
          schema: { type: string }
          description: Comma-separated list of BNF codes. Omit to return the whole drug tariff.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/GenericList' }
  /price_per_unit/:
    get:
      operationId: getPricePerUnit
      summary: Price-per-unit savings
      description: >-
        Price-per-unit data and potential savings for presentations across practices or
        Sub-ICB Locations for a given month.
      tags: [Tariff]
      parameters:
        - name: date
          in: query
          required: true
          schema: { type: string, format: date }
          description: Month (YYYY-MM-DD, first of month).
        - name: entity_code
          in: query
          schema: { type: string }
          description: Organisation code (practice or CCG/Sub-ICB Location).
        - name: entity_type
          in: query
          schema: { type: string, enum: [practice, ccg] }
          description: Organisation type; inferred from entity_code length when omitted.
        - name: child_org_type
          in: query
          schema: { type: string }
          description: Child organisation type to break results down to (e.g. practice).
        - name: bnf_code
          in: query
          schema: { type: string }
          description: Restrict to a single BNF code.
        - name: aggregate
          in: query
          schema: { type: boolean }
          description: Aggregate across all of England.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/GenericList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /ghost_generics/:
    get:
      operationId: getGhostGenerics
      summary: Ghost-generic savings
      description: >-
        Potential savings from "ghost-branded generic" prescribing, comparing the price paid
        against the national median price, for a given month and organisation.
      tags: [Tariff]
      parameters:
        - name: date
          in: query
          required: true
          schema: { type: string, format: date }
          description: Month (YYYY-MM-DD, first of month).
        - name: entity_code
          in: query
          schema: { type: string }
          description: Organisation code.
        - name: entity_type
          in: query
          required: true
          schema: { type: string, enum: [practice, ccg] }
          description: Organisation type.
        - name: group_by
          in: query
          schema: { type: string, enum: [practice, presentation, all], default: practice }
          description: Aggregation level for the results.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/GenericList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /measure/:
    get:
      operationId: getMeasures
      summary: Global (all-England) measure values
      description: National (all-England) values for one or more standardised prescribing measures.
      tags: [Measures]
      parameters:
        - $ref: '#/components/parameters/measure'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/MeasureList' }
  /measure_by_regional_team/:
    get:
      operationId: getMeasureByRegionalTeam
      summary: Measure values by Regional Team
      tags: [Measures]
      parameters:
        - $ref: '#/components/parameters/measure'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/orgList'
        - $ref: '#/components/parameters/parentOrgType'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/MeasureList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /measure_by_icb/:
    get:
      operationId: getMeasureByIcb
      summary: Measure values by ICB (STP)
      tags: [Measures]
      parameters:
        - $ref: '#/components/parameters/measure'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/orgList'
        - $ref: '#/components/parameters/parentOrgType'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/MeasureList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /measure_by_sicbl/:
    get:
      operationId: getMeasureBySicbl
      summary: Measure values by Sub-ICB Location (CCG)
      tags: [Measures]
      parameters:
        - $ref: '#/components/parameters/measure'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/orgList'
        - $ref: '#/components/parameters/parentOrgType'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/MeasureList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /measure_by_pcn/:
    get:
      operationId: getMeasureByPcn
      summary: Measure values by Primary Care Network (PCN)
      tags: [Measures]
      parameters:
        - $ref: '#/components/parameters/measure'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/orgList'
        - $ref: '#/components/parameters/parentOrgType'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/MeasureList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /measure_by_practice/:
    get:
      operationId: getMeasureByPractice
      summary: Measure values by GP practice
      tags: [Measures]
      parameters:
        - $ref: '#/components/parameters/measure'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/orgList'
        - $ref: '#/components/parameters/parentOrgType'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/MeasureList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /measure_numerators_by_org/:
    get:
      operationId: getMeasureNumeratorsByOrg
      summary: Measure numerator breakdown by organisation
      description: >-
        The individual presentations that make up a measure's numerator, broken down for a
        given organisation.
      tags: [Measures]
      parameters:
        - name: measure
          in: query
          required: true
          schema: { type: string }
          description: Single measure id.
        - name: org_type
          in: query
          schema: { type: string }
          description: Organisation type.
        - name: org
          in: query
          schema: { type: string }
          description: Organisation code.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/GenericList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /org_details/:
    get:
      operationId: getOrgDetails
      summary: Organisation statistics (list size, ASTRO-PU, STAR-PU)
      description: >-
        Practice-level statistics such as total list size, ASTRO-PU and STAR-PU values for one
        or more organisations, optionally restricted to a set of keys.
      tags: [Reference]
      parameters:
        - name: org_type
          in: query
          schema: { type: string }
          description: Organisation type.
        - name: keys
          in: query
          schema: { type: string }
          description: Comma-separated list of statistic keys to return.
        - name: org
          in: query
          schema: { type: string }
          description: Comma-separated list of organisation codes.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/GenericList' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /bnf_code/:
    get:
      operationId: getBnfCodes
      summary: Search BNF sections, chemicals and presentations
      description: >-
        Search the BNF hierarchy (chapters, sections, paragraphs, chemicals, products and
        presentations) by name or code.
      tags: [Reference]
      parameters:
        - name: q
          in: query
          schema: { type: string }
          description: Search term(s); comma-separated for multiple codes/names.
        - name: exact
          in: query
          schema: { type: string, enum: ["true", "false"] }
          description: When "true", match codes/names exactly instead of prefix/substring.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/BnfCodeList' }
  /org_code/:
    get:
      operationId: getOrgCodes
      summary: Look up NHS organisations by code or name
      description: >-
        Look up NHS organisations (practice, PCN, Sub-ICB Location, ICB, Regional Team) by
        code or name.
      tags: [Reference]
      parameters:
        - name: q
          in: query
          schema: { type: string }
          description: Organisation code or name to search for.
        - name: org_type
          in: query
          schema: { type: string, enum: [practice, pcn, ccg, stp, regional_team] }
          description: Restrict the search to a single organisation type.
        - $ref: '#/components/parameters/format'
      responses:
        '200': { $ref: '#/components/responses/GenericList' }
  /org_location/:
    get:
      operationId: getOrgLocation
      summary: Organisation boundaries and locations (GeoJSON)
      description: >-
        Sub-ICB Location / ICB / PCN / Regional Team boundaries, or approximate practice
        point locations, returned as a GeoJSON FeatureCollection.
      tags: [Reference]
      parameters:
        - name: org_type
          in: query
          schema: { type: string, enum: [practice, ccg, pcn, stp, regional_team], default: practice }
          description: Organisation type.
        - name: q
          in: query
          schema: { type: string }
          description: Comma-separated organisation codes.
        - name: centroids
          in: query
          schema: { type: string }
          description: When set, return boundary centroids instead of full polygons.
      responses:
        '200':
          description: GeoJSON FeatureCollection.
          content:
            application/json:
              schema: { type: object }
components:
  parameters:
    code:
      name: code
      in: query
      schema: { type: string }
      description: Comma-separated list of BNF code prefixes (section, chemical or presentation).
    org:
      name: org
      in: query
      schema: { type: string }
      description: Comma-separated list of NHS organisation codes.
    orgList:
      name: org
      in: query
      schema: { type: string }
      description: Comma-separated list of NHS organisation codes.
    orgType:
      name: org_type
      in: query
      schema: { type: string, enum: [practice, pcn, ccg, sicbl, stp, icb, regional_team] }
      description: NHS organisation type to break results down by.
    parentOrgType:
      name: parent_org_type
      in: query
      schema: { type: string }
      description: Parent organisation type to scope the query to.
    date:
      name: date
      in: query
      schema: { type: string, format: date }
      description: Month (YYYY-MM-DD, first of month) within the available 5-year window.
    measure:
      name: measure
      in: query
      schema: { type: string }
      description: Comma-separated list of measure ids.
    tags:
      name: tags
      in: query
      schema: { type: string }
      description: Comma-separated list of measure tags to filter by.
    aggregate:
      name: aggregate
      in: query
      schema: { type: boolean }
      description: Aggregate values across all organisations of the requested type.
    format:
      name: format
      in: query
      schema: { type: string, enum: [json, csv], default: json }
      description: >-
        Response format. May also be supplied as a URL suffix (.json / .csv) via DRF
        format_suffix_patterns.
  responses:
    SpendingList:
      description: A list of monthly spending rows.
      content:
        application/json:
          schema:
            type: array
            items: { $ref: '#/components/schemas/Spending' }
        text/csv:
          schema: { type: string }
    MeasureList:
      description: A list of measure values.
      content:
        application/json:
          schema:
            type: array
            items: { $ref: '#/components/schemas/MeasureValue' }
        text/csv:
          schema: { type: string }
    BnfCodeList:
      description: A list of matching BNF hierarchy entries.
      content:
        application/json:
          schema:
            type: array
            items: { $ref: '#/components/schemas/BnfCode' }
    Bubble:
      description: Bubble-chart series and categories.
      content:
        application/json:
          schema:
            type: object
            properties:
              plotline: { type: [number, "null"] }
              series: { type: array, items: { type: object } }
              categories: { type: array, items: { type: object } }
    GenericList:
      description: A list of result objects.
      content:
        application/json:
          schema: { type: array, items: { type: object } }
        text/csv:
          schema: { type: string }
    BadRequest:
      description: Invalid request (bad/missing parameter, unrecognised org type, invalid code).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Date outside the available data window, or resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Spending:
      type: object
      properties:
        date: { type: string, format: date }
        actual_cost: { type: number }
        items: { type: integer }
        quantity: { type: number }
        row_id: { type: string }
        row_name: { type: string }
    MeasureValue:
      type: object
      properties:
        measure: { type: string }
        org_type: { type: string }
        org_id: { type: string }
        org_name: { type: string }
        date: { type: string, format: date }
        numerator: { type: number }
        denominator: { type: number }
        calc_value: { type: [number, "null"] }
        percentile: { type: [number, "null"] }
    BnfCode:
      type: object
      properties:
        type:
          type: string
          description: One of BNF chapter/section/paragraph/subparagraph, chemical, product, product format.
        id: { type: string }
        name: { type: string }
        is_generic: { type: boolean }
        section: { type: string }
    Error:
      type: object
      description: Django REST Framework error envelope.
      properties:
        detail: { type: string }