api_v1.4/hub_api/docs/openapi-specs.yml

info:
  title: Gamification Swagger - OpenAPI 3.0
  description: NextGen Cities Institute Gamification API
  termsOfService: http://swagger.io/terms/
  contact:
    email: peteryefi@gmail.com
  version: 1.4
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
paths:
  /v1.4/city:
    post:
      tags:
        - city
      summary: Create a city
      operationId: createCity
      description: Create a new city with a file upoload
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                city_file:
                  type: string
                  format: binary
            required: true
      responses:
        '201':
          description: City created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/City'
        '200':
          description: City not created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: City not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: []
  /v1.4/heat-pump/{city_id}:
    post:
      tags:
        - heatpump
      summary: Create a heat pump simulation
      operationId: createHeatpump
      description: heatpump simulation with existing catalog data
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
        - in: path
          name: city_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the city to get
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/HeatPump'
            required: true
      responses:
        '201':
          description: Heatpump simulation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeatPumpRes'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
  /v1.4/city/{city_id}:
    get:
      tags:
        - city
      summary: Get a city
      operationId: getCity
      description: Retrieve a city with a given city ID
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the ID of the application access this API
        - in: path
          name: city_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the city to get
      responses:
        '200':
          description: City created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/City'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: City not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
  /v1.4/user:
    post:
      tags:
        - user
      summary: Create user
      description: This can only be done by the logged in admin.
      operationId: createUser
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
      requestBody:
        description: Created user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          '403':
            description: Forbidden
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '500':
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
    put:
      tags:
        - user
      summary: Update user
      description: This can only be done by the logged in admin.
      operationId: updateUser
      requestBody:
        description: Update user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          '403':
            description: Forbidden
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '500':
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
  /v1.4/user/login:
    post:
      tags:
        - user
      summary: Logs user into the system
      description: ''
      operationId: loginUser
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
            required: true
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginRes'
        '400':
          description: Invalid username/password supplied
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /v1.4/energy-demand/{city_id}:
    get:
      tags:
        - energy-demand
      summary: Get energy demand
      description: Retrieve energy demand data
      operationId: getEnergyDemand
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
        - in: path
          name: city_id
          schema:
            type: integer
            required: true
            description: Numeric ID of the city to get
      responses:
        '200':
          description: Successfully retrieved energy demand data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyDemand'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          '403':
            description: Forbidden
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '500':
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
  /v1.4/construction/{city_id}:
    put:
      tags:
        - construction
      summary: updates a city with building construction
      description: updates a city with building construction
      operationId: updateConstruction
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
        - in: path
          name: city_id
          schema:
            type: integer
            required: true
            description: Numeric ID of the city to get
      requestBody:
        description: creates building construction catalog
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Construction'
          application/xml:
            schema:
              $ref: '#/components/schemas/Construction'
      responses:
        '201':
          description: city updated with building construction successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Construction'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          '403':
            description: Forbidden
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '500':
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
  /v1.4/construction-catalog/entries:
    post:
      tags:
        - construction-catalog
      summary: creates building construction catalog entries
      description: create the construction catalog entries
      operationId: catalogEntries
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
      requestBody:
        description: creates building construction catalog
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConstructionCatalogEntries'
          application/xml:
            schema:
              $ref: '#/components/schemas/ConstructionCatalogEntries'
      responses:
        '201':
          description: Construction catalog entries created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstructionCatalogEntries'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          '403':
            description: Forbidden
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '500':
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
  /v1.4/construction-catalog/entry:
    post:
      tags:
        - construction-catalog
      summary: creates building construction catalog
      description: create the construction catalog of a building
      operationId: catalogEntry
      parameters:
        - in: header
          name: appId
          schema:
            type: string
          required: true
          description: the Id of the application access this API
      requestBody:
        description: creates building construction catalog
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConstructionCatalogEntry'
          application/xml:
            schema:
              $ref: '#/components/schemas/ConstructionCatalogEntry'
      responses:
        '201':
          description: Construction catalog created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstructionCatalogEntry'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          '403':
            description: Forbidden
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
          '500':
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ApiResponse'
      security:
        - BearerAuth: [ ]
