# OpenAPI specification.
# https://oai.github.io/Documentation/start-here.html
openapi: 3.0.3
info:
  title: Bulk Local API
  description: |
    External API for ES client-side use of the bulk local microservice.
  version: '1.0'
servers:
  - url: 'http://127.0.0.1:8100/'
  - url: 'https://int.api.bulklocal.energysage.dev'
  - url: 'https://dev.api.bulklocal.energysage.dev'
  - url: 'https://api.bulklocal.energysage.com'
paths:
  /bulk-local/page/{page_type}:
    parameters:
      - $ref: '#/components/parameters/page_type'
      - name: state
        example: ma
        description: Case-insensitive.
        in: query
        schema:
          type: string
        required: true
      - name: county
        example: suffolk-county
        description: Case-insensitive.
        in: query
        schema:
          type: string
        required: false
      - name: city
        example: boston
        description: Case-insensitive.
        in: query
        schema:
          type: string
        required: false
    get:
      description: |
        Returns all the data for the page of a given type for a specified location, combining LocalContent and page-type-specific data.
      operationId: get-single-page
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
        "400":
          description: "Bad request"
        "404":
          description: "Not found"
  /bulk-local/states/{page_type}:
    parameters:
      - $ref: '#/components/parameters/page_type'
    get:
      description: |
        Returns list of states with state-level data for the given page or content type.
      operationId: get-states-with-data
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
  /bulk-local/{state_slug}/cities:
    parameters:
      - name: state_slug
        in: path
        schema:
          type: string
        required: true
      - name: complete
        in: query
        schema:
          type: string
          enum: [true, false]
        required: false
    get:
      operationId: get-top-cities-for-state
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                type: object
  /bulk-local/solar-suppliers:
    parameters:
      - name: state
        example: ma
        description: Case-insensitive.
        in: query
        schema:
          type: string
        required: true
      - name: county
        example: suffolk-county
        description: Case-insensitive.
        in: query
        schema:
          type: string
        required: false
      - name: city
        example: boston
        description: Case-insensitive.
        in: query
        schema:
          type: string
        required: false
      - name: limit
        in: query
        schema:
          type: integer
        required: false
    get:
      description: |
        Returns list of LocalContentSuppliers for the SolarCompany page for the specified location.
      operationId: get-solar-suppliers-for-loc
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        "400":
          description: "Bad request"
        "404":
          description: "Not found"
  /bulk-local/average-cost:
    parameters:
      - name: state
        in: query
        schema:
          type: string
        required: true
      - name: city
        in: query
        schema:
          type: string
        required: true
    get:
      operationId: get-average-cost
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                type: object
  /:
    get:
      description: Displays Swagger UI for external API endpoints.
      responses:
        "200":
          description: "OK"
          content:
            text/html: {}
  /spec:
    get:
      description: Displays OpenAPI spec for external API endpoints.
      responses:
        "200":
          description: "OK"
          content:
            text/plain: {}
components:
  parameters:
    page_type:
      name: page_type
      description: Case-sensitive. LocalContent is not a page type, but a separate record of data that complements page-type-specific data.
      in: path
      schema:
        type: string
        enum:
          - SolarCompany
          - SolarCost
          - LocalContent
      required: true
  securitySchemes: {}
security:
  - NONE: []