1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.maps.aerialview.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/protobuf/duration.proto"; 23import "google/type/date.proto"; 24 25option csharp_namespace = "Google.Maps.AerialView.V1"; 26option go_package = "cloud.google.com/go/maps/aerialview/apiv1/aerialviewpb;aerialviewpb"; 27option java_multiple_files = true; 28option java_outer_classname = "AerialViewProto"; 29option java_package = "com.google.maps.aerialview.v1"; 30option objc_class_prefix = "GGMPV1B"; 31option php_namespace = "Google\\Maps\\AerialView\\V1"; 32option ruby_package = "Google::Maps::AerialView::V1"; 33 34// Service definition for the Aerial View API. 35service AerialView { 36 option (google.api.default_host) = "aerialview.googleapis.com"; 37 option (google.api.oauth_scopes) = 38 "https://www.googleapis.com/auth/cloud-platform"; 39 40 // Adds an address to the renderer's queue if a video hasn't already been 41 // rendered. Otherwise, returns metadata about the video. 42 rpc RenderVideo(RenderVideoRequest) returns (RenderVideoResponse) { 43 option (google.api.http) = { 44 post: "/v1/videos:renderVideo" 45 body: "*" 46 }; 47 option (google.api.method_signature) = "address"; 48 } 49 50 // Fetches a video given its address or videoId. The response will either be 51 // a video with a set of playback URIs for ACTIVE videos, a PROCESSING state 52 // for pending videos, or a 404 error if the video does not exist. Receiving a 53 // video is a billable event, so callers of this method should be ready to use 54 // the returned URIs at the time of request. 55 rpc LookupVideo(LookupVideoRequest) returns (Video) { 56 option (google.api.http) = { 57 get: "/v1/videos:lookupVideo" 58 }; 59 } 60} 61 62// An object that encapsulates all of the data about a video. 63message Video { 64 // The different states a video can be in. 65 enum State { 66 // Default value. This value is unused. 67 STATE_UNSPECIFIED = 0; 68 69 // The video is currently processing. 70 PROCESSING = 1; 71 72 // The video has finished rendering, and can be viewed through 73 // `LookupVideo`. 74 ACTIVE = 2; 75 76 // The video has failed to render. 77 FAILED = 3; 78 } 79 80 // A mapping of media types to their URIs. 81 // This field is only included for `ACTIVE` videos. 82 // The key is an enum value from `MediaFormat`. 83 map<string, Uris> uris = 1; 84 85 // Current state of the render request. 86 State state = 2; 87 88 // Contains the video's metadata, only set if the state is `ACTIVE`. 89 VideoMetadata metadata = 3; 90} 91 92// Contains all the uris for a given video format. 93message Uris { 94 // A signed short-lived URI for the media in a landscape orientation. 95 string landscape_uri = 1; 96 97 // A signed short-lived URI for the media in a portrait orientation. 98 string portrait_uri = 2; 99} 100 101// Contains metadata about a video, such as its videoId and duration. 102message VideoMetadata { 103 // An ID for the video, and the recommended way to retrieve a video. 104 string video_id = 1; 105 106 // The date at which the imagery used in the video was captured. 107 // This will be at a month-level granularity. 108 google.type.Date capture_date = 2; 109 110 // The length of the video. 111 google.protobuf.Duration duration = 3; 112} 113 114// Request message for `AerialView.RenderVideo`. 115message RenderVideoRequest { 116 // Required. A US postal address for the location to be rendered in the video. 117 string address = 1 [(google.api.field_behavior) = REQUIRED]; 118} 119 120// Response message for `AerialView.RenderVideo`. 121message RenderVideoResponse { 122 // Current state of the render request. 123 Video.State state = 1; 124 125 // Contains the video's metadata, only set if the state is `ACTIVE`. 126 VideoMetadata metadata = 2; 127} 128 129// Request message for `AerialView.LookupVideo`. 130message LookupVideoRequest { 131 // Required. 132 // A key used to look-up a video. 133 oneof key { 134 // An ID returned from `RenderVideo`. 135 string video_id = 1; 136 137 // A US postal address. 138 string address = 2; 139 } 140} 141