From b94dd75998c46ee0e2e93ecd6fc0bb3cd537b138 Mon Sep 17 00:00:00 2001 From: Eric Hoekstra Date: Fri, 12 Apr 2024 15:16:34 +0200 Subject: [PATCH] [api] Updated population statistics API after review and test. --- paths/population_statistics.yaml | 17 ++++++++--------- paths/population_statistics_deprived.yaml | 15 ++++++++++----- zoo-api.yaml | 4 ++-- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/paths/population_statistics.yaml b/paths/population_statistics.yaml index 4a7d68e..a8c432f 100644 --- a/paths/population_statistics.yaml +++ b/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' - diff --git a/paths/population_statistics_deprived.yaml b/paths/population_statistics_deprived.yaml index 6729f2a..030abeb 100644 --- a/paths/population_statistics_deprived.yaml +++ b/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: diff --git a/zoo-api.yaml b/zoo-api.yaml index b64911a..b611678 100644 --- a/zoo-api.yaml +++ b/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