Esecuzione di una richiesta di livelli dati

L'endpoint dataLayers fornisce informazioni dettagliate sull'energia solare per una regione che circonda una località specificata. L'endpoint restituisce 17 file TIFF scaricabili, tra cui:

• Modello di superficie digitale (DSM)
• Livello composito RGB (immagini aeree)
• Un livello maschera che identifica i limiti dell'analisi
• Il flusso solare annuale o il rendimento annuale di una data superficie
• Flusso solare mensile o rendimento mensile di una data superficie
• Area oraria (24 ore)

Per ulteriori informazioni su come l'API Solar definisce il flusso, consulta i concetti dell'API Solar.

Informazioni sulle richieste di livelli dati

L'esempio seguente mostra l'URL di una richiesta REST al metodo dataLayers:

https://solar.googleapis.com/v1/dataLayers:get?parameters

Includi i parametri dell'URL di richiesta che specificano quanto segue:

• Coordinate di latitudine e longitudine della posizione.
• Il raggio della regione intorno alla località
• Il sottoinsieme dei dati da restituire (DSM, RGB, maschera, flusso annuale o flusso mensile)
• La qualità minima consentita nei risultati
• La scala minima dei dati da restituire, in metri per pixel.

Esempio di richiesta di livelli dati

L'esempio seguente richiede tutte le informazioni di insight sugli edifici in un raggio di 100 metri per la località alle coordinate di latitudine = 37,4450 e longitudine = -122,1390:

Chiave API

Per effettuare una richiesta all'URL nella risposta, aggiungi la chiave API all'URL:

curl -X GET "https://solar.googleapis.com/v1/dataLayers:get?location.latitude=37.4450&location.longitude=-122.1390&radiusMeters=100&view=FULL_LAYERS&requiredQuality=HIGH&exactQualityRequired=true&pixelSizeMeters=0.5&key=YOUR_API_KEY"

Puoi anche effettuare richieste HTTP incollando l'URL nella richiesta cURL nella barra degli URL del browser. La trasmissione della chiave API offre migliori funzionalità di utilizzo e analisi e un migliore controllo dell'accesso ai dati delle risposte.

Token OAuth

Nota:questo formato è destinato solo a un ambiente di test. Per ulteriori informazioni, vedi Utilizzare OAuth.

Per effettuare una richiesta all'URL nella risposta, trasmetti il nome del progetto di fatturazione e il token OAuth:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  "https://solar.googleapis.com/v1/dataLayers:get?location.latitude=37.4450&location.longitude=-122.1390&radius_meters=100&required_quality=HIGH&exactQualityRequired=true"
        

TypeScript

Per effettuare una richiesta all'URL nella risposta, includi la chiave API o il token OAuth nella richiesta. L'esempio seguente utilizza una chiave API:

/**
 * Fetches the data layers information from the Solar API.
 *   https://developers.google.com/maps/documentation/solar/data-layers
 *
 * @param  {LatLng} location      Point of interest as latitude longitude.
 * @param  {number} radiusMeters  Radius of the data layer size in meters.
 * @param  {string} apiKey        Google Cloud API key.
 * @return {Promise<DataLayersResponse>}  Data Layers response.
 */
export async function getDataLayerUrls(
  location: LatLng,
  radiusMeters: number,
  apiKey: string,
): Promise<DataLayersResponse> {
  const args = {
    'location.latitude': location.latitude.toFixed(5),
    'location.longitude': location.longitude.toFixed(5),
    radius_meters: radiusMeters.toString(),
    // The Solar API always returns the highest quality imagery available.
    // By default the API asks for HIGH quality, which means that HIGH quality isn't available,
    // but there is an existing MEDIUM or LOW quality, it won't return anything.
    // Here we ask for *at least* LOW quality, but if there's a higher quality available,
    // the Solar API will return us the highest quality available.
    required_quality: 'LOW',
  };
  console.log('GET dataLayers\n', args);
  const params = new URLSearchParams({ ...args, key: apiKey });
  // https://developers.google.com/maps/documentation/solar/reference/rest/v1/dataLayers/get
  return fetch(`https://solar.googleapis.com/v1/dataLayers:get?${params}`).then(
    async (response) => {
      const content = await response.json();
      if (response.status != 200) {
        console.error('getDataLayerUrls\n', content);
        throw content;
      }
      console.log('dataLayersResponse', content);
      return content;
    },
  );
}
solar.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

I campi e il tipo di dati sono un "type" in TypeScript. In questo esempio, definiamo un tipo personalizzato per archiviare i campi di interesse nella risposta, ad esempio i valori dei pixel e il riquadro di delimitazione latitudine/longitudine. Puoi includere altri campi come preferisci.

export interface GeoTiff {
  width: number;
  height: number;
  rasters: Array<number>[];
  bounds: Bounds;
}
solar.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

Definizioni dei tipi di dati

Sono supportati i seguenti tipi di dati:

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

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' | 'LOW';
}

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;
  };
}
solar.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

L'API restituisce URL nel seguente formato:

https://solar.googleapis.com/v1/solar/geoTiff:get?id=HASHED_ID

Questi URL possono essere utilizzati per accedere ai file GeoTIFF con i dati richiesti.

Esempio di risposta

La richiesta produce una risposta JSON nel formato:

