get:
  tags:
    - Frequent users
  operationId: populationFrequentUserPatients
  summary: Frequent users
  description: Lists the top n (1-50) frequent users (patients).
  parameters:
    - name: periodStart
      in: query
      description: Start of the period (including) to analyze.
      schema: 
        $ref: ../schemas/date.yaml
    - name: periodEnd
      in: query
      description: End of the period (excluding) to analyze.
      schema: 
        $ref: ../schemas/date.yaml
    - name: gpAgbs
      in: query
      description: |-
        If present, restrict report to patients registered to any of the GP AGBs listed here.
        The restriction is applied to the GP responsible for the patient now, not on the GP responsible at the time of the feat.
      schema:
        type: array
        items:
          type: integer
    - name: gpMemocodes
      in: query
      description: |-
        If present, restrict report to patients registered to any of the GPs listed here; list the memocode as used in the GP Information System.
        The restriction is applied to the GP responsible for the patient now, not on the GP responsible at the time of the feat.
      example: 01015678,01018765,01014321
      schema: 
        type: array
        items: 
          $ref: ../schemas/med_dossier/Practitioner.yaml
    - name: featCodes
      in: query
      description: "The feats which are identified as time consuming or otherwise taking effort of the practice, defaults to: 12011,12411,12001,12401,12010,12410."
      schema: 
        $ref: ../schemas/med_dossier/FeatCode.yaml
    - name: patients
      in: query
      description: If present, restrict output to only patients in this list.
      schema:
        type: array
        items:
          $ref: ../schemas/pat-patId.yaml
    - name: pii
      in: query
      description: "Allow personal identifying information in the response. Defaults to false if omitted. If false, only category, doctor, patid, patUnid and feats are in the response. In other words: they are always in the response, but can be extended with other pii properties, see non-required properties below."
      example: true
      schema:
        type: boolean
    - name: limit
      in: query
      description: "Limits the output to the top 1 to 50 of the frequent users (patients). Defaults to 20 if omitted or not in the specified range."
      schema:
        type: integer
        minimum: 1
        maximum: 50
  responses: 
    200: 
      description: "Responds with an array with patients. Only the top `limit` users are exported. The output is ranked with the most frequent user at position 0 of the array."
      content: 
        application/json:
          schema: 
            type: array
            items: 
              type: object
              required:
                - category
                - doctor
                - patid
                - patUnid
                - feats
              properties:
                bsn:
                  $ref: '../schemas/PatIdentity.yaml#/bsn'
                name:
                  $ref: '../schemas/PatIdentity.yaml#/name'
                gender:
                  $ref: '../schemas/PatIdentity.yaml#/gender'
                dob:
                  $ref: '../schemas/PatIdentity.yaml#/dob'
                category:
                  $ref: '../schemas/PatIdentity.yaml#/category'
                doctor:
                  $ref: '../schemas/PatIdentity.yaml#/doctor'
                address:
                  $ref: '../schemas/PatIdentity.yaml#/address'
                contact:
                  $ref: '../schemas/PatIdentity.yaml#/contact'
                insurance:
                  $ref: '../schemas/PatIdentity.yaml#/insurance'
                patid:
                  $ref: '../schemas/PatIdentity.yaml#/patid'
                patPubId:
                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
                patUnid:
                  $ref: '../schemas/PatIdentity.yaml#/patUnid'
                feats:
                  type: object
                  properties:
                    featCode0:
                      type: object
                      description: The string featCode0 is replaced by an actual code, e.g. 12001.
                      properties: 
                        description:
                          type: string
                          example: consult huisarts langer dan 20 minuten
                          description: The feat description is taken from the GPIS import.
                        n:
                          type: number
                          description: The count of the feats with the given code for the patient.
                          example: 59
                    featCodeN:
                      type: object
                      properties: 
                        description:
                          type: string
                          example: Consult regulier korter dan 5 minuten
                        n:
                          type: number
                          example: 54
    400:
      $ref: '../zoo-api.yaml#/components/responses/ReqFailure'
    401:
      $ref: '../zoo-api.yaml#/components/responses/JwtFailure'
    403:
      $ref: '../zoo-api.yaml#/components/responses/MandateMissing'
    404:
      $ref: '../zoo-api.yaml#/components/responses/PatNotFound'