Blocos do Street View

Os blocos do Street View são semelhantes aos blocos 2D, mas contêm imagens panorâmicas tiradas no nível da rua. Com o Street View, você pode explorar pontos turísticos do mundo, conferir maravilhas naturais e entrar em lugares como museus, arenas, restaurantes ou pequenas empresas. Esse endpoint da API dá acesso a:

• Blocos do Street View do Google Maps
• Metadados do Street View
• Miniaturas do Street View

É possível unir blocos de imagens tirados do nível da rua para criar um efeito panorâmico real. Você pode consultar até 100 IDs de panorama para um conjunto de locais (como um trajeto) e receber metadados mais detalhados sobre a posição da câmera.

É necessário um visualizador para unir os blocos do Street View. Por exemplo, o visualizador de panoramas personalizados do Street View.

Depois de ter uma chave de API, você pode acessar as imagens do Street View seguindo as etapas abaixo.

1. Receba um token de sessão. Defina o valor de mapType como streetview.

2. Use o token de sessão para pegar o identificador do panorama (panoId) de um ou mais locais geográficos.

3. Use os identificadores de panorama da resposta de pesquisa de panoId para receber:

   1. Metadados do Street View. Também é possível receber metadados da Street View transmitindo um conjunto de coordenadas e um raio.

   2. Miniaturas do Street View.

   3. Blocos do Street View.

Métodos do Street View

É possível acessar as imagens e os metadados do Street View chamando um dos quatro métodos a seguir.

Pesquisa de panoIds do Street View

É possível encontrar o identificador de panorama de um ou mais locais geográficos transmitindo as coordenadas deles (lat, lng) para o método panoIds. O corpo da solicitação é um objeto JSON que contém uma matriz locations e, opcionalmente, uma radius, conforme mostrado no exemplo de código JSON abaixo.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations

A matriz locations precisa conter pelo menos um conjunto de valores de coordenadas, mas é possível incluir mais, até um máximo de 100.

radius

O valor radius (medido em metros) define o raio do círculo em torno do local em que você quer pesquisar panoramas. O valor padrão é 50 metros.

Resposta do PanoId

A API Map Tiles tenta encontrar o panorama mais próximo de cada local e, em seguida, retorna os IDs dos panoramas. Uma solicitação panoIds bem-sucedida retorna um objeto JSON que contém uma matriz panoIds. A matriz contém uma lista de IDs de panorama, na ordem em que você os solicitou. Se a API Map Tiles não encontrar panoramas para os locais solicitados, uma string vazia será retornada nesse local na matriz. Confira um exemplo no código JSON abaixo.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

Você pode usar panoIds para:

• Solicitar metadados do Street View
• Solicitar miniaturas do Street View
• Solicitar blocos do Street View

Metadados do Street View

As solicitações de metadados do Street View recuperam informações sobre panoramas. Uma solicitação de metadados do Street View é uma solicitação GET HTTPS. É possível recuperar informações sobre panoramas de duas maneiras:

• Se você transmitir um pano_id, a API Map Tiles vai retornar os metadados desse panorama.

• No entanto, se você transmitir um lat e um lng, a API Map Tiles vai retornar os metadados do panorama mais próximo dentro do raio de pesquisa fornecido.

Transmitir um conjunto de coordenadas e um raio

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

Como os IDs de panorama são temporários, recomendamos que você transmita um conjunto de coordenadas e um valor radius na solicitação inicial de metadados do Street View. Confira um exemplo no snippet de código abaixo.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

Transmitir o panoId de uma imagem do Street View

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Resposta de metadados

O código JSON a seguir é um exemplo de resposta de metadados típica.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

A lista a seguir contém definições dos campos no corpo da resposta.

panoId

O ID exclusivo desse panorama. Não confie em IDs do Panorama que sejam válidos por mais tempo do que uma sessão de usuário única.

lat, lng

As coordenadas (latitude e longitude) do panorama. Esses valores podem ser diferentes das coordenadas transmitidas na solicitação, porque o local se encaixa no panorama mais próximo.

imageHeight, imageWidth

As dimensões da imagem panorâmica costurada.

tileHeight, tileWidth

As dimensões de um único bloco de panorama.

heading

A direção da bússola, medida em graus no sentido horário a partir do Norte. Os rumos são retornados no intervalo [0,360], com 0 representando o norte.

tilt

A inclinação do panorama, medida em graus do pólo sul do panorama até o horizonte. Os valores retornados estão no intervalo [0, 180]. Um valor de 90 graus indica que o horizonte já está alinhado no equador do panorama.

roll

