// Copyright 2019 Google LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.streetview.publish.v1;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "google/streetview/publish/v1/resources.proto";
import "google/streetview/publish/v1/rpcmessages.proto";

option go_package = "google.golang.org/genproto/googleapis/streetview/publish/v1;publish";
option java_outer_classname = "StreetViewPublish";
option java_package = "com.google.geo.ugc.streetview.publish.v1";

// Definition of the service that backs the Street View Publish API.

// Publishes and connects user-contributed photos on Street View.
service StreetViewPublishService {
  // Creates an upload session to start uploading photo bytes. The method uses
  // the upload URL of the returned
  // [UploadRef][google.streetview.publish.v1.UploadRef] to upload the bytes for
  // the [Photo][google.streetview.publish.v1.Photo].
  //
  // In addition to the photo requirements shown in
  // https://support.google.com/maps/answer/7012050?hl=en&ref_topic=6275604,
  // the photo must meet the following requirements:
  //
  // * Photo Sphere XMP metadata must be included in the photo medadata. See
  // https://developers.google.com/streetview/spherical-metadata for the
  // required fields.
  // * The pixel size of the photo must meet the size requirements listed in
  // https://support.google.com/maps/answer/7012050?hl=en&ref_topic=6275604, and
  // the photo must be a full 360 horizontally.
  //
  // After the upload completes, the method uses
  // [UploadRef][google.streetview.publish.v1.UploadRef] with
  // [CreatePhoto][google.streetview.publish.v1.StreetViewPublishService.CreatePhoto]
  // to create the [Photo][google.streetview.publish.v1.Photo] object entry.
  rpc StartUpload(google.protobuf.Empty) returns (UploadRef) {
    option (google.api.http) = {
      post: "/v1/photo:startUpload"
      body: "*"
    };
  }

  // After the client finishes uploading the photo with the returned
  // [UploadRef][google.streetview.publish.v1.UploadRef],
  // [CreatePhoto][google.streetview.publish.v1.StreetViewPublishService.CreatePhoto]
  // publishes the uploaded [Photo][google.streetview.publish.v1.Photo] to
  // Street View on Google Maps.
  //
  // Currently, the only way to set heading, pitch, and roll in CreatePhoto is
  // through the [Photo Sphere XMP
  // metadata](https://developers.google.com/streetview/spherical-metadata) in
  // the photo bytes. CreatePhoto ignores the `pose.heading`, `pose.pitch`,
  // `pose.roll`, `pose.altitude`, and `pose.level` fields in Pose.
  //
  // This method returns the following error codes:
  //
  // * [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT] if
  // the request is malformed or if the uploaded photo is not a 360 photo.
  // * [google.rpc.Code.NOT_FOUND][google.rpc.Code.NOT_FOUND] if the upload
  // reference does not exist.
  // * [google.rpc.Code.RESOURCE_EXHAUSTED][google.rpc.Code.RESOURCE_EXHAUSTED]
  // if the account has reached the storage limit.
  rpc CreatePhoto(CreatePhotoRequest) returns (Photo) {
    option (google.api.http) = {
      post: "/v1/photo"
      body: "photo"
    };
  }

  // Gets the metadata of the specified
  // [Photo][google.streetview.publish.v1.Photo].
  //
  // This method returns the following error codes:
  //
  // * [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED] if
  // the requesting user did not create the requested
  // [Photo][google.streetview.publish.v1.Photo].
  // * [google.rpc.Code.NOT_FOUND][google.rpc.Code.NOT_FOUND] if the requested
  // [Photo][google.streetview.publish.v1.Photo] does not exist.
  // * [google.rpc.Code.UNAVAILABLE][google.rpc.Code.UNAVAILABLE] if the
  // requested [Photo][google.streetview.publish.v1.Photo] is still being
  // indexed.
  rpc GetPhoto(GetPhotoRequest) returns (Photo) {
    option (google.api.http) = {
      get: "/v1/photo/{photo_id}"
    };
  }

  // Gets the metadata of the specified
  // [Photo][google.streetview.publish.v1.Photo] batch.
  //
  // Note that if
  // [BatchGetPhotos][google.streetview.publish.v1.StreetViewPublishService.BatchGetPhotos]
  // fails, either critical fields are missing or there is an authentication
  // error. Even if
  // [BatchGetPhotos][google.streetview.publish.v1.StreetViewPublishService.BatchGetPhotos]
  // succeeds, individual photos in the batch may have failures.
  // These failures are specified in each
  // [PhotoResponse.status][google.streetview.publish.v1.PhotoResponse.status]
  // in
  // [BatchGetPhotosResponse.results][google.streetview.publish.v1.BatchGetPhotosResponse.results].
  // See
  // [GetPhoto][google.streetview.publish.v1.StreetViewPublishService.GetPhoto]
  // for specific failures that can occur per photo.
  rpc BatchGetPhotos(BatchGetPhotosRequest) returns (BatchGetPhotosResponse) {
    option (google.api.http) = {
      get: "/v1/photos:batchGet"
    };
  }

  // Lists all the [Photos][google.streetview.publish.v1.Photo] that belong to
  // the user.
  //
  // <aside class="note"><b>Note:</b> Recently created photos that are still
  // being indexed are not returned in the response.</aside>
  rpc ListPhotos(ListPhotosRequest) returns (ListPhotosResponse) {
    option (google.api.http) = {
      get: "/v1/photos"
    };
  }

  // Updates the metadata of a [Photo][google.streetview.publish.v1.Photo], such
  // as pose, place association, connections, etc. Changing the pixels of a
  // photo is not supported.
  //
  // Only the fields specified in the
  // [updateMask][google.streetview.publish.v1.UpdatePhotoRequest.update_mask]
  // field are used. If `updateMask` is not present, the update applies to all
  // fields.
  //
  // This method returns the following error codes:
  //
  // * [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED] if
  // the requesting user did not create the requested photo.
  // * [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT] if
  // the request is malformed.
  // * [google.rpc.Code.NOT_FOUND][google.rpc.Code.NOT_FOUND] if the requested
  // photo does not exist.
  // * [google.rpc.Code.UNAVAILABLE][google.rpc.Code.UNAVAILABLE] if the
  // requested [Photo][google.streetview.publish.v1.Photo] is still being
  // indexed.
  rpc UpdatePhoto(UpdatePhotoRequest) returns (Photo) {
    option (google.api.http) = {
      put: "/v1/photo/{photo.photo_id.id}"
      body: "photo"
    };
  }

  // Updates the metadata of [Photos][google.streetview.publish.v1.Photo], such
  // as pose, place association, connections, etc. Changing the pixels of photos
  // is not supported.
  //
  // Note that if
  // [BatchUpdatePhotos][google.streetview.publish.v1.StreetViewPublishService.BatchUpdatePhotos]
  // fails, either critical fields are missing or there is an authentication
  // error. Even if
  // [BatchUpdatePhotos][google.streetview.publish.v1.StreetViewPublishService.BatchUpdatePhotos]
  // succeeds, individual photos in the batch may have failures.
  // These failures are specified in each
  // [PhotoResponse.status][google.streetview.publish.v1.PhotoResponse.status]
  // in
  // [BatchUpdatePhotosResponse.results][google.streetview.publish.v1.BatchUpdatePhotosResponse.results].
  // See
  // [UpdatePhoto][google.streetview.publish.v1.StreetViewPublishService.UpdatePhoto]
  // for specific failures that can occur per photo.
  //
  // Only the fields specified in
  // [updateMask][google.streetview.publish.v1.UpdatePhotoRequest.update_mask]
  // field are used. If `updateMask` is not present, the update applies to all
  // fields.
  //
  // The number of
  // [UpdatePhotoRequest][google.streetview.publish.v1.UpdatePhotoRequest]
  // messages in a
  // [BatchUpdatePhotosRequest][google.streetview.publish.v1.BatchUpdatePhotosRequest]
  // must not exceed 20.
  //
  // <aside class="note"><b>Note:</b> To update
  // [Pose.altitude][google.streetview.publish.v1.Pose.altitude],
  // [Pose.latLngPair][google.streetview.publish.v1.Pose.lat_lng_pair] has to be
  // filled as well. Otherwise, the request will fail.</aside>
  rpc BatchUpdatePhotos(BatchUpdatePhotosRequest)
      returns (BatchUpdatePhotosResponse) {
    option (google.api.http) = {
      post: "/v1/photos:batchUpdate"
      body: "*"
    };
  }

  // Deletes a [Photo][google.streetview.publish.v1.Photo] and its metadata.
  //
  // This method returns the following error codes:
  //
  // * [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED] if
  // the requesting user did not create the requested photo.
  // * [google.rpc.Code.NOT_FOUND][google.rpc.Code.NOT_FOUND] if the photo ID
  // does not exist.
  rpc DeletePhoto(DeletePhotoRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/photo/{photo_id}"
    };
  }

  // Deletes a list of [Photos][google.streetview.publish.v1.Photo] and their
  // metadata.
  //
  // Note that if
  // [BatchDeletePhotos][google.streetview.publish.v1.StreetViewPublishService.BatchDeletePhotos]
  // fails, either critical fields are missing or there was an authentication
  // error. Even if
  // [BatchDeletePhotos][google.streetview.publish.v1.StreetViewPublishService.BatchDeletePhotos]
  // succeeds, individual photos in the batch may have failures.
  // These failures are specified in each
  // [PhotoResponse.status][google.streetview.publish.v1.PhotoResponse.status]
  // in
  // [BatchDeletePhotosResponse.results][google.streetview.publish.v1.BatchDeletePhotosResponse.status].
  // See
  // [DeletePhoto][google.streetview.publish.v1.StreetViewPublishService.DeletePhoto]
  // for specific failures that can occur per photo.
  rpc BatchDeletePhotos(BatchDeletePhotosRequest)
      returns (BatchDeletePhotosResponse) {
    option (google.api.http) = {
      post: "/v1/photos:batchDelete"
      body: "*"
    };
  }
}