Anfrage zum Erstellen von Statistiken zu Gebäuden senden

Entwickler im Europäischen Wirtschaftsraum (EWR)

Der Endpunkt buildingInsights liefert Informationen zu Standort, Abmessungen und Solarpotenzial eines Gebäudes. Dabei erhalten Sie insbesondere folgende Informationen:

  • Solarpotenzial, einschließlich Größe der Solarmodule, jährliche Sonneneinstrahlung, Faktoren für die CO₂-Kompensation und mehr
  • Position, Ausrichtung und Energieerzeugung von Solarmodulen
  • Geschätzte monatliche Stromrechnung für das optimale Solarlayout und die damit verbundenen Kosten und Vorteile

Weitere Informationen dazu, wie die Solar API Solarpotenzial und Sonneneinstrahlung definiert, finden Sie unter Solar API-Konzepte.

Mit dem APIs Explorer können Sie Liveanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:

Anfragen zu Gebäudeinformationen

Wenn Sie Gebäudeinformationen anfordern möchten, senden Sie eine HTTP-GET-Anfrage an:

https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY

Geben Sie die Parameter der Anfrage-URL an, die die Breiten- und Längengradkoordinaten des Standorts und die mindestens erforderliche Qualitätsebene für die Ergebnisse enthalten.

Antworten auf Gebäudeinformationen

Die Solar API gibt im Antworttext Informationen zum Standort, zu den Abmessungen und zum Solarpotenzial eines Gebäudes zurück.

Qualität der Bilder

In einigen Fällen kann die angeforderte Bildqualität an einem bestimmten Ort von der verfügbaren Bildqualität abweichen. In solchen Szenarien ist das folgende Verhalten zu erwarten:

Szenario Antwortverhalten
Für einen Ort sind keine Bilder verfügbar, die den
requiredQuality entsprechen.		 Die Solar API gibt den Fehler NOT_FOUND mit dem Statuscode 404 zurück.
In einer Anfrage wird ein bestimmter requiredQuality angegeben, es sind aber nur Daten mit einer höheren Bildqualität verfügbar. Die Solar API gibt die am Standort verfügbaren Daten mit der höchsten Qualität zurück.

Beispiel für eine Building Insights-Anfrage

Im folgenden Beispiel werden Building Insights-Informationen für den Standort mit den Koordinaten „Breitengrad = 37.4450“ und „Längengrad = -122.1390“ angefordert:

API-Schlüssel

Wenn Sie eine Anfrage mit einem API-Schlüssel stellen möchten, geben Sie Ihren API-Schlüssel als Eingabeparameter an:

curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450&location.longitude=-122.1390&requiredQuality=HIGH&key=YOUR_API_KEY"

Sie können HTTP-Anfragen auch stellen, indem Sie die URL in der cURL-Anfrage in die URL-Leiste Ihres Browsers einfügen.

OAuth-Token

Hinweis: Dieses Format ist nur für eine Testumgebung vorgesehen. Weitere Informationen finden Sie unter OAuth verwenden.

Wenn Sie eine Anfrage mit OAuth stellen möchten, übergeben Sie den Namen Ihres Abrechnungsprojekts und Ihr OAuth-Token:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450&location.longitude=-122.1390"

TypeScript

Wenn Sie eine Anfrage mit TypeScript stellen möchten, fügen Sie der Anfrage entweder Ihren API-Schlüssel oder Ihr OAuth-Token hinzu. Im folgenden Beispiel wird ein API-Schlüssel verwendet:

/**
 * Fetches the building insights information from the Solar API.
 *   https://developers.google.com/maps/documentation/solar/building-insights
 *
 * @param  {LatLng} location      Point of interest as latitude longitude.
 * @param  {string} apiKey        Google Cloud API key.
 * @return {Promise<DataLayersResponse>}  Building Insights response.
 */
export async function findClosestBuilding(
  location: google.maps.LatLng,
  apiKey: string,
): Promise<BuildingInsightsResponse> {
  const args = {
    'location.latitude': location.lat().toFixed(5),
    'location.longitude': location.lng().toFixed(5),
    // The Solar API always returns the highest quality imagery available.
    required_quality: 'BASE',
  };
  console.log('GET buildingInsights\n', args);
  const params = new URLSearchParams({ ...args, key: apiKey });
  // https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest
  return fetch(`https://solar.googleapis.com/v1/buildingInsights:findClosest?${params}`).then(
    async (response) => {
      const content = await response.json();
      if (response.status != 200) {
        console.error('findClosestBuilding\n', content);
        throw content;
      }
      console.log('buildingInsightsResponse', content);
      return content;
    },
  );
}

