[api] Updated population statistics API after review and test.

paths/population_statistics.yaml

@@ -1,12 +1,10 @@
 get:
   tags:
-    - population
+    - population statistics
   operationId: "populationStatistics"
-  summary: "Get a population count divided by items like age, preferred doctor, etc."
+  summary: "Get a population count"
   description: |-
-    A table with at least two columns. The first column is a category of age, preferred doctor, etc. The second, the number of patients in the category. The category can be extended by several more group by items.
-
-    Patients who are no longer registrered are excluded, so only patients with an active registration are included. Patients without birthdate are excluded (rare).
+    Groups the patient population by any combination of age, preferred doctor, etc. and calculates the count of each category. 
   parameters:
     - name: referenceDate
       in: query
@@ -29,23 +27,25 @@ get:
         - preferredDoctor
         - insurer
         - gender
-        description: "Several items can be added to the group by using a comma separated list, e.g. `groupByItems=gender,age`. If an item is twice or more repeated the first occurance is used. Only known ages are outputted. The insurer is outputted as an Uzovi (with name and concern). The most recent Uzovi table is used to convert codes to names and concerns. The sequence of the items in the URL is the same as the sequence in the grouping of the output."
+        description: "Several items can be added to the group by using a comma separated list, e.g. `groupByItems=gender,age`. If an item is twice or more repeated the first occurrence is used."
     - name: insurer
       in: query
       style: form
       explode: false
+      required: false
       schema: 
         $ref: ../schemas/insurer-Uzovi.yaml
-      description: "Supply zero, one or more Uzovi's to limit the responses to certain insurer. Use 0 to select all patients without insurer registred. Supply the Uzovi code as an integer in a comma separated list, e.g. `insurer=101,211,3344`."
+      description: "Supply zero, one or more Uzovi's to limit the responses to certain insurer. Use 0 to select all patients without insurer registered. Supply the Uzovi code as an integer in a comma separated list, e.g. `insurer=101,211,3344`."
     - name: passerBy
       in: query
+      required: false
       schema: 
         type: boolean
         description: "True to include passer-by patients. This also includes Medicom's noni patients. (Noni = niet op naam ingeschreven.) By default passer-by patients are excluded from the response."
     - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
   responses:
     200:
-      description: "The response body is a JSON-array with for each group, defined by a sequence of `groupByItem` query parameters, an object with a count `n`."
+      description: "The response body is a JSON-array with for each group, defined by a sequence of `groupByItem` query parameters, an object with a count `n`. Only patients with an active registration on the reference date are included. When age is chosen as a category, only patients with a birthdate are included and only known ages are included in the response. The insurer is outputted as an Uzovi (with name and concern). The most recent Uzovi table is used to convert codes to names and concerns. If an Uzovi is missing in that table it is still added to the response, but without name and/or concern. The sequence of the items in the URL is the same as the sequence in the grouping of the output."
       content:
         application/json:
           schema:
@@ -74,4 +74,3 @@ get:
       description: "Indicated practice is known but has not authorized ZOO to share this information with signer."
     404:
       $ref: '../zoo-api.yaml#/components/responses/PatNotFound'
-

paths/population_statistics_deprived.yaml

@@ -1,10 +1,9 @@
 get:
   tags:
-    - population
+    - population statistics
   operationId: "populationStatisticsDeprivedNeighborhood"
-  summary: "Get a deprived neighborhood versus regular count."
-  description: |-
-    Patients who are no longer registrered are excluded, so only patients with an active registration are included. Passer-by and NONI-patients are excluded. Patients without birthdate are excluded (rare).
+  summary: "Patients in a deprived neighborhood"
+  description: "A simple report with a count of all patients living in a deprived neighborhood or regular one based on the well-known postcode table."
   parameters:
     - name: referenceDate
       in: query
@@ -18,7 +17,7 @@ get:
     - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
   responses:
     200:
-      description: "The response body is a JSON-array with exactly two objects."
+      description: "The response body is a JSON-array with exactly three objects. Patients who are no longer registered are excluded from the response, so only patients with an active registration are included. Passer-by and NONI-patients are excluded."
       content:
         application/json:
           schema:
@@ -35,6 +34,12 @@ get:
                     regularNeighborhood:
                       type: number
                       example: 256
+                - type: object
+                  description: "When an irregular postcode is used for a patient it can't be used for determining the neighborhood. These patients are added to unknown."
+                  properties:
+                    unknown:
+                      type: number
+                      example: 3
     400:
       description: "Common HTTP semantics, see the response body."
     401:

zoo-api.yaml

@@ -24,9 +24,9 @@ tags:
     description: |-
       API for retrieving medical dossier data and concerns based on looking up a
       specific patient.
-  - name: population
+  - name: population statistics
     description: |-
-      Population statistics.
+      Statistics of a patient population.
   - name: Quality of Care
     description: |-
       API related to Quality of Care (QoC) features