private/google/streetview/publish/v1/streetview_publish.proto
// 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/api/client.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 {
option (google.api.default_host) = "streetviewpublish.googleapis.com";
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/streetviewpublish";
// 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: "*"
};
}
}