Datentypdefinitionen

Folgende Datentypen werden unterstützt:

export interface DataLayersResponse {
  imageryDate: Date;
  imageryProcessedDate: Date;
  dsmUrl: string;
  rgbUrl: string;
  maskUrl: string;
  annualFluxUrl: string;
  monthlyFluxUrl: string;
  hourlyShadeUrls: string[];
  imageryQuality: 'HIGH' | 'MEDIUM' | 'BASE';
}

export interface Bounds {
  north: number;
  south: number;
  east: number;
  west: number;
}

// https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest
export interface BuildingInsightsResponse {
  name: string;
  center: LatLng;
  boundingBox: LatLngBox;
  imageryDate: Date;
  imageryProcessedDate: Date;
  postalCode: string;
  administrativeArea: string;
  statisticalArea: string;
  regionCode: string;
  solarPotential: SolarPotential;
  imageryQuality: 'HIGH' | 'MEDIUM' | 'BASE';
}

export interface SolarPotential {
  maxArrayPanelsCount: number;
  panelCapacityWatts: number;
  panelHeightMeters: number;
  panelWidthMeters: number;
  panelLifetimeYears: number;
  maxArrayAreaMeters2: number;
  maxSunshineHoursPerYear: number;
  carbonOffsetFactorKgPerMwh: number;
  wholeRoofStats: SizeAndSunshineStats;
  buildingStats: SizeAndSunshineStats;
  roofSegmentStats: RoofSegmentSizeAndSunshineStats[];
  solarPanels: SolarPanel[];
  solarPanelConfigs: SolarPanelConfig[];
  financialAnalyses: object;
}

export interface SizeAndSunshineStats {
  areaMeters2: number;
  sunshineQuantiles: number[];
  groundAreaMeters2: number;
}

export interface RoofSegmentSizeAndSunshineStats {
  pitchDegrees: number;
  azimuthDegrees: number;
  stats: SizeAndSunshineStats;
  center: LatLng;
  boundingBox: LatLngBox;
  planeHeightAtCenterMeters: number;
}

export interface SolarPanel {
  center: LatLng;
  orientation: 'LANDSCAPE' | 'PORTRAIT';
  segmentIndex: number;
  yearlyEnergyDcKwh: number;
}

export interface SolarPanelConfig {
  panelsCount: number;
  yearlyEnergyDcKwh: number;
  roofSegmentSummaries: RoofSegmentSummary[];
}

export interface RoofSegmentSummary {
  pitchDegrees: number;
  azimuthDegrees: number;
  panelsCount: number;
  yearlyEnergyDcKwh: number;
  segmentIndex: number;
}

export interface LatLng {
  latitude: number;
  longitude: number;
}

export interface LatLngBox {
  sw: LatLng;
  ne: LatLng;
}

export interface Date {
  year: number;
  month: number;
  day: number;
}

export interface RequestError {
  error: {
    code: number;
    message: string;
    status: string;
  };
}

Diese Anfrage erzeugt eine JSON-Antwort im folgenden Format:

