openapi: 3.0.3
info:
  title: Electricity Price Plan Proposal Plugin API
  description: An API that searches for electricity plans based on the conditions of electricity usage at home
  version: 'v1'
servers:
  - url: https://gpt-plugin.enechange.jp
    description: Production server
  - url: https://gpt-plugin-stg.enechange.jp
    description: Staging server
  - url: http://gpt-plugin.local-enechange.jp:8000
    description: Local development server
paths:
  /v1/plans:
    get:
      summary: Retrieve plans
      operationId: retrieve_plans
      parameters:
        - name: size
          in: query
          required: false
          schema:
            type: integer
          description: The size of the plans to retrieve. 1 to 10 or less is expected. No input is required unless specified by the user.
        - name: postcode
          in: query
          required: true
          schema:
            type: string
          description: Postcode of the user address without hyphen. It is expected to consist of 7 numbers. If this input is not present, the API cannot be executed. If "is_moving" is true, this refers to the postcode of the new address for the move; if false, it refers to the postcode of the current address.
        - name: household_size
          in: query
          required: false
          schema:
            type: integer
          description: The size of the household. Default is 3.
        - name: is_moving
          in: query
          required: false
          schema:
            type: boolean
          description: A flag of type boolean that is expected to be true if the user assumes a moving situation and false otherwise. Default is false.
        - name: moving_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: If "is_moving" is true, it is valid. The date you plan to move. Time is not used for processing and is expected to be filled with zeros. Default is after 1 month.
        - name: moving_to_new_construction
          in: query
          required: false
          schema:
            type: boolean
          description: If "is_moving" is true, it is valid. Whether moving to a new building or not. Default is false.
        - name: moving_to_all_electric
          in: query
          required: false
          schema:
            type: boolean
          description: If "is_moving" is true, it is valid. Whether to move into an all-electric home. Default is false.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  plans:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The name of the plan. It includes the name of the company that provides it and the region.
                        url:
                          type: string
                          description: The URL of the plan.
                        saved_yen:
                          type: integer
                          description: The amount of yen saved per year by the plan.
                        saved_yen_description:
                          type: string
                          description: The description of the amount saved by the plan. The text of the calculation basis.
                  current_price_and_conditions:
                    type: string
                    description: The retrieve conditions for the plans and the assumed current electricity plan cost under those conditions. If plans can be retrieved, it will be included in the response. This is a prerequisite for the retrieved plans detail.
                  notes:
                    type: string
                    description: Additional notes.
                  instruction_message:
                    type: string
                    description: Instructional messages for users to improve prompts.
                  error_message:
                    type: string
                    description: Error messages for users to improve prompts.
