service-alerts-api.yaml

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.2.0
  contact:
    name: Gordon Inggs
    email: gordon.inggs@capetown.gov.za
externalDocs:
  description: Code repository
  url: 'https://github.com/cityofcapetown/service-alerts-connector'
servers:
  - description: "Prod endpoint"
    url: https://service-alerts.cct-datascience.xyz
tags:
  - name: "v0"
    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."
  - name: "v1.2"
    description: "Minor increment of third version of API. Adds fields relating to Alert Status."

paths:
  /coct-service_alerts-{timeFrame}-{planned}.json:
    get:
      tags:
        - "v0"
      deprecated: true
      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
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceAlertV0'
  /v1/coct-service_alerts-{timeFrame}-{planned}.json:
    get:
      tags:
        - "v1"
      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'
          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.1/service-alerts/{timeFrame}/{planned}:
    get:
      tags:
        - "v1.1"
      deprecated: true
      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.1'
  /v1.2/service-alerts/{timeFrame}/{planned}:
    get:
      tags:
        - "v1.2"
      summary: list service alerts
      description: Get all service alerts, according to the parameters set with additional status field.
      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.2'
  /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:
        - name: alertId
          $ref: '#/components/parameters/alertId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAlertV1'
  /v1.1/service-alert/{alert_id}:
    get:
      tags:
        - "v1.1"
      deprecated: true
      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'
  /v1.2/service-alert/{alert_id}:
    get:
      tags:
        - "v1.2"
      deprecated: false
      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.2'
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
      properties:
        Id:
          type: integer
          description: Unique identifier for service alert
          example: 23128
        service_area:
          type: string
          description: Type of service affected
          example: "Water & Sanitation"
          enum:
            - Business Queries
            - City Health
            - Creditors Accounts Payable
            - Development Management
            - Drivers Licence Enquiries
            - Economic Development
            - Electricity
            - Events
            - General Documents
            - General enquiries
            - Meter Readings
            - Motor Vehicle Registration
            - Ombudsman
            - Parks
            - Points of Distribution
            - Refuse
            - Revenue
            - Roads & Stormwater
            - Roads & Transport
            - Supply Chain Management
            - Tourism
            - Traffic
            - Valuations
            - Water & Sanitation
            - Water Management
        title:
          type: string
          description: Title of service alert
          example: "Water Off"
        description:
          type: string
          description: More detailed description of nature of outage, and its effects.
          example: "Leak on Main"
        area:
          type: string
          description: High level description of the area affected. Often the suburb.
          example: "Sonkring"
        location:
          type: string
          description: More fine-grained description of the area affected. Often the street address.
          example: "Woudenberg street"
        publish_date:
          type: string
          format: date-time
          description: Date when service alert was created as ISO8601 timestamp. **NB** Uses UTC timestamp.
          example: "2024-02-13T22:00:00.000Z"
        effective_date:
          type: string
          format: date-time
          description: Date when the service alert is applicable as ISO8601 timestamp. **NB** Uses UTC timestamp.
          example: "2024-02-13T22:00:00.000Z"
        expiry_date:
          type: string
          format: date-time
          description: Date when the service alert should stop being considered valid as ISO8601 timestamp. **NB** Uses UTC timestamp.
          example: "2024-02-14T22:00:00.000Z"
        start_timestamp:
          type: string
          format: date-time
          description: Timestamp when the issue that caused the alert started as ISO8601 timestamp. **NB** Uses UTC timestamp.
          example: "2024-02-14T08:04:00.000Z"
        forecast_end_timestamp:
          type: string
          format: date-time
          description: Timestamp by when the issue that caused the alert is expected to be resolved.
          example: "2024-02-14T14:00:00.000Z"
          nullable: true
        planned:
          type: boolean
          description: Whether the issue that caused the alert is part of routine maintenance or unexpected.
          example: false
        request_number:
          type: string
          description: Unique identifier for the service request associated with the issue. Should be cited if contacting the City of Cape Town.
          example: "9116640606"

    ServiceAlertV1:
      allOf:
        - $ref: '#/components/schemas/ServiceAlertV0'
        - type: object
          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 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 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 License Testing Centre
                - Electricity Service Region
                - Water Service Region
            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))"
    ServiceAlertV1.2:
      allOf:
        - $ref: '#/components/schemas/ServiceAlertV1.1'
        - type: object
          properties:
            status:
              type: string
              nullable: false
              description: Current status of the alert, giving an indication of progress towards addressing the issue.
              example: "Open"
              enum:
                - Open
                - Assigned
                - Crew on Site
                - Issue Resolved
                - Closed