# 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](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop).
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](https://developers.google.com/streetview/publish/libraries) if you don't
want to make direct HTTP calls.

### Prerequisites

1. You need a [Google Account](https://www.google.com/accounts/NewAccount) to access the Google API Console, request an API key, and register your application.

2. Create a project in the [Google Developers Console](https://console.developers.google.com) and obtain [authorization credentials](https://console.developers.google.com/apis/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](https://console.cloud.google.com/) and select the project that you just registered.
   2. Visit the [Enabled APIs page](https://console.cloud.google.com/apis/enabled). Make sure that the Google Street View API is on the list of enabled APIs. If it isn't, then [open the API Library](https://console.cloud.google.com/apis/library) and enable the API.
4. Read the [authentication](https://developers.google.com/streetview/publish/authorizing) 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](http://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](https://console.developers.google.com/apis/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](https://developers.google.com/oauthplayground/).
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** .

   > [!NOTE]
   > To obtain the client ID and client secret, go to the [Credentials](https://console.developers.google.com/apis/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 |
   >
   > <br />
   >
   > 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]
> **Caution:** Make sure to read the [Publishing
> acceptance criteria](https://support.google.com/contributionpolicy/answer/7400114) before publishing a photo. Your photos also need the metadata described in [Photo Sphere XMP Metadata](https://developers.google.com/streetview/spherical-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`.