Place Photos (novo)

Selecione a plataforma: Android iOS Web Service
Desenvolvedores do Espaço Econômico Europeu (EEE)

Introdução

O serviço Place Photos (novo) é uma API somente leitura que permite adicionar conteúdo fotográfico de alta qualidade ao aplicativo. O Place Photos (novo) oferece acesso a milhões de fotos armazenadas no banco de dados do Places.

Quando você recebe informações de um lugar usando uma solicitação do Place Details (novo), Nearby Search (novo) ou Text Search (novo), também é possível solicitar recursos de fotos para conteúdo fotográfico relevante. Usando o Place Photos (novo), é possível acessar as fotos referenciadas e redimensionar a imagem de acordo com o tamanho ideal para o aplicativo.

O APIs Explorer permite fazer solicitações em tempo real para que você possa se familiarizar com a API e as opções dela:

Solicitações do Place Photos (novo)

Uma solicitação do Place Photos (novo) é 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 do recurso da foto.
  • API_KEY contém a chave de API.
  • PARAMETERS contém o parâmetro maxHeightPx, o parâmetro maxWidthPx ou ambos.

A lista completa de parâmetros obrigatórios e opcionais é descrita abaixo.

Parâmetros obrigatórios

Nome da foto

Um identificador de string que identifica uma foto de maneira exclusiva. Os nomes das fotos são retornados de uma solicitação do Place Details (novo), Nearby Search (novo) ou Text Search (novo) na propriedade name de cada elemento da matriz photos[].

Para ver um exemplo, consulte Receber um nome de foto.

maxHeightPx e maxWidthPx

Especifica a altura e a largura máximas pretendidas 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 dimensão, ela será dimensionada para corresponder à menor das duas dimensões, restrita à proporção original. As propriedades maxheight e maxwidth aceitam um número inteiro entre 1 e 4800.

É necessário especificar maxHeightPx, maxWidthPx ou ambos.

Parâmetros opcionais

skipHttpRedirect

Se false (padrão), faça um redirecionamento HTTP para a imagem para retornar a imagem. Se true, pule o redirecionamento e retorne uma resposta JSON contendo os detalhes da 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 não HTTP.

Receber um nome de foto

Todas as solicitações do Place Photos (novo) precisam incluir um nome de recurso de foto , retornado na resposta a uma solicitação do Nearby Search (novo) , Text Search (novo) ou Place Details (novo). A resposta a essas solicitações contém uma matriz photos[] se o lugar tiver conteúdo fotográfico relacionado.

Cada elemento de photo[] contém os seguintes campos:

  • name: uma string que contém o nome do recurso da foto quando você faz 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[]: todas as atribuições necessárias. Esse campo está sempre presente, mas pode estar vazio.

Fotos retornadas pelo Place Photos (novo) 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 vai ser incluída na imagem. No entanto, se o elemento photo retornado incluir um valor no campo authorAttributions, vai ser necessário incluir a atribuição adicional no aplicativo sempre que você mostrar a imagem.

O exemplo a seguir mostra uma solicitação do Place Details (novo) 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/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 Um exemplo de uma matriz photos[] na resposta é mostrado abaixo. 
    ...
    "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 name do recurso, redimensionando-a para que tenha no máximo 400 pixels de altura e largura:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

A resposta de uma solicitação bem-sucedida do Place Photos (novo) é uma imagem.

Códigos de erro

As solicitações do Place Photos (novo) podem retornar os seguintes códigos de erro.

Cota excedida (403)

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

Notificação de cota excedida

Solicitação inválida (404)

Se o servidor não conseguir 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 especificado.
  • A solicitação não incluiu o maxHeightPx ou o maxWidthPx parâmetro.
  • O valor do maxHeightPx ou o parâmetro maxWidthtPx foi definido como null.
  • O name expirou. Se name expirar, faça uma solicitação do Place Details (novo), Nearby Search (novo) ou Text Search (novo) para receber um novo name.

Muitos pedidos (429)

O Google recomenda carregar fotos sob demanda. Se você tentar mostrar todas as imagens de um lugar de uma só vez, o servidor poderá retornar um status HTTP 429 indicando que muitas fotos estão sendo carregadas ao mesmo tempo. Se você receber essa mensagem de erro, entre em contato com o suporte e solicite um aumento de cota.

Faça um teste

O APIs Explorer permite fazer solicitações de amostra para que você possa se familiarizar com a API e as opções dela.

Para fazer uma solicitação:

  1. Selecione o ícone da API no lado direito da página.
  2. Defina o parâmetro name como: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Defina skipHttpRedirect como true para que a solicitação retorne uma resposta JSON response. Por padrão, a solicitação retorna a imagem, que não pode ser mostrada pelo APIs Explorer.
  4. Selecione o botão Executar. Na caixa de diálogo, escolha a conta que você quer usar para fazer a solicitação.

  5. No painel do APIs Explorer, selecione o ícone de tela cheia para expandir a janela do APIs Explorer.