{
  "name": "buildings/ChIJh0CMPQW7j4ARLrRiVvmg6Vs",
  "center": {
    "latitude": 37.4449439,
    "longitude": -122.13914659999998
  },
  "imageryDate": {
    "year": 2022,
    "month": 8,
    "day": 14
  },
  "postalCode": "94303",
  "administrativeArea": "CA",
  "statisticalArea": "06085511100",
  "regionCode": "US",
  "solarPotential": {
    "maxArrayPanelsCount": 1163,
    "maxArrayAreaMeters2": 1903.5983,
    "maxSunshineHoursPerYear": 1802,
    "carbonOffsetFactorKgPerMwh": 428.9201,
    "wholeRoofStats": {
      "areaMeters2": 2399.3958,
      "sunshineQuantiles": [
        351,
        1396,
        1474,
        1527,
        1555,
        1596,
        1621,
        1640,
        1664,
        1759,
        1864
      ],
      "groundAreaMeters2": 2279.71
    },
    "roofSegmentStats": [
      {
        "pitchDegrees": 11.350553,
        "azimuthDegrees": 269.6291,
        "stats": {
          "areaMeters2": 452.00052,
          "sunshineQuantiles": [
            408,
            1475,
            1546,
            1575,
            1595,
            1606,
            1616,
            1626,
            1635,
            1643,
            1761
          ],
          "groundAreaMeters2": 443.16
        },
        "center": {
          "latitude": 37.444972799999995,
          "longitude": -122.13936369999999
        },
        "boundingBox": {
          "sw": {
            "latitude": 37.444732099999996,
            "longitude": -122.1394224
          },
          "ne": {
            "latitude": 37.4451909,
            "longitude": -122.13929279999999
          }
        },
        "planeHeightAtCenterMeters": 10.7835045
      },
    /.../
    ],
    "solarPanelConfigs": [
      {
        "panelsCount": 4,
        "yearlyEnergyDcKwh": 1819.8662,
        "roofSegmentSummaries": [
          {
            "pitchDegrees": 12.273684,
            "azimuthDegrees": 179.12555,
            "panelsCount": 4,
            "yearlyEnergyDcKwh": 1819.8663,
            "segmentIndex": 1
          }
        ]
      },
      /.../
    ]
   "financialAnalyses": [
      {
        "monthlyBill": {
          "currencyCode": "USD",
          "units": "20"
        },
        "panelConfigIndex": -1
      },
      {
        "monthlyBill": {
          "currencyCode": "USD",
          "units": "25"
        },
        "panelConfigIndex": -1
      },
      {
        "monthlyBill": {
          "currencyCode": "USD",
          "units": "30"
        },
        "panelConfigIndex": -1
      },
      {
        "monthlyBill": {
          "currencyCode": "USD",
          "units": "35"
        },
        "panelConfigIndex": 0,
        "financialDetails": {
          "initialAcKwhPerYear": 1546.8864,
          "remainingLifetimeUtilityBill": {
            "currencyCode": "USD",
            "units": "2563"
          },
          "federalIncentive": {
            "currencyCode": "USD",
            "units": "1483"
          },
          "stateIncentive": {
            "currencyCode": "USD"
          },
          "utilityIncentive": {
            "currencyCode": "USD"
          },
          "lifetimeSrecTotal": {
            "currencyCode": "USD"
          },
          "costOfElectricityWithoutSolar": {
            "currencyCode": "USD",
            "units": "10362"
          },
          "netMeteringAllowed": true,
          "solarPercentage": 86.7469,
          "percentageExportedToGrid": 52.136684
        },
        "leasingSavings": {
          "leasesAllowed": true,
          "leasesSupported": true,
          "annualLeasingCost": {
            "currencyCode": "USD",
            "units": "335",
            "nanos": 85540771
          },
          "savings": {
            "savingsYear1": {
              "currencyCode": "USD",
              "units": "-10"
            },
            "savingsYear20": {
              "currencyCode": "USD",
              "units": "1098"
            },
            "presentValueOfSavingsYear20": {
              "currencyCode": "USD",
              "units": "568",
              "nanos": 380859375
            },
            "financiallyViable": true,
            "savingsLifetime": {
              "currencyCode": "USD",
              "units": "1098"
            },
            "presentValueOfSavingsLifetime": {
              "currencyCode": "USD",
              "units": "568",
              "nanos": 380859375
            }
          }
        },
        "cashPurchaseSavings": {
          "outOfPocketCost": {
            "currencyCode": "USD",
            "units": "5704"
          },
          "upfrontCost": {
            "currencyCode": "USD",
            "units": "4221"
          },
          "rebateValue": {
            "currencyCode": "USD",
            "units": "1483",
            "nanos": 40039063
          },
          "paybackYears": 11.5,
          "savings": {
            "savingsYear1": {
              "currencyCode": "USD",
              "units": "325"
            },
            "savingsYear20": {
              "currencyCode": "USD",
              "units": "7799"
            },
            "presentValueOfSavingsYear20": {
              "currencyCode": "USD",
              "units": "1083",
              "nanos": 500244141
            },
            "financiallyViable": true,
            "savingsLifetime": {
              "currencyCode": "USD",
              "units": "7799"
            },
            "presentValueOfSavingsLifetime": {
              "currencyCode": "USD",
              "units": "1083",
              "nanos": 500244141
            }
          }
        },
        "financedPurchaseSavings": {
          "annualLoanPayment": {
            "currencyCode": "USD",
            "units": "335",
            "nanos": 85540771
          },
          "rebateValue": {
            "currencyCode": "USD"
          },
          "loanInterestRate": 0.05,
          "savings": {
            "savingsYear1": {
              "currencyCode": "USD",
              "units": "-10"
            },
            "savingsYear20": {
              "currencyCode": "USD",
              "units": "1098"
            },
            "presentValueOfSavingsYear20": {
              "currencyCode": "USD",
              "units": "568",
              "nanos": 380859375
            },
            "financiallyViable": true,
            "savingsLifetime": {
              "currencyCode": "USD",
              "units": "1098"
            },
            "presentValueOfSavingsLifetime": {
              "currencyCode": "USD",
              "units": "568",
              "nanos": 380859375
            }
          }
        }
      },
    ],
    /.../
    "panelCapacityWatts": 400,
    "panelHeightMeters": 1.879,
    "panelWidthMeters": 1.045,
    "panelLifetimeYears": 20,
    "buildingStats": {
      "areaMeters2": 2533.1233,
      "sunshineQuantiles": [
        348,
        1376,
        1460,
        1519,
        1550,
        1590,
        1618,
        1638,
        1662,
        1756,
        1864
      ],
      "groundAreaMeters2": 2356.03
    },
    "solarPanels": [
      {
        "center": {
          "latitude": 37.4449659,
          "longitude": -122.139089
        },
        "orientation": "LANDSCAPE",
        "yearlyEnergyDcKwh": 455.40714,
        "segmentIndex": 1
      },
      /.../
    ]
  "imageryQuality": "HIGH",
  "imageryProcessedDate": {
    "year": 2023,
    "month": 8,
    "day": 4
  }
}

Dachsegmente für die Platzierung von Solarmodulen auswählen

In einigen Fällen können Sie bestimmte Dachsegmente für die Platzierung von Solarmodulen auswählen. roofSegmentStats liefert Informationen zur Größe, Ausrichtung und Sonneneinstrahlung eines bestimmten Dachsegments:

"roofSegmentStats": [
      {
        "pitchDegrees": 11.350553,
        "azimuthDegrees": 269.6291,
        "stats": {
          "areaMeters2": 452.00052,
          "sunshineQuantiles": [409.601, 1482.1255, 1553.5117, 1582.7875, 1602.3456, 1613.7804, 1623.6434, 1634.0812, 1642.697, 1651.0267, 1771.4792],
          "groundAreaMeters2": 443.16
        },
        "center": {
          "latitude": 37.4449728,
          "longitude": -122.1393637
        },
        "boundingBox": {
          "sw": {
            "latitude": 37.4447321,
            "longitude": -122.1394224
          },
          "ne": {
            "latitude": 37.4451909,
            "longitude": -122.1392928
          }
        },
        "planeHeightAtCenterMeters": 10.7835045
      },
      {
        "pitchDegrees": 12.273684,
        "azimuthDegrees": 179.12555,
        "stats": {
          "areaMeters2": 309.87268,
          "sunshineQuantiles": [650.5504, 1701.709, 1745.0032, 1768.4081, 1779.1625, 1787.4258, 1794.9333, 1801.3938, 1806.7461, 1814.0724, 1845.8717],
          "groundAreaMeters2": 302.79
        },
        "center": {
          "latitude": 37.4449286,
          "longitude": -122.1389889
        },
        "boundingBox": {
          "sw": {
            "latitude": 37.4448617,
            "longitude": -122.1392095
          },
          "ne": {
            "latitude": 37.444982,
            "longitude": -122.1387809
          }
        },
        "planeHeightAtCenterMeters": 10.67585
      },
      /.../
    ],

Anhand dieser Merkmale können Sie nur die Module auswählen, die auf einem bestimmten Dachsegment platziert sind. Jedes Solarmodul, das über den Endpunkt buildingInsights zurückgegeben wird, enthält einen segmentIndex-Wert, der angibt, auf welchem Dachsegment das Solarmodul platziert ist:

{
        "panelsCount": 142,
        "yearlyEnergyDcKwh": 101170.17,
        "roofSegmentSummaries": [
          {
            "pitchDegrees": 12.273684,
            "azimuthDegrees": 179.12555,
            "panelsCount": 122,
            "yearlyEnergyDcKwh": 87260.48,
            "segmentIndex": 1
          },
          {
            "pitchDegrees": 11.245564,
            "azimuthDegrees": 179.204,
            "panelsCount": 18,
            "yearlyEnergyDcKwh": 12544.052,
            "segmentIndex": 3
          },
          {
            "pitchDegrees": 2.5699794,
            "azimuthDegrees": 86.05642,
            "panelsCount": 1,
            "yearlyEnergyDcKwh": 681.69183,
            "segmentIndex": 10
          },
          {
            "pitchDegrees": 0.10844088,
            "azimuthDegrees": 0,
            "panelsCount": 1,
            "yearlyEnergyDcKwh": 683.9312,
            "segmentIndex": 14
          }
        ]
      },

Wenn Sie Module auf Dachsegmenten mit bestimmten Merkmalen auswählen möchten, können Sie nach segmentIndex filtern. Wenn Sie beispielsweise Solarmodule auf dem nach Süden ausgerichteten Teil des Dachs platzieren möchten, ermitteln Sie, welche Dachsegmente azimuthDegrees-Werte zwischen 90 und 270 haben. Verwenden Sie dann die entsprechenden segmentIndex-Werte, um die vollständige Liste der Solarmodule nach diesen Dachsegmenten zu filtern.

Daten zu erkannten Arrays anfordern

Die Solar API erkennt vorhandene Solaranlagen auf Dächern mithilfe von Satellitenbildern. Informationen zu unterstützten Regionen finden Sie auf der Abdeckungskarte.

Wenn Sie Daten zu erkannten Arrays anfordern möchten, setzen Sie den Parameter additionalInsights im Anfragetext auf DETECTED_ARRAYS:

curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=49.9263&location.longitude=11.5870&additionalInsights=DETECTED_ARRAYS&required_quality=BASE&key=YOUR_API_KEY"

Der Antworttext enthält die folgenden Informationen zu erkannten Arrays:

  • Ob Solaranlagen auf dem Dach des Gebäudes erkannt wurden (detectionStatus).
  • Das Datum der letzten Satellitenbilderfassung, die für die Erkennungen verwendet wurde (latestCaptureDate), falls verfügbar.
  • Eine Liste der erkannten Solaranlagen (arrays). Jede Anlage stellt einen einzelnen zusammenhängenden Bereich von Solarmodulen dar und enthält Folgendes:
    • polygonGeojson: Eine GeoJSON-Darstellung der Dachfläche, auf der Solarmodule erkannt wurden. Die GeoJSON-Daten sind im RFC 7946-Format und stellen ein Polygon für ein einzelnes zusammenhängendes Gebiet dar. Ein Polygon, das Löcher enthält, wird durch mehrere Schleifen dargestellt.

Die Liste arrays wird nur ausgefüllt, wenn detectionStatus den Wert DETECTION_STATUS_ARRAYS_DETECTED hat.

Das folgende Beispiel zeigt eine Antwort für ein Gebäude mit erkannten Arrays (die Antwort ist gekürzt):

{
  "name": "buildings/ChIJ7zV8T9a8oUcRapOpazDCQEE",
  "center": {
    "latitude": 49.9262649,
    "longitude": 11.587273999999999
  },
  "imageryQuality": "HIGH",
  "imageryDate": {
    "year": 2016,
    "month": 6,
    "day": 11
  },
  ...
  "detectedArrays": {
    "detectionStatus": "DETECTION_STATUS_ARRAYS_DETECTED",
    "arrays": [
      {
        "polygonGeojson": {
          "type": "Polygon",
          "coordinates": [
            [
              [11.5873992221349, 49.9262569599232],
              [11.5873991692473, 49.9262899326168],
              [11.5873805103546, 49.9262899153611],
              [11.5873807666599, 49.9262569221221],
              [11.5873992221349, 49.9262569599232]
            ]
          ]
        }
      },
      ...
    ],
    "latestCaptureDate": {
      "year": 2025,
      "month": 5,
      "day": 14
    }
  }
}

Testen!

Mit dem APIs Explorer können Sie Beispielanfragen erstellen, um sich mit der API und den API-Optionen vertraut zu machen.

  1. Wählen Sie rechts auf der Seite das API-Symbol api aus.

  2. Bearbeiten Sie optional die Anfrageparameter.

  3. Wählen Sie den Button Ausführen aus. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.

  4. Wählen Sie im APIs Explorer-Bereich das Vollbildsymbol fullscreen aus, um das APIs Explorer-Fenster zu maximieren.

Weiter
Gebäude suchen