L'endpoint dataLayers fornisce informazioni solari dettagliate per una regione che circonda una località specificata. L'endpoint restituisce 17 file TIFF scaricabili, tra cui:
- Modello digitale della superficie (DSM)
- Livello composito RGB (immagini aeree o satellitari)
- Un livello di maschera che identifica i limiti dell'analisi
- Flusso solare annuale o rendimento annuale di una determinata superficie
- Flusso solare mensile o rendimento mensile di una determinata superficie
- Ombra oraria (24 ore)
Per saperne di più su come l'API Solar definisce il flusso, consulta la sezione Concetti dell'API Solar.
Informazioni sulle richieste dei 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 della richiesta che specificano quanto segue:
- Coordinate di latitudine e longitudine della località
- Il raggio della regione che circonda la 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 dei livelli dati
L'esempio seguente richiede tutte le informazioni sugli approfondimenti sugli edifici in un raggio di 100 metri per la località con coordinate di latitudine = 37.4450 e longitudine = -122.1390:
Chiave API
Per inviare 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. Il passaggio della chiave API offre funzionalità di utilizzo e analisi migliori e un controllo dell'accesso migliore ai dati di risposta.
Token OAuth
Nota: questo formato è solo per un ambiente di test. Per ulteriori informazioni, consulta la sezione Utilizza OAuth.
Per inviare una richiesta all'URL nella risposta, inserisci 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 inviare una richiesta all'URL nella risposta, includi la chiave API o il token OAuth nella richiesta. L'esempio seguente utilizza una chiave API chiave:
/** * 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 BASE quality, it won't return anything. // Here we ask for *at least* BASE quality, but if there's a higher quality available, // the Solar API will return us the highest quality available. required_quality: 'BASE', }; 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; }, ); }
I campi e il tipo di dati sono un "tipo" in TypeScript. In questo esempio, definiamo un tipo personalizzato per archiviare i campi di interesse nella risposta, come i valori dei pixel e il riquadro di delimitazione di latitudine/longitudine. Puoi includere altri campi a tuo piacimento.
export interface GeoTiff { width: number; height: number; rasters: Array<number>[]; bounds: Bounds; }
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' | '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; }; }
L'API restituisce gli 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=MmQyMzI0NTMyZDc3YjBjNmQ3OTgyM2ZhNzMyNzk5NjItN2ZjODJlOThkNmQ5ZDdmZDFlNWU3MDY4YWFlMWU0ZGQ6UkdCOkhJR0g=", "rgbUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=NzQwNGQ0NmUyMzAzYWRiNmMxNzMwZTJhN2IxMTc4NDctOTI5YTNkZTlkM2MzYjRiNjE4MGNkODVmNjNiNDhkMzE6UkdCOkhJR0g=", "maskUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=ZTk1YTBlZmY5Y2FhMThlNWYzMWEzZGZhYzEzMGQzOTAtM2Q4NmUyMmM5ZThjZmE0YjhhZWMwN2UzYzdmYmQ3ZjI6TUFTSzpISUdI", "annualFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=OTE0OWIxZDM3NmNlYjkzMWY2YjQyYjY5Y2RkYzNiOTAtZjU5YTVjZGQ3MzE3ZTQ4NTNmN2M4ZmY2MWZlZGZkMzg6QU5OVUFMX0ZMVVg6SElHSA==", "monthlyFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=Y2NhOGRhOWI2MjVmYmNiZTY3Njk4Yjk0MGJhNTk1NDUtY2MyYTI4NDJmN2Q5YTI0MmY2NDQyZGUwZWJkMWQ0ZDg6TU9OVEhMWV9GTFVYOkhJR0g=", "hourlyShadeUrls": [ "https://solar.googleapis.com/v1/geoTiff:get?id=OWFhOTZmNDU2OGQyNTYxYWQ4YjZkYjQ5NWI4Zjg1ODItZGEwNDNhMmM3NDU0MTY2OGIzZDY2OGU1NTY0NTFlMzE6TU9OVEhMWV9GTFVYOkhJR0g=", "https://solar.googleapis.com/v1/geoTiff:get?id=MTI1ZTI2YzM1ZTRlYjA3ZDM4NWE2ODY4MjUzZmIxZTMtNTRmYTI3YmQyYzVjZDcyYjc5ZTlmMTRjZjBmYTk4OTk6TU9OVEhMWV9GTFVYOkhJR0g=", ... ], "imageryQuality": "HIGH" }
Accedere ai dati di risposta
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 inviare 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. Il passaggio della chiave API offre funzionalità di utilizzo e analisi migliori e un controllo dell'accesso migliore ai dati di risposta.
Token OAuth
Per inviare una richiesta all'URL nella risposta, inserisci 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 i valori dei colori 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, aggiunge affidabilità al 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, }, }; }
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 applicazione di mappatura, come QGIS.
La specifica completa di questa richiesta e risposta è disponibile nella documentazione di riferimento.