Solicitação e resposta do Street View

Desenvolvedores do Espaço Econômico Europeu (EEE)

Uma solicitação de imagem do Street View é um URL HTTP neste formato:

https://maps.googleapis.com/maps/api/streetview?parameters

A imagem é especificada usando parâmetros de solicitação. Como é padrão em URLs, todos os parâmetros são separados usando o caractere "e" comercial (&). Os parâmetros permitidos e os possíveis valores estão enumerados abaixo.

Parâmetros obrigatórios

Siga uma destas instruções:

  • location pode ser uma string de texto (como Chagrin Falls, OH) ou um par de coordenadas de latitude e longitude (40.457375,-80.009353) e precisa ser codificado em URL. Portanto, converta endereços como "City Hall, New York, NY" para "City+Hall,New+York,NY" antes de enviar a solicitação. A API Street View Static se ajusta à fotografia de panorama mais próxima do local. Quando você fornece uma string de texto de endereço, a API pode usar um local de câmera diferente para mostrar melhor o local especificado. Quando você informa as coordenadas de latitude e longitude, a API pesquisa um raio de 50 metros para encontrar a foto mais próxima do local. Como as imagens do Street View são atualizadas periodicamente e as fotos podem ser tiradas de posições ligeiramente diferentes a cada vez, é possível que seu location se ajuste a um panorama diferente quando as imagens forem atualizadas.

ou:

  • pano é um ID de panorama específico. Os panoramas podem mudar de ID com o tempo, então não persista esse ID. Em vez disso, salve o endereço do local ou as coordenadas de latitude e longitude para atualizar o ID do panorama. Para detalhes, consulte Atualizar IDs de panorama excluídos.

Incluindo:

  • size especifica o tamanho da saída da imagem em pixels. O tamanho é especificado como {width}x{height}. Por exemplo, size=600x400 retorna uma imagem com 600 pixels de largura e 400 de altura.
  • O key permite monitorar o uso da API do aplicativo no console do Google Cloud e garante que o Google possa entrar em contato com você sobre o aplicativo, se necessário. Para mais informações, consulte Receber uma chave e uma assinatura.

Atualizar IDs de panorama excluídos

Se você tentar recuperar um ID de panorama e receber ZERO_RESULTS ou nenhum valor, o ID foi excluído e precisa ser atualizado.

  1. Salve o endereço do local ou as coordenadas de latitude e longitude usadas para receber um ID de panorama e atualizar quando necessário.

  2. Quando você detectar que um ID de panorama mudou, use o endereço do local original ou as coordenadas de latitude e longitude para pesquisar novamente os panoramas mais próximos a esse local e receber um novo ID.

Parâmetros opcionais

  • signature (recomendado) é uma assinatura digital usada para verificar se os sites que geram solicitações usando sua chave de API têm autorização para isso. As solicitações que não incluem uma assinatura digital podem falhar. Para mais informações, consulte Receber uma chave e uma assinatura.

    Observação:para ex-clientes do plano Premium da Plataforma Google Maps, a assinatura digital é obrigatória. Saiba mais sobre os parâmetros de autenticação para clientes do plano Premium.

  • heading indica a bússola da câmera. Os valores aceitos vão de 0 a 360 (ambos indicando "Norte", com 90 indicando "Leste" e 180 "Sul"). Se você não especificar uma posição, um valor será calculado para direcionar a câmera para o location especificado, do ponto em que a fotografia mais próxima foi tirada.
  • fov (o padrão é 90) determina o campo de visão horizontal da imagem expresso em graus, com um valor máximo permitido 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. Números menores indicam um nível de zoom maior.


    Captura de tela de um campo de visão amplo mostrando o teto, as paredes, o chão e uma janela de tanque dentro de um aquário. Captura de tela de um campo de visão de close-up, mostrando detalhes ampliados de uma foto do Street View dentro de um aquário.
    (Esquerda: fov=120; Direita: fov=20)

  • pitch (o padrão é 0) especifica o ângulo para cima ou para baixo da câmera em relação ao veículo do Street View. Com frequência, mas não sempre, é o plano horizontal. Os valores positivos levam o ângulo da câmera para cima (com 90 graus indicando diretamente para cima). Os valores negativos levam o ângulo da câmera para baixo (com -90 indicando diretamente para baixo).
  • radius (o padrão é 50) define um raio, em metros, para procurar um panorama, com o centro na latitude e longitude fornecidas. Os valores válidos são números inteiros não negativos.
  • return_error_code indica se a API precisa retornar um código de erro quando nenhuma imagem é encontrada (404 NOT FOUND) ou em resposta a uma solicitação inválida (400 BAD REQUEST). Os valores válidos são true e false. Se definido como true, uma mensagem de erro será retornada no lugar da imagem cinza genérica. Isso elimina a necessidade de fazer uma chamada separada para verificar a disponibilidade da imagem.
  • source (o padrão é default) limita as pesquisas do Street View às fontes selecionadas. Os valores válidos são:
    • default: usa as fontes padrão do Street View, sem limitar a pesquisa a origens específicas.
    • outdoor: limita as pesquisas a coleções ao ar livre. As coleções internas não são incluídas nos resultados da pesquisa. e pode ser que não existam panoramas externos para o local especificado. A pesquisa só retorna panoramas em que é possível determinar se eles são internos ou externos. Por exemplo, as Fotoesferas não são retornadas porque não se sabe se elas estão em ambientes internos ou externos.

Este é um exemplo de solicitação.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Captura de tela de uma foto de um ponto de vista na rua mostrando trilhos de ferrovia eletrificados.

Nenhuma imagem disponível

Para locais onde as imagens do Street View não estão disponíveis, a API Street View Static retorna uma imagem genérica cinza com o texto "Desculpe, não temos imagens aqui", como mostrado neste exemplo:

Uma captura de tela da imagem genérica exibida quando não há imagens disponíveis para o local especificado. O plano de fundo é marrom-claro e mostra o texto "Sentimos muito, mas não temos imagens daqui".
Figura: imagem genérica exibida quando não há imagens disponíveis para o local especificado.

Mostrar apenas imagens válidas

Para evitar a exibição da imagem genérica e garantir que sua página da Web mostre apenas imagens válidas da API Street View Static, siga estas sugestões:

  • Defina o parâmetro return_error_code como true. Isso faz com que a API Street View Static retorne um erro 404 NOT FOUND em vez da imagem cinza genérica, se nenhuma imagem estiver disponível para o local especificado.
  • Solicite metadados de imagens do Street View para determinar se há imagens disponíveis para o local especificado antes de enviar uma solicitação.