components:
  schemas:
    City:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: Montreal
        srs_name:
          type: string
          example: EPSG:26918
        country:
          type: string
          example: ca
        lon:
          type: float
          example: 0.38292983
        lat:
          type: float
          example: 0.92898883
        time_zone:
          type: string
          example: utc
        city_version:
          type: integer
          format: int64
          example: 1
        lower_corner:
          type: array
          items:
            type: float
          example: [610610.7547462888,5035770.347264212,566.5784301757819]
        upper_corner:
          type: array
          items:
            type: float
          example: [610610.7547462888,5035770.347264212,566.5784301757819]
        user:
          type: object
          $ref: '#/components/schemas/User'
        created:
          type: string
          example: 2023-01-15 18:40:54.64877
        updated:
          type: string
          example: 2023-01-15 18:40:54.64877
    HeatPump:
      type: object
      properties:
        StartYear:
          type: integer
          format: int64
          example: 10
        EndYear:
          type: integer
          format: int64
          example: 10
        MaximumHPEnergyInput:
          type: float
          example: 9.8382
        HoursOfStorageAtMaxDemand:
          type: integer
          format: int64
          example: 9
        BuildingSuppTemp:
          type: integer
          format: int64
          example: 40
        TemperatureDifference:
          type: float
          example: 9.8382
        FuelLHV:
          type: float
          example: 9.8382
        FuelPrice:
          type: float
          example: 9.8382
        FuelEF:
          type: integer
          format: int64
          example: 40
        FuelDensity:
          type: float
          example: 9.8382
        HPSupTemp:
          type: float
          example: 9.8382
        HeatPumpType:
          type: string
          example: Water to Water HP
          enum:
            - Water to Water HP
            - Air Source HP
        HeatPumpModel:
          type: string
          example: Water to Water HP
          enum:
            - ClimateMaster 156 kW
            - ClimateMaster 256 kW
            - ClimateMaster 335 kW
            - 012
            - 015
            - 018
            - 023
            - 030
            - 033
            - 037
            - 044
            - 047
            - 057
            - 070
            - 087
            - 097
            - 102
            - 120
            - 130
            - 140
        SimType:
          type: int
          example: 1
          format: int64
        EnergyDemand:
          type: array
          items:
            type: float
            example: [ 610.610, 754.746, 288.338 ]
      required:
        - SimType
        - EnergyDemand
        - HeatPumpModel
        - HeatPumpType
        - FuelEF
        - FuelDensity
        - FuelPrice
        - FuelLHV
        - BuildingSuppTemp
        - TemperatureDifference
        - HoursOfStorageAtMaxDemand
        - MaximumHPEnergyInput
        - StartYear
        - EndYear
    ConstructionCatalogEntry:
      type: object
      properties:
        name:
          type: string
          example: 189.1-2009 Nonres 4B Ext Wall Mass
      required:
        - name
    ConstructionCatalogEntries:
      type: object
      properties:
        category:
          type: string
          example: archetypes
      required:
        - category
    Construction:
      type: object
      properties:
        building_names:
          type: array
          items:
            type: string
            example: ["Dompark"]
        extra_loses_due_to_thermal_bridges:
          type: float
          example: 0.15
        indirect_heated_ratio:
          type: float
          example: 0.15
        infiltration_rate_for_ventilation_system_off:
          type: float
          example: 0.5
        infiltration_rate_for_ventilation_system_on:
          type: float
          example: 0.0
        constructions:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: 189.1-2009 Res 4B Ext Wall Steel-Framed
              type:
                type: string
                example: Wall
              layers:
                type: array
                items:
                  type: object
                  $ref: '#components/schemas/Layers'
      required:
        - building_names
        - extra_loses_due_to_thermal_bridges
        - indirect_heated_ratio
        - infiltration_rate_for_ventilation_system_off
        - infiltration_rate_for_ventilation_system_on
        - constructions
    Layers:
      type: object
      properties:
        name:
          type: string
          example: Layer 1
        thickness:
          type: float
          example: 0.0
        material:
          type: object
          $ref: '#/components/schemas/Material'
    Material:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 12
        name:
          type: string
          example: MAT-SHEAT
        solar_absorptance:
          type: float
          example: 0.7
        thermal_absorptance:
          type: float
          example: 0.9
        visible_absorptance:
          type: float
          example: 0.7
        no_mass:
          type: string
          example: "True"
        thermal_resistance:
          type: float
          example: 0.36256
        conductivity:
          type: string
        density:
          type: string
        specific_heat:
          type: string
      required:
        - id
        - name
        - solar_absorptance
        - thermal_absorptance
        - visible_absorptance
        - no_mass
        - thermal_resistance
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: Peter Yefi
        email:
          type: string
          format: email
          example: peteryefi@gmail.com
        password:
          type: string
          example: 'Hub@183838'
        role:
          type: string
          enum:
            - Admin
            - Hub_Reader
      required:
        - name
        - email
        - password
        - role
    HeatPumpRes:
      type: object
      properties:
        hourly_electricity_demand:
          type: array
          items:
            type: object
        daily_electricity_demand:
          type: array
          items:
            type: object
        monthly_electricity_demand:
          type: array
          items:
            type: object
        daily_fossil_consumption:
          type: array
          items:
            type: object
        monthly_fossil_consumption:
          type: array
          items:
            type: object
    EnergyDemand:
      type: object
      properties:
        heating_demand:
          type: array
          items:
            type: object
        cooling_demand:
          type: array
          items:
            type: object
        lighting_demand:
          type: array
          items:
            type: object
        appliances_demand:
          type: array
          items:
            type: object
    Login:
      type: object
      properties:
        email:
          type: string
          example: peteryefi@gmail.com
        password:
          type: string
          example: 'Hub@183838'
      required:
        - email
        - password
    LoginRes:
      type: object
      properties:
        token:
          type: string
          example: eylskdkdjfkdj67uhbnmkhbn908uyhndh
        user:
          type: object
          $ref: '#/components/schemas/User'
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  requestBodies:
    User:
      description: Pet object that needs to be added to the store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
        application/xml:
          schema:
            $ref: '#/components/schemas/User'
    CityArray:
      description: List of city object
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/City'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT