{
  "openapi": "3.0.1",
  "info": {
    "title": "EnergySage Scraper: Solar Installers, Reviews & Solar Costs",
    "description": "Scrape EnergySage: a US solar installers list with rating, tier, phone, email, website, services, licenses and certifications; customer reviews with sub-ratings; and solar cost per watt, system price and payback for 50 states and 4,882 cities. No login, no API key.",
    "version": "0.1",
    "x-build-id": "okFqg26h3gRbgwWYC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/oswaldocarabano~energysage-solar-installers-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-oswaldocarabano-energysage-solar-installers-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/oswaldocarabano~energysage-solar-installers-scraper/runs": {
      "post": {
        "operationId": "runs-sync-oswaldocarabano-energysage-solar-installers-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/oswaldocarabano~energysage-solar-installers-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-oswaldocarabano-energysage-solar-installers-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "outputType": {
            "title": "What to extract",
            "enum": [
              "installers",
              "locations",
              "reviews"
            ],
            "type": "string",
            "description": "One row type per run. Installers: every EnergySage-listed solar installer of the chosen states or cities, with rating, review count, EnergySage tier, year established and headquarters (add the full profile below for phone, email, website, services, licenses, certifications and more). Locations: local solar cost data for each state and city page (cost per watt, average system size and price, payback years, lifetime savings) plus the ranked installers of that location. Reviews: customer reviews of the installers, with the four sub-ratings and the installer's reply.",
            "default": "installers"
          },
          "states": {
            "title": "States",
            "type": "array",
            "description": "US state codes or names, e.g. CA, TX, New York. Each state page lists ALL EnergySage installers active in that state (measured: 50 state pages, 200 unique installers nationwide on 23 Sep 2026). Leave states, cities and installer URLs all empty to get California, Texas and Florida. Alaska has no EnergySage page.",
            "items": {
              "type": "string"
            }
          },
          "cities": {
            "title": "Cities",
            "type": "array",
            "description": "Optional. \"City, ST\" (e.g. \"Berkeley, CA\") or an EnergySage solar-companies city URL. 4,882 city pages exist. For installers, a city returns the installers that serve it (a subset of its state); for locations, the city's own solar cost data.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "includeCityPages": {
            "title": "Include every city of the chosen states (locations only)",
            "type": "boolean",
            "description": "Locations output only: also read every city page of each chosen state (California alone has 566). Off returns just the state pages. Installers do not need it: the state page already lists every installer of the state.",
            "default": true
          },
          "installerUrls": {
            "title": "Installer profile URLs or IDs",
            "type": "array",
            "description": "Optional. EnergySage installer profile URLs (https://www.energysage.com/supplier/23948/next-solar/) or bare IDs. Installers output: returns the full profile of each. Reviews output: returns their reviews.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "scrapeDetails": {
            "title": "Add the full installer profile",
            "type": "boolean",
            "description": "Installers output only: open each installer's profile page and add phone (99.0 % filled), email (96.5 %), website (99.5 %), badge, services, product manufacturers, financing partners, licenses, insurance, certifications, workmanship warranty, the four sub-ratings, other locations and states served (fill rates measured on all 200 installers). One extra request per installer, read at about one every 1.5 seconds, and billed as a separate event.",
            "default": false
          },
          "source": {
            "title": "Installer source",
            "enum": [
              "locations",
              "directory"
            ],
            "type": "string",
            "description": "Where the installer list comes from. Location pages (default): the 200 installers EnergySage ranks on its state and city pages, with tier, rating and review count — fast. Full directory: every supplier profile in EnergySage's directory (6,822 profiles, of which about 39 % offer installation), read one profile at a time at about 40 per minute; always includes the full profile. Use the state filter to keep profiles serving those states.",
            "default": "locations"
          },
          "onlyInstallers": {
            "title": "Directory: installers only",
            "type": "boolean",
            "description": "Full directory source only: keep just the profiles that list \"Installation\" among their services (measured 13 of 33 sampled directory profiles). Turn off to also get manufacturers, lenders and other suppliers.",
            "default": true
          },
          "maxReviewsPerInstaller": {
            "title": "Max reviews per installer",
            "minimum": 0,
            "type": "integer",
            "description": "Reviews output only. EnergySage serves reviews 12 at a time; 0 means all of them (the largest installer has over 500).",
            "default": 24
          },
          "maxResults": {
            "title": "Max rows",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Hard cap on delivered rows of the chosen type. Rows are charged one by one as they are delivered, never error rows or duplicates.",
            "default": 50
          },
          "maxConcurrency": {
            "title": "Parallel location pages",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "How many location pages are read at once (they are served from a cache and were measured clean at 2 per second). Profiles and reviews are always read one at a time, because EnergySage slows down clients that open them in parallel.",
            "default": 4
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Not needed: EnergySage answered every measured request directly. Only used as a fallback if the site starts refusing requests.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}