A rotação no sentido horário em torno da linha de visão que foi aplicada ao panorama para nivelar o horizonte. Os valores retornados estão no intervalo [0, 360].

imageryType

Indica o tipo de imagem. Os valores válidos são indoor e outdoor.

date

A data em que a imagem foi tirada. Nem todas as imagens têm dados de data. Mas, quando disponível, esse campo contém uma combinação do ano (AAAA) e do mês (MM). Por exemplo: 2023-05 ou 2024.

copyright

O texto de direitos autorais que você precisa mostrar como atribuição junto com a imagem do Street View.

reportProblemLink

Um hiperlink para que os usuários usem para informar problemas com esse bloco do Street View. Esse hiperlink precisa ser exibido no canto inferior direito da imagem e incluir um texto de link, como "Informar um problema com esta imagem".

addressComponent

Um Geocode estruturado que contém detalhes sobre o endereço do panorama. Para mais informações, consulte Solicitações e respostas de geocodificação na documentação da API Geocoding.

links

Uma lista de IDs de panoramas vinculados a este. Também contém o título em que o link é encontrado. Por exemplo, se a direção for 180°, o panorama vinculado vai estar ao sul do panorama atual. Devido à natureza transitória dos IDs de panorama, não confie neles para mais de uma sessão de usuário.

Miniaturas do Street View

Você pode solicitar imagens do Street View no formato thumbnail. As miniaturas são imagens não em blocos com tamanho, título, inclinação e campo de visão definidos pelo usuário. As imagens de miniatura têm uma resolução menor que os blocos e são menores em tamanho de arquivo. Para fazer uma solicitação de miniatura, envie uma solicitação GET para o endpoint thumbnail, conforme demonstrado no protótipo de código abaixo.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

Considere o exemplo de código abaixo, que faz o download de uma miniatura de imagens do Street View tiradas em Whistler, no Canadá.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

Parâmetros obrigatórios

panoId

O ID exclusivo da miniatura que você quer. É possível receber valores de ID de panorama do endpoint panoIds ou do endpoint metadata. Ambos aceitam coordenadas geográficas e retornam o panoId apropriado.

session

Um token de sessão válido.

key

Sua chave de API.

Parâmetros opcionais

height

Especifica a altura da miniatura em pixels, variando de 16 pixels a 250 pixels. Se você não especificar uma altura, ela vai ser definida como o valor máximo permitido de 250 pixels. Se você especificar um valor fora do intervalo, a miniatura será ajustada ao valor válido mais próximo.

width

Especifica a largura da miniatura em pixels, variando de 16 pixels a 600 pixels. Se você não especificar uma largura, o padrão será o valor máximo permitido de 600 pixels. Se você especificar um valor fora do intervalo, a miniatura será ajustada ao valor válido mais próximo.

pitch

Especifica o ângulo da câmera ao longo do eixo vertical. Os valores válidos estão no intervalo de -90 a 90 (inclusive). O valor padrão é 0.

yaw

Especifica a direção da câmera ao longo do eixo horizontal. Os valores válidos estão no intervalo de -360 a 360 (inclusive). O valor padrão é 0.

fov

Especifica o campo de visão horizontal, expresso em graus, com um valor máximo de 120. Ao lidar com uma janela de visualização de tamanho fixo, como uma imagem do Street View de um tamanho definido, o campo de visão representa o zoom, em que valores menores especificam um nível mais alto de zoom. O valor padrão é 90.

Blocos de imagens do Street View

Depois de ter um panoId, você pode solicitar um bloco de imagem do Street View. As solicitações de blocos são solicitações GET HTTPS. Veja o exemplo a seguir.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Neste exemplo de código, z é o nível de zoom, e x e y são as coordenadas do bloco do bloco do Street View que você quer. Os níveis de zoom nos panoramas do Street View precisam estar no intervalo [0,5], sendo que 0 representa o campo de visão mais amplo.

Respostas dos blocos do Street View

Uma solicitação de bloco do Street View bem-sucedida retorna uma imagem do formato e tamanho especificados na resposta createSession.

No nível de zoom zero, o panorama inteiro é redimensionado para um bloco de dimensões tileWidth por tileHeight. Como os panoramas são maiores na dimensão x, o bloco vai conter espaço vazio na dimensão y:

No nível de zoom 5, o panorama em tamanho real é usado e dividido em blocos.

Direitos autorais

Você precisa mostrar informações de direitos autorais em todos os panoramas do Street View. A string a ser exibida pode variar entre os panoramas. Para receber as informações de direitos autorais, solicite os metadados do Street View e consulte o campo copyright da resposta. Para mais informações, consulte Atribuições de dados.