O endpoint dataLayers fornece informações solares detalhadas para uma região ao redor de um local especificado. O endpoint retorna 17 arquivos TIFF para download, incluindo:
- Modelo de superfície digital (DSM)
- Camada composta RGB (imagens aéreas)
- Uma camada de máscara que identifica os limites da análise
- Fluxo solar anual, ou a produção anual de uma determinada superfície
- Fluxo solar mensal ou a produção mensal de uma determinada superfície
- Sombra por hora (24 horas)
Para mais informações sobre como a API Solar define o fluxo, consulte Conceitos da API Solar.
Sobre as solicitações de camadas de dados
O exemplo a seguir mostra o URL de uma solicitação REST para o método dataLayers:
https://solar.googleapis.com/v1/dataLayers:get?parameters
Inclua os parâmetros do URL da solicitação que especificam o seguinte:
- Coordenadas de latitude e longitude do local
- O raio da região ao redor do local
- O subconjunto de dados a serem retornados (DSM, RGB, máscara, fluxo anual ou fluxo mensal)
- A qualidade mínima permitida nos resultados
- A escala mínima de dados a serem retornados, em metros por pixel
Exemplo de solicitação de camadas de dados
O exemplo a seguir solicita todos os insights de edifícios em um raio de 100 metros para o local nas coordenadas de latitude = 37,4450 e longitude = -122,1390:
Chave de API
Para fazer uma solicitação ao URL na resposta, anexe sua chave de API ao 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"
Também é possível fazer solicitações HTTP colando o URL na solicitação cURL na barra de URL do navegador. A transmissão da chave de API oferece recursos de uso e análise melhores e um controle de acesso melhor aos dados de resposta.
Token OAuth
Observação:esse formato é apenas para um ambiente de teste. Para mais informações, consulte Usar o OAuth.
Para fazer uma solicitação ao URL na resposta, transmita o nome do projeto de faturamento e o 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
Para fazer uma solicitação ao URL na resposta, inclua a chave de API ou o token OAuth na solicitação. O exemplo a seguir usa uma chave de 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;
},
);
}
Campos e tipos de dados são um "type" no TypeScript. Neste exemplo, definimos um tipo personalizado para armazenar os campos de interesse na resposta, como os valores de pixel e a caixa delimitadora de lat/long. É possível incluir mais campos, se quiser.
export interface GeoTiff {
width: number;
height: number;
rasters: Array<number>[];
bounds: Bounds;
}
Definições de tipos de dados
Os seguintes tipos de dados são aceitos:
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;
};
}
A API retorna URLs no seguinte formato:
https://solar.googleapis.com/v1/solar/geoTiff:get?id=HASHED_ID
Esses URLs podem ser usados para acessar arquivos GeoTIFF com os dados solicitados.
Exemplo de resposta
A solicitação produz uma resposta JSON no 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"
}
Acessar dados de resposta
O acesso aos dados por URLs de resposta exige uma autenticação extra. Se você usar uma chave de autenticação, anexe a chave de API ao URL. Se você usa a autenticação OAuth, adicione cabeçalhos OAuth.
Chave de API
Para fazer uma solicitação ao URL na resposta, anexe sua chave de API ao URL:
curl -X GET "https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32&key=YOUR_API_KEY"
Também é possível fazer solicitações HTTP colando o URL na solicitação cURL na barra de URL do navegador. A transmissão da chave de API oferece recursos de uso e análise melhores e um controle de acesso melhor aos dados de resposta.
Token OAuth
Para fazer uma solicitação ao URL na resposta, transmita o nome do projeto de faturamento e o 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
O exemplo a seguir mostra como receber valores de dados de pixel (as informações armazenadas em pixels individuais de uma imagem digital, incluindo valores de cor e outros atributos), calcular a latitude e a longitude do GeoTIFF e armazená-los em um objeto do Typescript.
Para este exemplo específico, permitimos a verificação de tipo, que reduz erros de tipo, aumenta a confiabilidade do código e facilita a manutenção.
// 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,
},
};
}
Com exceção da camada RGB, todos os arquivos TIFF vão aparecer como imagens em branco em aplicativos de visualização de imagens. Para visualizar os arquivos TIFF transferidos por download, importe-os para um software de aplicativo de mapeamento, como o QGIS.
A especificação completa dessa solicitação e resposta está na documentação de referência.