Make your first API calls

To complete the steps required to make basic calls to the Street View Publish API, follow the steps in this tutorial.

Making HTTP calls

The Street View Publish API can be called using multiple tools such as curl, wget, and Postman. In most cases, you will want to use a programming language of your choice to build a client application that uses the API, but this tutorial will walk you through the basics by guiding you through the individual commands.

We also provide some client libraries if you don't want to make direct HTTP calls.

Prerequisites

1. You need a Google Account to access the Google API Console, request an API key, and register your application.

2. Create a project in the Google Developers Console and obtain authorization credentials so your application can submit API requests.

3. After creating your project, make sure the Street View Publish API is one of the services that your application is registered to use:

   1. Go to the API Console and select the project that you just registered.
   2. Visit the Enabled APIs page. Make sure that the Google Street View API is on the list of enabled APIs. If it isn't, then open the API Library and enable the API.

4. Read the authentication guide to learn how to implement OAuth 2.0 authorization.

5. Familiarize yourself with the core concepts of the JavaScript Object Notation (JSON) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.

Obtain an API key

For authentication and quota purposes, you will need to use the Google Street View Publish API with credentials generated from your Developers Console.

1. Navigate to the Credentials page in your Developers Console.
2. If you already have an API key, you can use the value from it. Otherwise, create a new one by selecting API key from the New credentials menu.

Obtain an access token

1. Navigate to the Google Developers OAuth 2.0 Playground.
2. Click the settings menu (gear icon on the top right), check Use your own OAuth credentials and input your Client ID and Client secret in the corresponding fields, and then click Close.
   To obtain the client ID and client secret, go to the Credentials page in your Developers Console. If you do not have an existing OAuth 2.0 client, create a new OAuth 2.0 client ID by selecting OAuth client ID under the Create credentials menu and use the following configuration:

   Field	Value
   Application type	Web application
   Name	(any value)
   Restrictions: Authorized JavaScript origins	(empty)
   Restrictions: Authorized redirect URIs	https://developers.google.com/oauthplayground

   
   Click create. The client ID and client secret will be provided to you.
3. Under Step 1: Select & authorize APIs, input the API scope https://www.googleapis.com/auth/streetviewpublish in the Input your own scopes field, then click Authorize APIs. A new page will open to confirm that you want to authorize the API.
4. Click Exchange authorization code for tokens. This will populate the Access token field, which will contain your access token to be used in the next step. The access token expires in 60 minutes. You can select the option to auto-refresh the token before it expires, which will create a new token.

Send an HTTP request

After you have your API key and access token, you can run the following command on a shell to perform an HTTP call to the service. In the example below, we make a call to the /v1/photo:startUpload method.

    $ 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'
  

Sample requests

After you are comfortable with sending the HTTP request above, try using some additional methods. A variety of calls are displayed below.

Getting a list of your photos

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

Getting a photo

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

Uploading a photo

Creating a photo requires three separate calls. The first call will return an upload URL, which is used in the second call to upload the photo bytes. After the photo bytes are uploaded, the third call uploads the metadata of the photo and returns the photo ID.

Caution: Make sure to read the Publishing acceptance criteria before publishing a photo. Your photos also need the metadata described in Photo Sphere XMP Metadata to be published.

1. Request an Upload URL

           $ 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. Upload the photo bytes to the Upload URL

           $ curl --request POST \
           --url 'UPLOAD_URL' \
           --upload-file 'PATH_TO_FILE' \
           --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
         

3. Upload the metadata of the photo

           $ 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
                     },
                   }'
         

Updating a photo

   $ 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
                 }
               }
             }'
  

Batch updating multiple photos

   $ 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"
                  }
              ]
          }'
  

Deleting a photo

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

What is updateMask?

updateMask is a way for you to keep your requests small if you want to update part of your photo instead of all of it. Without updateMask, your request updates the entire photo. This means that if you don't set updateMask and your request is missing pose, your photo's pose will be cleared. Some possible values for updateMask are: places, pose.heading, pose.latlngpair, pose.level, connections. You can put multiple comma-delimited values in updateMask.