openapi: 3.2.0
info:
  title: OpenPrescribing Tariff 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: Tariff
  description: Drug-tariff prices and price-per-unit / ghost-generic savings data.
paths:
  /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'
components:
  responses:
    GenericList:
      description: A list of result objects.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
        text/csv:
          schema:
            type: string
    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
    BadRequest:
      description: Invalid request (bad/missing parameter, unrecognised org type, invalid code).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    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.
  schemas:
    Error:
      type: object
      description: Django REST Framework error envelope.
      properties:
        detail:
          type: string