Place Photos

Selecione a plataforma: Android iOS JavaScript Web Service

O serviço Place Photo, que faz parte da API Places, é uma API somente leitura que permite adicionar conteúdo fotográfico de alta qualidade ao seu aplicativo. O serviço Place Photo permite acessar milhões de fotos armazenadas no banco de dados do Places. Ao receber informações de local usando uma solicitação de Place Details, referências de fotos serão retornadas para o conteúdo fotográfico relevante. As solicitações de Find Place, Nearby Search e Text Search também retornam uma única referência de foto por local, quando relevante. Usando o serviço Photo, é possível acessar as fotos referenciadas e redimensionar a imagem de acordo com o tamanho ideal para o aplicativo.

Solicitações de Place Photos

Uma solicitação de Place Photo é um URL HTTP no seguinte formato:

https://maps.googleapis.com/maps/api/place/photo?parameters

Certos parâmetros são obrigatórios para iniciar uma solicitação de pesquisa. Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&). A lista de parâmetros e os possíveis valores estão enumerados abaixo.

Required parameters

  • photo_reference

    A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.

  • maxheight or maxwidth

    maxheight specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.

    maxwidth specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.

    Both the maxheight and maxwidth properties accept an integer between 1 and 1600.

    You must specify either maxheight, or maxwidth, or both.

Referências de fotos

Todas as solicitações para o serviço Place Photo precisam incluir um photo_reference, retornado na resposta a uma solicitação de Find Place, Nearby Search, Text Search ou Place Details. A resposta a essas solicitações conterá um campo photos[] se o local tiver conteúdo fotográfico relacionado.

Observação: o número de fotos retornadas varia de acordo com a solicitação.

  • Uma solicitação de Find Place, Nearby Search ou Text Search retorna no máximo um elemento photo na matriz.
  • Uma solicitação de Place Details retorna até dez elementos photo.

Cada elemento photo contém os seguintes campos:

  • photo_reference: uma string usada para identificar a foto ao fazer uma solicitação de Photo.
  • height: a altura máxima da imagem.
  • width: a largura máxima da imagem.
  • html_attributions[]: contém as atribuições necessárias. Esse campo sempre estará presente, mas poderá estar vazio.

As fotos retornadas pelo serviço Photo têm origem em vários locais, inclusive de proprietários de empresas e imagens enviadas pelos usuários. Na maioria dos casos, essas fotos podem ser usadas sem atribuição ou a atribuição necessária será incluída como parte da imagem. No entanto, se o elemento photo retornado incluir um valor no campo html_attributions, será necessário incluir a atribuição adicional no aplicativo sempre que você mostrar a imagem.

.

O exemplo a seguir mostra uma solicitação de detalhes do lugar:

curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"

Confira abaixo um exemplo da matriz photos[] na resposta.

...
"photos" : [
   {
      "html_attributions" : [],
      "height" : 853,
      "width" : 1280,
      "photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
   }
...

Exemplo de Place Photo

Um exemplo de solicitação é mostrado abaixo. Essa solicitação vai retornar a imagem referenciada, redimensionando-a para que ela tenha no máximo 400 pixels de largura.

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q&key=YOUR_API_KEY

Resposta de Place Photo

A resposta de uma solicitação de Place Photo bem-sucedida será uma imagem. O tipo da imagem vai depender do tipo da foto originalmente enviada.

Se a solicitação exceder a cota disponível, o servidor retornará um status HTTP 403 e exibirá a imagem abaixo para indicar que a cota foi excedida:

Imagem de cota excedida

Se o servidor não entender a solicitação, ele vai retornar um status HTTP 400, que indica uma solicitação inválida. Os motivos mais comuns para uma solicitação inválida incluem:

  • A referência da foto enviada não foi especificada corretamente.
  • A solicitação não incluiu os parâmetros maxwidth ou maxheight.
  • O valor do parâmetro maxwidth ou maxheight foi definido como null.
  • O photo_reference expirou. Se photo_reference expirar, faça uma solicitação para Place Details, Find Place, Nearby Search ou Text Search para receber o valor atualizado de photo_reference.