O serviço Place Photo, 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 dá acesso a milhões de fotos armazenadas no banco de dados do Places. Quando você consegue informações de local usando uma solicitação do Place Details, são retornadas referências de fotos para o conteúdo fotográfico relevante. As solicitações do Find Place, Nearby Search e Text Search também retornam uma única referência de foto por local, quando relevante. Com 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 Photo
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 valores possíveis 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
andmaxwidth
properties accept an integer between1
and1600
.You must specify either
maxheight
, ormaxwidth
, or both.
Referências de fotos
Todas as solicitações para o serviço Place Photo precisam incluir um photo_reference
, retornado em resposta a uma solicitação do Find Place, do Nearby Search, do Text Search ou do Place Details. A resposta a essas solicitações vai incluir um campo photos[]
se o lugar tiver conteúdo fotográfico relacionado.
Observação: o número de fotos retornadas varia de acordo com a solicitação.
- Uma solicitação do Find Place, Nearby Search ou Text Search retorna no máximo um elemento
photo
na matriz. - Uma solicitação do Place Details retorna até dez elementos
photo
.
Cada elemento photo
conterá os seguintes campos:
photo_reference
: uma string usada para identificar a foto quando você realiza uma solicitação de foto.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 pode estar vazio.
Fotos retornadas pelo serviço Photo têm origem em vários locais, inclusive de proprietários de empresas e fotos enviadas pelos usuários. Na maioria dos casos, essas
fotos podem ser usadas sem atribuição ou a atribuição necessária vai 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ê exibir a imagem.
Veja abaixo um exemplo de matriz photos[]
.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1"
}
...
Exemplo do Place Photo
Veja abaixo um exemplo de solicitação. Essa solicitação retornará a imagem referenciada, redimensionando-a para que tenha no máximo 400 pixels de largura.
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1 &key=YOUR_API_KEY
Resposta do Place Photo
A resposta de uma solicitação de Place Photo bem-sucedida será uma imagem. O tipo de imagem depende do tipo de foto enviada originalmente.
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:
Se o servidor não entender sua solicitação, ele retornará o status HTTP 400, que indica uma solicitação inválida. Entre os motivos mais comuns para uma solicitação inválida estão:
- A referência da foto enviada não foi especificada corretamente.
- A solicitação não incluiu os parâmetros
maxwidth
oumaxheight
. - O valor do parâmetro
maxwidth
oumaxheight
foi definido comonull
.