Metadados de imagens do Street View

Introdução

As solicitações de metadados da API Street View Static fornecem dados sobre panoramas do Street View. Usando os metadados, você pode descobrir se uma imagem do Street View está disponível em um determinado local, bem como ter acesso programático às coordenadas de latitude e longitude, ao ID do panorama, à data em que a foto foi tirada e às informações de direitos autorais da imagem. O acesso a esses metadados permite personalizar o comportamento de erros no aplicativo.

Observação : o valor do campo de data pode variar:

• O campo de data pode ter uma granularidade diferente para panoramas diferentes. Por exemplo, o campo de data de alguns panoramas contém um ano e um mês, enquanto outros têm apenas o ano.
• O campo de data é omitido se não houver dados disponíveis.

As solicitações de metadados da API Street View Static estão disponíveis sem cobrança. Nenhuma cota é consumida quando você solicita metadados. A cota só é consumida quando você carrega uma imagem usando a API Street View Static.

Ao fazer solicitações de metadados de imagens do Street View, as imagens panorâmicas têm uma precisão de 50 metros.

Acessar os metadados das imagens

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

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

Observação: o protocolo https:// é obrigatório para solicitações de metadados.

Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&).

Parâmetros obrigatórios para solicitações de metadados

As solicitações de metadados aceitam os mesmos parâmetros de URL que as solicitações de imagens da API Street View Static, embora apenas os seguintes parâmetros sejam 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 separadas por vírgulas (40.457375,-80.009353).

ou:

• pano: um ID de panorama específico. Os panoramas podem mudar de ID com o tempo. Portanto, não mantenha 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 mais detalhes, consulte Atualizar IDs de panoramas excluídos.

Incluindo:

• key e signature: a chave de API é necessária para autenticar a solicitação. A assinatura digital também é obrigatória em alguns casos e sempre recomendada. Para mais informações, consulte Obter uma chave e uma assinatura.

A solicitação de metadados, com apenas os parâmetros obrigatórios, tem esta aparência:

https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=

ou assim:

https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=

Atualizar IDs de panoramas excluídos

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

1. Salve o endereço do local ou as coordenadas de latitude e longitude que você usou para receber um ID de panorama para que possa 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.

Observação: como as imagens do Street View são atualizadas periodicamente e as fotografias podem ser tiradas de posições ligeiramente diferentes a cada vez, um determinado ID de panorama pode ser fixado em um panorama diferente quando as imagens ou o ID de panorama forem atualizados.

Parâmetros opcionais para solicitações de metadados

É possível incluir os seguintes parâmetros na solicitação de metadados: size, heading, fov e pitch. Esses parâmetros não influenciam os dados sobre o panorama ou que panorama é encontrado. A API permite a inclusão dos mesmos parâmetros que a solicitação de imagens para facilitar a construção de uma solicitação de metadados relacionada a uma solicitação de imagens específica. No entanto, para solicitações de metadados, a API ignora os parâmetros opcionais e os valores. Para saber como usar esses parâmetros, consulte o guia para desenvolvedores da API Street View Static.

Formato da resposta

As respostas de metadados são retornadas somente em formato JSON.

Exemplos

Exemplo 1: panorama encontrado

Os URLs a seguir solicitam com sucesso os metadados e a imagem do mesmo panorama.

Solicitação de metadados e resposta

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "copyright" : "© 2017 Google",
   "date" : "2016-05",
   "location" : {
      "lat" : 48.85783227207914,
      "lng" : 2.295226175151347
   },
   "pano_id" : "tu510ie_z4ptBZYo2BGEJg",
   "status" : "OK"
}

Solicitação e resposta de imagens, em que a imagem ausente é esperada.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Nem todas as amostras estão disponíveis na sua região.

Exemplo 2: panorama não encontrado

Os URLs a seguir solicitam os metadados e a imagem de um panorama que não foi encontrado no local especificado ou perto dele.

Solicitação e resposta de metadados

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "status" : "ZERO_RESULTS"
}

Solicitação e resposta de imagens

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Nem todas as amostras estão disponíveis na sua região.

Códigos de status

O campo status no objeto de resposta de metadados contém o status da solicitação e pode conter informações de depuração para ajudar a diagnosticar por que a solicitação do Street View não está funcionando. O campo status pode conter os seguintes valores:

Status	Descrição
"OK"	Indica que nenhum erro ocorreu; foi encontrado um panorama e os metadados são retornados.
"ZERO_RESULTS"	Indica que não foi encontrado um panorama perto do local fornecido. Essa resposta pode ocorrer se você informar um ID de panorama inválido ou inexistente. Consulte [Atualizar IDs de panoramas excluídos](#refresh-pano).
"NOT_FOUND"	Indica que a string de endereço fornecida no parâmetro location não foi encontrada. Essa mensagem pode ocorrer se um endereço inexistente for fornecido.
"OVER_QUERY_LIMIT"	Indica que você excedeu a cota diária ou por segundo para essa API.
"REQUEST_DENIED"	Indica que a solicitação foi negada. Essa mensagem pode ocorrer se você não autorizou sua solicitação ou se a API Street View Static não estiver ativada no projeto do console do Google Cloud que contém sua chave de API.
"INVALID_REQUEST"	Geralmente indica que os parâmetros da consulta (endereço, coordenadas de latitude e longitude ou componentes) estão ausentes.
"UNKNOWN_ERROR"	Indica que a solicitação não foi processada devido a um erro de servidor. Esse problema geralmente é temporário. Se você tentar novamente, a solicitação poderá dar certo.

Mais informações

Para saber mais sobre como usar a API Street View Static ou outros produtos da API Google Maps, consulte a página de suporte das Maps APIs.