{
  "imageryDate": {
    "year": 2022,
    "month": 4,
    "day": 6
  },
  "imageryProcessedDate": {
    "year": 2023,
    "month": 8,
    "day": 4
  },
  "dsmUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=6d654a0300e454f4c6db7fff24d7ab98-f51261151c9d4c7e055dd21ce57fa3b5",
  "rgbUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=7c71f407a36c1cd051f5ada9c17a6cb8-4b1a9e2b489656febfb7676f205aea1d",
  "maskUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=814470096c53cb221b524119e1e2700c-ac51cf76452dd6c2e843e6b11922ccc0",
  "annualFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=e044991d7f376dc23f9abe8d4efc909b-982983cd98d0572b9d62ca0a2db38eb3",
  "monthlyFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=9b4638db10d2d58560b9f1e9fb013551-dff565175a1e6861a7afb62ece41e218",
  "hourlyShadeUrls": [
    "https://solar.googleapis.com/v1/geoTiff:get?id=9aa96f4568d2561ad8b6db495b8f8582-da043a2c74541668b3d668e556451e31",
    "https://solar.googleapis.com/v1/geoTiff:get?id=125e26c35e4eb07d385a6868253fb1e3-54fa27bd2c5cd72b79e9f14cf0fa9899",
    ...
  ],
  "imageryQuality": "HIGH"
}

Accedi ai dati delle risposte

L'accesso ai dati tramite gli URL di risposta richiede un'autenticazione aggiuntiva. Se utilizzi una chiave di autenticazione, devi aggiungere la chiave API all'URL. Se utilizzi l'autenticazione OAuth, devi aggiungere le intestazioni OAuth.

Chiave API

Per effettuare una richiesta all'URL nella risposta, aggiungi la chiave API all'URL:

curl -X GET "https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32&key=YOUR_API_KEY"

Puoi anche effettuare richieste HTTP incollando l'URL nella richiesta cURL nella barra degli URL del browser. La trasmissione della chiave API offre migliori funzionalità di utilizzo e analisi e un migliore controllo dell'accesso ai dati delle risposte.

Token OAuth

Per effettuare una richiesta all'URL nella risposta, trasmetti il nome del progetto di fatturazione e il token OAuth:

curl -X GET \
-H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
-H "Authorization: Bearer $TOKEN" \
"https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32"
        

TypeScript

L'esempio seguente mostra come ottenere i valori dei dati dei pixel (le informazioni memorizzate nei singoli pixel di un'immagine digitale, inclusi valori di colore e altri attributi), calcolare la latitudine e la longitudine dal GeoTIFF e memorizzarli in un oggetto TypeScript.

Per questo esempio specifico, abbiamo scelto di consentire il controllo dei tipi, che riduce gli errori di tipo, aumenta l'affidabilità del codice e ne semplifica la manutenzione.

// npm install geotiff geotiff-geokeys-to-proj4 proj4

import * as geotiff from 'geotiff';
import * as geokeysToProj4 from 'geotiff-geokeys-to-proj4';
import proj4 from 'proj4';

/**
 * Downloads the pixel values for a Data Layer URL from the Solar API.
 *
 * @param  {string} url        URL from the Data Layers response.
 * @param  {string} apiKey     Google Cloud API key.
 * @return {Promise<GeoTiff>}  Pixel values with shape and lat/lon bounds.
 */
export async function downloadGeoTIFF(url: string, apiKey: string): Promise<GeoTiff> {
  console.log(`Downloading data layer: ${url}`);

  // Include your Google Cloud API key in the Data Layers URL.
  const solarUrl = url.includes('solar.googleapis.com') ? url + `&key=${apiKey}` : url;
  const response = await fetch(solarUrl);
  if (response.status != 200) {
    const error = await response.json();
    console.error(`downloadGeoTIFF failed: ${url}\n`, error);
    throw error;
  }

  // Get the GeoTIFF rasters, which are the pixel values for each band.
  const arrayBuffer = await response.arrayBuffer();
  const tiff = await geotiff.fromArrayBuffer(arrayBuffer);
  const image = await tiff.getImage();
  const rasters = await image.readRasters();

  // Reproject the bounding box into lat/lon coordinates.
  const geoKeys = image.getGeoKeys();
  const projObj = geokeysToProj4.toProj4(geoKeys);
  const projection = proj4(projObj.proj4, 'WGS84');
  const box = image.getBoundingBox();
  const sw = projection.forward({
    x: box[0] * projObj.coordinatesConversionParameters.x,
    y: box[1] * projObj.coordinatesConversionParameters.y,
  });
  const ne = projection.forward({
    x: box[2] * projObj.coordinatesConversionParameters.x,
    y: box[3] * projObj.coordinatesConversionParameters.y,
  });

  return {
    // Width and height of the data layer image in pixels.
    // Used to know the row and column since Javascript
    // stores the values as flat arrays.
    width: rasters.width,
    height: rasters.height,
    // Each raster reprents the pixel values of each band.
    // We convert them from `geotiff.TypedArray`s into plain
    // Javascript arrays to make them easier to process.
    rasters: [...Array(rasters.length).keys()].map((i) =>
      Array.from(rasters[i] as geotiff.TypedArray),
    ),
    // The bounding box as a lat/lon rectangle.
    bounds: {
      north: ne.y,
      south: sw.y,
      east: ne.x,
      west: sw.x,
    },
  };
}
solar.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

Ad eccezione del livello RGB, tutti i file TIFF verranno visualizzati come immagini vuote nelle applicazioni di visualizzazione delle immagini. Per visualizzare i file TIFF scaricati, importali in un software di mappatura, come QGIS.

Le specifiche complete di questa richiesta e risposta sono disponibili nella documentazione di riferimento.

Nota: gli URL di risposta sono attivi solo per un'ora dopo la richiesta iniziale. Per accedere agli URL oltre questo periodo di tempo, devi inviare di nuovo una richiesta all'endpoint del dataLayer.