From 3fff7ce556d78dcf27b76bffc7f29d44d6c9a542 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 01/12] DRYing out the current spec --- service-alerts-api.yaml | 214 +++++++++------------------------------- 1 file changed, 47 insertions(+), 167 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 175e99b..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -19,153 +19,18 @@ tags: description: "Second version of API with AI-generated social media post fields" paths: - /coct-service_alerts-current-unplanned.json: + /coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v0" deprecated: true - summary: Current unplanned outages - description: Get all currently active unplanned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-current-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Current planned outages - description: Get all currently active planned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: All unplanned outages - description: Get all unplanned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: All planned outages - description: Get all planned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-current-unplanned.json: - get: - tags: - - "v1" - summary: Current unplanned outages - description: Get all currently active unplanned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-current-planned.json: - get: - tags: - - "v1" - summary: Current planned outages - description: Get all currently active planned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v1" - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-planned.json: - get: - tags: - - "v1" - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days with social media fields + summary: List service alerts + description: Get all service alerts, according to the parameters set. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -175,27 +40,19 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-all-unplanned.json: - get: - tags: - - "v1" - summary: All unplanned outages - description: Get all unplanned service outages going back several years with social media fields. - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-all-planned.json: + /v1/coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v1" summary: All planned outages description: Get all planned service outages going back several years with social media fields. + deprecated: true + description: Get all service alerts, according to the parameters set with additional social media fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -206,18 +63,15 @@ paths: items: $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alert_id}.json: + /v1/alerts/{alertId}.json: get: tags: - "v1" summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: - - name: alert_id - in: path - description: ID of the service alert to retrieve - required: true - schema: - type: integer + - name: alertId + $ref: '#/components/parameters/alertId' responses: '200': description: Successful response @@ -226,6 +80,32 @@ paths: schema: $ref: '#/components/schemas/ServiceAlertV1' components: + parameters: + timeFrame: + in: path + description: Time frame from which select service alerts will be listed. + schema: + type: string + enum: + - current + - 7days + - all + required: true + planned: + in: path + description: Whether this potential outage was a result of planned maintenance or not. + schema: + type: string + enum: + - planned + - unplanned + required: true + alertId: + in: path + description: ID of the service alert to retrieve + required: true + schema: + type: integer schemas: ServiceAlertV0: type: object @@ -321,9 +201,9 @@ components: properties: tweet_text: type: string - description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B LLM. + description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B or Llama3-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected water outage due to burst pipe. For assistance, use request number 9116664427 when contacting the City." toot_text: type: string - description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B LLM. + description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From f6add174b61f888754e395c1df96476597ed3f37 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 02/12] Adding v1.1 spec to API path --- docs/area_type_lookup.md | 8 +++++ service-alerts-api.yaml | 67 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/area_type_lookup.md diff --git a/docs/area_type_lookup.md b/docs/area_type_lookup.md new file mode 100644 index 0000000..1191618 --- /dev/null +++ b/docs/area_type_lookup.md @@ -0,0 +1,8 @@ +# Area Type Lookup + +This document describes the links between specific `area_type` values, and GIS datasets on the City of Cape Town's Open +Data Portal. + +| Area Type Value | Layer URL | Area Lookup Column | +|----------------------------|-------------------------------------------------------------------------------------|--------------------| +| `Official Planning Suburb` | https://odp-cctegis.opendata.arcgis.com/datasets/cctegis::official-planning-suburbs | `OFC_SBRB_NAME` | \ No newline at end of file diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From aa6cb7f4ece7a9ca82aea5998c9f960c89e3dc97 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 03/12] DRYing out the current spec --- service-alerts-api.yaml | 214 +++++++++------------------------------- 1 file changed, 47 insertions(+), 167 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 175e99b..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -19,153 +19,18 @@ tags: description: "Second version of API with AI-generated social media post fields" paths: - /coct-service_alerts-current-unplanned.json: + /coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v0" deprecated: true - summary: Current unplanned outages - description: Get all currently active unplanned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-current-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Current planned outages - description: Get all currently active planned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: All unplanned outages - description: Get all unplanned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: All planned outages - description: Get all planned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-current-unplanned.json: - get: - tags: - - "v1" - summary: Current unplanned outages - description: Get all currently active unplanned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-current-planned.json: - get: - tags: - - "v1" - summary: Current planned outages - description: Get all currently active planned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v1" - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-planned.json: - get: - tags: - - "v1" - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days with social media fields + summary: List service alerts + description: Get all service alerts, according to the parameters set. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -175,27 +40,19 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-all-unplanned.json: - get: - tags: - - "v1" - summary: All unplanned outages - description: Get all unplanned service outages going back several years with social media fields. - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-all-planned.json: + /v1/coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v1" summary: All planned outages description: Get all planned service outages going back several years with social media fields. + deprecated: true + description: Get all service alerts, according to the parameters set with additional social media fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -206,18 +63,15 @@ paths: items: $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alert_id}.json: + /v1/alerts/{alertId}.json: get: tags: - "v1" summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: - - name: alert_id - in: path - description: ID of the service alert to retrieve - required: true - schema: - type: integer + - name: alertId + $ref: '#/components/parameters/alertId' responses: '200': description: Successful response @@ -226,6 +80,32 @@ paths: schema: $ref: '#/components/schemas/ServiceAlertV1' components: + parameters: + timeFrame: + in: path + description: Time frame from which select service alerts will be listed. + schema: + type: string + enum: + - current + - 7days + - all + required: true + planned: + in: path + description: Whether this potential outage was a result of planned maintenance or not. + schema: + type: string + enum: + - planned + - unplanned + required: true + alertId: + in: path + description: ID of the service alert to retrieve + required: true + schema: + type: integer schemas: ServiceAlertV0: type: object @@ -321,9 +201,9 @@ components: properties: tweet_text: type: string - description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B LLM. + description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B or Llama3-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected water outage due to burst pipe. For assistance, use request number 9116664427 when contacting the City." toot_text: type: string - description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B LLM. + description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From 3cfa5a8bf44528d51b3146bd4aff6569052d8437 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 04/12] Adding v1.1 spec to API path --- docs/area_type_lookup.md | 8 +++++ service-alerts-api.yaml | 67 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/area_type_lookup.md diff --git a/docs/area_type_lookup.md b/docs/area_type_lookup.md new file mode 100644 index 0000000..1191618 --- /dev/null +++ b/docs/area_type_lookup.md @@ -0,0 +1,8 @@ +# Area Type Lookup + +This document describes the links between specific `area_type` values, and GIS datasets on the City of Cape Town's Open +Data Portal. + +| Area Type Value | Layer URL | Area Lookup Column | +|----------------------------|-------------------------------------------------------------------------------------|--------------------| +| `Official Planning Suburb` | https://odp-cctegis.opendata.arcgis.com/datasets/cctegis::official-planning-suburbs | `OFC_SBRB_NAME` | \ No newline at end of file diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From 979d0c81f57351585486a572ad8bf62311952d44 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Wed, 29 May 2024 16:38:42 +0200 Subject: [PATCH 05/12] Aligning spec to current behaviour --- service-alerts-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index dea30bc..dcab320 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -83,7 +83,7 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alertId}.json: + /alerts/{alertId}.json: get: tags: - "v1" From fbd047d33d3b806f5c868baac3a69c85f3194746 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 06/12] DRYing out the current spec --- service-alerts-api.yaml | 214 +++++++++------------------------------- 1 file changed, 47 insertions(+), 167 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 175e99b..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -19,153 +19,18 @@ tags: description: "Second version of API with AI-generated social media post fields" paths: - /coct-service_alerts-current-unplanned.json: + /coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v0" deprecated: true - summary: Current unplanned outages - description: Get all currently active unplanned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-current-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Current planned outages - description: Get all currently active planned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: All unplanned outages - description: Get all unplanned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: All planned outages - description: Get all planned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-current-unplanned.json: - get: - tags: - - "v1" - summary: Current unplanned outages - description: Get all currently active unplanned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-current-planned.json: - get: - tags: - - "v1" - summary: Current planned outages - description: Get all currently active planned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v1" - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-planned.json: - get: - tags: - - "v1" - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days with social media fields + summary: List service alerts + description: Get all service alerts, according to the parameters set. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -175,27 +40,19 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-all-unplanned.json: - get: - tags: - - "v1" - summary: All unplanned outages - description: Get all unplanned service outages going back several years with social media fields. - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-all-planned.json: + /v1/coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v1" summary: All planned outages description: Get all planned service outages going back several years with social media fields. + deprecated: true + description: Get all service alerts, according to the parameters set with additional social media fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -206,18 +63,15 @@ paths: items: $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alert_id}.json: + /v1/alerts/{alertId}.json: get: tags: - "v1" summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: - - name: alert_id - in: path - description: ID of the service alert to retrieve - required: true - schema: - type: integer + - name: alertId + $ref: '#/components/parameters/alertId' responses: '200': description: Successful response @@ -226,6 +80,32 @@ paths: schema: $ref: '#/components/schemas/ServiceAlertV1' components: + parameters: + timeFrame: + in: path + description: Time frame from which select service alerts will be listed. + schema: + type: string + enum: + - current + - 7days + - all + required: true + planned: + in: path + description: Whether this potential outage was a result of planned maintenance or not. + schema: + type: string + enum: + - planned + - unplanned + required: true + alertId: + in: path + description: ID of the service alert to retrieve + required: true + schema: + type: integer schemas: ServiceAlertV0: type: object @@ -321,9 +201,9 @@ components: properties: tweet_text: type: string - description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B LLM. + description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B or Llama3-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected water outage due to burst pipe. For assistance, use request number 9116664427 when contacting the City." toot_text: type: string - description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B LLM. + description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From 97247686f37d16bb44d737228c3d1a48d77a23aa Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 07/12] Adding v1.1 spec to API path --- docs/area_type_lookup.md | 8 +++++ service-alerts-api.yaml | 67 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/area_type_lookup.md diff --git a/docs/area_type_lookup.md b/docs/area_type_lookup.md new file mode 100644 index 0000000..1191618 --- /dev/null +++ b/docs/area_type_lookup.md @@ -0,0 +1,8 @@ +# Area Type Lookup + +This document describes the links between specific `area_type` values, and GIS datasets on the City of Cape Town's Open +Data Portal. + +| Area Type Value | Layer URL | Area Lookup Column | +|----------------------------|-------------------------------------------------------------------------------------|--------------------| +| `Official Planning Suburb` | https://odp-cctegis.opendata.arcgis.com/datasets/cctegis::official-planning-suburbs | `OFC_SBRB_NAME` | \ No newline at end of file diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From 43d74edb9197158c7a353911e0eefb78db7b3ea0 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 08/12] DRYing out the current spec --- service-alerts-api.yaml | 67 +++-------------------------------------- 1 file changed, 5 insertions(+), 62 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index dea30bc..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.1.0 + version: 1.0.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,8 +17,6 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" - - name: "v1.1" - description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -46,8 +44,9 @@ paths: get: tags: - "v1" + summary: All planned outages + description: Get all planned service outages going back several years with social media fields. deprecated: true - summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -63,31 +62,11 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1.1/service-alerts/{timeFrame}/{planned}: - get: - tags: - - "v1.1" - summary: list service alerts - description: Get all service alerts, according to the parameters set with additional geospatial fields. - parameters: - - $ref: '#/components/parameters/timeFrame' - name: timeFrame - - $ref: '#/components/parameters/planned' - name: planned - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' + /v1/alerts/{alert_id}.json: /v1/alerts/{alertId}.json: get: tags: - "v1" - deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -100,22 +79,6 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' - /v1.1/service-alert/{alert_id}: - get: - tags: - - "v1.1" - summary: Get a specific service alert by ID - description: Retrieve detailed information about a service alert by its unique ID - parameters: - - name: alertId - $ref: '#/components/parameters/alertId' - responses: - '200': - description: Successful response - content: - application/json: - schema: - $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -243,24 +206,4 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" - - ServiceAlertV1.1: - allOf: - - $ref: '#/components/schemas/ServiceAlertV1' - - type: object - properties: - area_type: - type: string - nullable: true - description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. - example: "Official Planning Suburb" - enum: - - Official Planning Suburb - - Solid Waste Regional Service Area - - Citywide - - Driving Licence Testing Centre - geospatial_footprint: - type: string - description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. - example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From 2eb6a518aa276f57bd294fcde33f984c8a401b95 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 09/12] Adding v1.1 spec to API path --- service-alerts-api.yaml | 67 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From 5b0ce9f139fdbf8fad49725e850b73d819b807f2 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Wed, 29 May 2024 16:38:42 +0200 Subject: [PATCH 10/12] Aligning spec to current behaviour --- service-alerts-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index dea30bc..dcab320 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -83,7 +83,7 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alertId}.json: + /alerts/{alertId}.json: get: tags: - "v1" From e83f2468590e5b8ddfc20c2998de52c250e14f41 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Fri, 6 Sep 2024 21:46:11 +0200 Subject: [PATCH 11/12] Swapping out 3.5-turbo for 4o-mini --- src/cct_connector/ServiceAlertAugmenter.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/cct_connector/ServiceAlertAugmenter.py b/src/cct_connector/ServiceAlertAugmenter.py index 1f7d7ba..a17e1b9 100644 --- a/src/cct_connector/ServiceAlertAugmenter.py +++ b/src/cct_connector/ServiceAlertAugmenter.py @@ -36,7 +36,7 @@ # Internal LLM consts PRIMARY_GPT_ENDPOINT = "https://api.openai.com/v1/chat/completions" -PRIMARY_DRAFTING_MODEL = "gpt-3.5-turbo-16k" +PRIMARY_DRAFTING_MODEL = "gpt-4o-mini-2024-07-18" FALLBACK_ENDPOINT = "https://datascience.capetown.gov.za/cptgpt-dev/v1/chat/completions" FALLBACK_DRAFTING_MODEL = "llama3-8b-it-q5" DRAFT_LIMIT = 10 @@ -836,10 +836,10 @@ class ServiceAlertAugmenter(ServiceAlertBase.ServiceAlertsBase): def __init__(self, minio_read_name=FIXED_SA_NAME, minio_write_name=AUGMENTED_SA_NAME): super().__init__(None, None, minio_utils.DataClassification.LAKE, minio_read_name=minio_read_name, minio_write_name=minio_write_name, - use_cached_values=True, stage_cache_salt=AUGMENTER_SALT, index_col=ID_COL) + use_cached_values=False, stage_cache_salt=AUGMENTER_SALT, index_col=ID_COL) # all data is reverse sorted - self.data = self.get_data_from_minio().sort_values(by=['publish_date'], ascending=False) + self.data = self.get_data_from_minio().sort_values(by=['publish_date'], ascending=False).head(10) # if there aren't new values, take some undrafted ones from the cache less_than_limit = DRAFT_LIMIT - self.data.shape[0] @@ -1106,5 +1106,5 @@ def _location_generator(): logging.info("...Look[ed] up Image Filenames") logging.info("Wr[iting] to Minio...") - sa_augmenter.write_data_to_minio(sa_augmenter.data) + # sa_augmenter.write_data_to_minio(sa_augmenter.data) logging.info("...Wr[ote] to Minio") From 0e21a02fae1c14681f1ab71a2e868f11ce0d1e8e Mon Sep 17 00:00:00 2001 From: Bradley Kirton Date: Fri, 4 Oct 2024 10:53:34 +0200 Subject: [PATCH 12/12] fix: valid-type errors Binary operator cannot be used in type annotation. Refs: https://mypy.readthedocs.io/en/stable/error_code_list.html#check-validity-of-types-valid-type --- src/cct_connector/ServiceAlertAugmenter.py | 12 ++++++------ src/cct_connector/ServiceAlertEmailer.py | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/cct_connector/ServiceAlertAugmenter.py b/src/cct_connector/ServiceAlertAugmenter.py index a17e1b9..9a5bcce 100644 --- a/src/cct_connector/ServiceAlertAugmenter.py +++ b/src/cct_connector/ServiceAlertAugmenter.py @@ -78,7 +78,7 @@ @functools.lru_cache -def _load_gis_layer(area_type: str, layer_query: str or None = None): +def _load_gis_layer(area_type: str, layer_query: str | None = None): if area_type in AREA_LOOKUP: layer_name, _ = AREA_LOOKUP[area_type] else: @@ -114,7 +114,7 @@ def _get_overture_street_data() -> geopandas.GeoDataFrame: def _geocode_location(address: str, - bounding_polygon: shapely.geometry.base) -> shapely.geometry.base or None: + bounding_polygon: shapely.geometry.base) -> shapely.geometry.base | None: output_shape = None logging.debug(f"Attempting to geocode '{address=}'") @@ -195,7 +195,7 @@ def _geocode_location(address: str, return output_shape -def _cptgpt_location_call_wrapper(location_dict: typing.Dict, http_session: requests.Session) -> typing.List or None: +def _cptgpt_location_call_wrapper(location_dict: typing.Dict, http_session: requests.Session) -> typing.List | None: endpoint = PRIMARY_GPT_ENDPOINT # ToDo move messages to standalone config file params = { @@ -507,7 +507,7 @@ def _cptgpt_location_call_wrapper(location_dict: typing.Dict, http_session: requ def _cptgpt_summarise_call_wrapper(message_dict: typing.Dict, http_session: requests.Session, - max_post_length: int) -> str or None: + max_post_length: int) -> str | None: system_prompt = ( f'Please reason step by step to draft {max_post_length} or less character social media posts about potential ' 'City of Cape Town service outage or update, using the details in provided JSON objects. ' @@ -772,7 +772,7 @@ def _generate_screenshot_of_area(area_gdf: geopandas.GeoDataFrame, area_filename return minio_utils.file_to_minio(local_image_path, AREA_IMAGE_BUCKET) -def _generate_image_link(area_type: str, area: str, location: str or None, wkt_str: str) -> str: +def _generate_image_link(area_type: str, area: str, location: str | None, wkt_str: str) -> str: template_params = dict( salt_str=base64.b64encode(bytes(AREA_IMAGE_SALT, 'utf-8')).decode(), area_type_str=base64.b64encode(bytes(area_type, 'utf-8')).decode(), @@ -944,7 +944,7 @@ def lookup_geospatial_image_link(self): if not image_filename_lookup.empty: self.data[IMAGE_COL] = image_filename_lookup - def infer_area(self, layer_name: str, layer_col: str, data_col_name: str, layer_query: str or None = None): + def infer_area(self, layer_name: str, layer_col: str, data_col_name: str, layer_query: str | None = None): if self.data.empty: logging.warning("No data, so skipping...") return diff --git a/src/cct_connector/ServiceAlertEmailer.py b/src/cct_connector/ServiceAlertEmailer.py index df0c464..8c6342c 100644 --- a/src/cct_connector/ServiceAlertEmailer.py +++ b/src/cct_connector/ServiceAlertEmailer.py @@ -38,9 +38,9 @@ @dataclasses.dataclass class ServiceAlertEmailConfig(ServiceAlertOutputFileConfig): - receivers: typing.Tuple[typing.Tuple[str or None, str], ...] + receivers: typing.Tuple[typing.Tuple[str | None, str], ...] email_focus: str - additional_filter: str or typing.Callable or None + additional_filter: str | typing.Callable | None def apply_additional_filter(self, data_df: pandas.DataFrame) -> pandas.DataFrame: logging.debug(f"( pre-filter) {data_df.shape=}")