O serviço Place Photo (New) é 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.
Ao conseguir informações de local usando uma solicitação do Place Details, Nearby Search ou Text Search, você também pode solicitar recursos de fotos para conteúdo fotográfico relevante. Com o serviço Photo, é possível acessar as fotos referenciadas e redimensionar a imagem para o tamanho ideal para o aplicativo.
Com o API Explorer, é possível fazer solicitações em tempo real para se familiarizar com a API e as opções dela:
Faça um testeSolicitações de Place Photos
Uma solicitação de Place Photo é uma solicitação HTTP GET para um URL no formato:https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS
Em que os seguintes parâmetros são obrigatórios:
- NAME contém o nome de recurso da foto.
- API_KEY contém a chave de API.
- PARAMETERS contém o parâmetro
maxHeightPx
,maxWidthPx
ou ambos.
A lista completa de parâmetros obrigatórios e opcionais está descrita abaixo.
Parâmetros obrigatórios
Nome da foto
Um identificador de string que identifica uma foto de forma exclusiva. Os nomes das fotos são retornados de uma solicitação de Place Details (novo), Nearby Search (novo) ou Text Search (New) na propriedade name
de cada elemento da matriz photos[]
.
Para ver um exemplo, consulte Usar o nome de uma foto.
maxHeightPx e maxWidthPx
Especifica a altura e a largura máximas desejadas da imagem em pixels. Se a imagem for menor que os valores especificados, a imagem original será retornada. Se a imagem for maior em qualquer uma das dimensões, ela será redimensionada para corresponder à menor das duas dimensões, restrita à proporção original. Ambas as propriedades maxheight e maxwidth aceitam números inteiros entre 1 e 4.800.
É necessário especificar maxHeightPx
, maxWidthPx
ou ambos.
Parâmetros opcionais
skipHttpRedirect
Se for false
(padrão), faça um redirecionamento HTTP para a imagem para retornar a imagem.
Se for true
, pule o redirecionamento e retorne uma resposta JSON contendo a imagem.
Exemplo:
{ "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media", "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo" }
Essa opção é ignorada para solicitações que não são HTTP.
Obter o nome de uma foto
Todas as solicitações para o serviço Place Photo precisam incluir um nome de recurso de foto, retornado na resposta a uma solicitação de Nearby Search, Text Search ou Place Details. A resposta a essas solicitações vai conter uma matriz photos[]
se o local tiver conteúdo fotográfico relacionado.
Cada elemento de photo[]
contém os seguintes campos:
name
: uma string contendo o nome de recurso da foto quando você executa uma solicitação de foto. Essa string está no formato:places/PLACE_ID/photos/PHOTO_RESOURCE
heightPx
: a altura máxima da imagem em pixels.widthPx
: a largura máxima da imagem em pixels.authorAttributions[]
: qualquer atribuição necessária. Este campo está sempre presente, mas pode estar vazio.
Fotos retornadas pelo serviço Photo têm origem em vários locais, incluindo proprietários de empresas e imagens enviadas pelos usuários. Na maioria dos casos, essas
fotos podem ser usadas sem atribuição ou terão a atribuição necessária
incluída como parte da imagem. No entanto, se o elemento photo
retornado
incluir um valor no campo authorAttributions
, será necessário incluir a
atribuição adicional no aplicativo sempre que você exibir a imagem.
O exemplo a seguir mostra uma solicitação do Place Details que inclui photos
na máscara de campo para que a resposta inclua a matriz photos[]
na resposta:
curl -X GET \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,photos" \ https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6EVeja abaixo um exemplo de matriz
photos[]
na resposta.
... "photos" : [ { "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1", "widthPx": 6000, "heightPx": 4000, "authorAttributions": [ { "displayName": "John Smith", "uri": "//maps.google.com/maps/contrib/101563", "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo" } ] }, ...
Solicitar uma foto de lugar
O exemplo de solicitação abaixo retorna uma imagem usando o recurso name
, redimensionando-a para que
ela tenha no máximo 400 pixels de altura e largura:
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY
A resposta de uma solicitação de Place Photo bem-sucedida é uma imagem. O tipo de imagem depende do tipo da 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. Os motivos mais comuns para uma solicitação inválida incluem:
- O nome da foto enviada não foi especificado corretamente.
- A solicitação não incluiu o parâmetro
maxHeightPx
oumaxWidthPx
. - O valor do parâmetro
maxHeightPx
oumaxWidthtPx
foi definido comonull
. - O
name
expirou. Sename
expirar, faça uma solicitação para Place Details (New), Nearby Search (New) ou Text Search (New) para receber um novoname
.
Confira!
Com a API Explorer, você pode fazer solicitações de amostra para conhecer a API e as opções dela.
Para fazer uma solicitação:
- Selecione o ícone da API, , no lado direito da página.
- Defina o parâmetro
name
como:places/PLACE_ID/photos/PHOTO_RESOURCE/media
- Defina
skipHttpRedirect
comotrue
para que a solicitação retorne uma resposta JSON. Por padrão, a solicitação retorna a imagem, que não pode ser exibida pelo APIs Explorer. - Selecione o botão Executar. No pop-up, escolha a conta que você quer usar para fazer a solicitação.
No painel do APIs Explorer, selecione o ícone de expansão para expandir a janela dele.