Fazer suas primeiras chamadas de API

Para concluir as etapas necessárias para fazer chamadas básicas para a API Street View Publish, siga as etapas deste tutorial.

Como fazer chamadas HTTP

É possível chamar a API Street View Publish usando várias ferramentas, como curl, wget e Postman. Na maioria dos casos, você vai querer usar uma linguagem de programação de sua escolha para criar um aplicativo cliente que usa a API, mas este tutorial orientará você nas noções básicas, orientando você nas comandos individuais.

Também fornecemos algumas bibliotecas de cliente caso você não querem fazer chamadas HTTP diretas.

Pré-requisitos

  1. Você precisa de uma Conta do Google para acessar o Console de APIs do Google, solicitar uma chave de API e registrar seu aplicativo.

  2. Crie um projeto no Google Developers Console e receba credenciais de autorização para que seu aplicativo possa enviar solicitações de API.

  3. Depois de criar o projeto, verifique se a API Street View Publish é um dos serviços registrados para uso pelo aplicativo:

    1. Acesse o Console de APIs e selecione o projeto que você acabou de registrar.
    2. Acesse a página de APIs ativadas. Verifique se a API Google Street View está na lista de APIs ativadas. Se não estiver, abra a Biblioteca de APIs e ative-a.

  4. Leia o guia de autenticação para saber como implementar a autorização OAuth 2.0.

  5. Familiarize-se com os conceitos fundamentais do formato de dados JavaScript Object Notation (JSON). JSON é um formato de dados comum e independente de linguagem que fornece uma representação de texto simples de estruturas de dados arbitrárias. Para mais informações, acesse json.org.

Receber uma chave de API

Para fins de autenticação e cota, você precisará usar a API Google Street View Publish com credenciais geradas a partir do Developers Console.

  1. Acesse o menu Credenciais no Developers Console.
  2. Se você já tiver uma chave de API, poderá usar o valor dela. Caso contrário, crie uma nova selecionando Chave de API no menu Novas credenciais.

Adquirir um token de acesso

  1. Acesse o Google Developers OAuth 2.0 Playground.
  2. Clique no menu de configurações (ícone de engrenagem no canto superior direito), marque Usar suas próprias credenciais do OAuth e insira Client ID e Client secret nos campos correspondentes e, em seguida, clique em Fechar.
  3. Na Etapa 1: selecionar e autorizar APIs, insira o escopo da API https://www.googleapis.com/auth/streetviewpublish No campo Insira seus próprios escopos, clique em Autorizar APIs. Um nova página será aberta para confirmar que você deseja autorizar a API.
  4. Clique em Trocar código de autorização dos tokens. Isso preencherá o campo Token de acesso, que conterá o token de acesso a ser usado na para a próxima etapa. O token de acesso expira em 60 minutos. Selecione a opção atualiza o token automaticamente antes de expirar, o que cria um novo token;

Enviar uma solicitação HTTP

Depois de ter a chave de API e o token de acesso, execute o comando a seguir: em um shell para realizar uma chamada HTTP para o serviço. No exemplo abaixo, faça uma chamada para o método /v1/photo:startUpload.

    $ curl --request POST \
    --url 'https://streetviewpublish.googleapis.com/v1/photo:startUpload?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Length: 0'

Exemplos de solicitação

Depois que você se sentir confortável em enviar a solicitação HTTP acima, use algumas métodos. Diversas chamadas são exibidas abaixo.

Recebendo uma lista das suas fotos

    $ curl --request GET \
    --url 'https://streetviewpublish.googleapis.com/v1/photos?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

Carregando uma foto

    $ curl --request GET \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

Como fazer upload de uma foto

Criar uma foto requer três chamadas separadas. A primeira chamada retorna um URL de upload, que é usado na segunda chamada para fazer upload dos bytes de foto. Depois do upload dos bytes da foto, a terceira chamada carrega os metadados da foto e retorna o ID com foto.

  1. Solicitar um URL de upload 
            $ curl --request POST \
        --url 'https://streetviewpublish.googleapis.com/v1/photo:startUpload?key=YOUR_API_KEY' \
        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
        --header 'Content-Length: 0'
  2. Fazer upload dos bytes da foto para o URL de upload 
            $ curl --request POST \
        --url 'UPLOAD_URL' \
        --upload-file 'PATH_TO_FILE' \
        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  3. Fazer upload dos metadados da foto 
            $ curl --request POST \
        --url 'https://streetviewpublish.googleapis.com/v1/photo?key=YOUR_API_KEY' \
        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
        --header 'Content-Type: application/json' \
        --data '{
                  "uploadReference":
                  {
                    "uploadUrl": "UPLOAD_URL"
                  },
                  "pose":
                   {
                     "heading": 105.0,
                     "latLngPair":
                     {
                       "latitude": 46.7512623,
                       "longitude": -121.9376983
                     }
                  },
                  "captureTime":
                  {
                    "seconds": 1483202694
                  },
                }'

Atualizar uma foto

   $ curl --request PUT \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY&updateMask=pose.latLngPair' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
               "pose":
               {
                 "latLngPair":
                 {
                   "latitude": 46.7512624,
                   "longitude": -121.9376982
                 }
               }
             }'

Atualização em lote de várias fotos

   $ curl --request POST \
    --url 'https://streetviewpublish.googleapis.com/v1/photos:batchUpdate?key=YOUR_API_KEY' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
              "updatePhotoRequests": [
                  {
                      "photo": {
                          "photoId": {
                              "id": "FIRST_PHOTO_ID"
                          },
                          "pose": {
                              "latLngPair": {
                                  "latitude": 37.1701638,
                                  "longitude": -122.3624387
                              }
                          }
                      },
                      "updateMask": "pose.latLngPair"
                  },
                  {
                      "photo": {
                          "photoId": {
                              "id": "SECOND_PHOTO_ID"
                          },
                          "pose": {
                              "latLngPair": {
                                  "latitude": 37.1685704,
                                  "longitude": -122.3618021
                              }
                          }
                      },
                      "updateMask": "pose.latLngPair"
                  }
              ]
          }'

Excluir uma foto

    $ curl --request DELETE \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

O que é updateMask?

updateMask é uma maneira de manter suas solicitações pequenas se você quiser atualizar parte da sua foto, e não toda ela. Sem updateMask, a solicitação atualiza o a foto inteira. Isso significa que, se você não definir updateMask e sua solicitação for sem pose, o estado pose da sua foto será apagado. Alguns valores possíveis para updateMask são: places, pose.heading, pose.latlngpair, pose.level, connections. É possível colocar vários valores separados por vírgulas em updateMask.