// Copyright 2018 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.


// Proto file describing the GoogleAdsService.
syntax = "proto3";

package google.ads.googleads.v0.services;

import "google/ads/googleads/v0/common/metrics.proto";
import "google/ads/googleads/v0/enums/ad_network_type.proto";
import "google/ads/googleads/v0/enums/day_of_week.proto";
import "google/ads/googleads/v0/enums/device.proto";
import "google/ads/googleads/v0/enums/slot.proto";
import "google/ads/googleads/v0/resources/ad_group.proto";
import "google/ads/googleads/v0/resources/ad_group_ad.proto";
import "google/ads/googleads/v0/resources/ad_group_bid_modifier.proto";
import "google/ads/googleads/v0/resources/ad_group_criterion.proto";
import "google/ads/googleads/v0/resources/bidding_strategy.proto";
import "google/ads/googleads/v0/resources/campaign.proto";
import "google/ads/googleads/v0/resources/campaign_budget.proto";
import "google/ads/googleads/v0/resources/campaign_criterion.proto";
import "google/ads/googleads/v0/resources/customer.proto";
import "google/ads/googleads/v0/resources/geo_target_constant.proto";
import "google/ads/googleads/v0/resources/keyword_view.proto";
import "google/ads/googleads/v0/resources/recommendation.proto";
import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/wrappers.proto";

option java_package = "com.google.ads.googleads.v0.services";
option java_outer_classname = "GoogleAdsServiceProto";
option java_multiple_files = true;

// Objective-C prefix. Google Ads API.
option objc_class_prefix = "GAA";
option csharp_namespace = "Google.Ads.GoogleAds.V0.Services";
option php_namespace = "Google\\Ads\\GoogleAds\\V0\\Services";
option php_metadata_namespace = "Google\\Ads\\GoogleAds\\V0\\Services";

// Service to fetch data and metrics across resources.
service GoogleAdsService {
  // Returns all rows that match the search query.
  rpc Search(SearchGoogleAdsRequest) returns (SearchGoogleAdsResponse) {
    option (google.api.http) = {
      post: "/v0/customers/{customer_id=*}/googleAds:search"
      body: "*"
    };
  }
}

// Request message for [GoogleAdsService.Search][].
message SearchGoogleAdsRequest {
  // The ID of the customer being queried.
  string customer_id = 1;

  // The query string.
  string query = 2;

  // Token of the page to retrieve. If not specified, the first
  // page of results will be returned. Use the value obtained from
  // `next_page_token` in the previous response in order to request
  // the next page of results.
  string page_token = 3;

  // Number of elements to retrieve in a single page.
  // When too large a page is requested, the server may decide to
  // further limit the number of returned resources.
  int32 page_size = 4;
}

// Response message for [GoogleAdsService.Search][].
message SearchGoogleAdsResponse {
  // The list of rows that matched the query.
  repeated GoogleAdsRow results = 1;

  // Pagination token used to retrieve the next page of results.
  // Pass the content of this string as the `page_token` attribute of
  // the next request. `next_page_token` is not returned for the last
  // page.
  string next_page_token = 2;

  // Total number of results that match the query ignoring the LIMIT
  // clause.
  int64 total_results_count = 3;

  // FieldMask that represents what fields were requested by the user.
  google.protobuf.FieldMask field_mask = 5;
}

// A returned row from the query.
message GoogleAdsRow {
  // The ad group referenced in the query.
  resources.AdGroup ad_group = 3;

  // The ad referenced in the query.
  resources.AdGroupAd ad_group_ad = 16;

  // The bid modifier referenced in the query.
  resources.AdGroupBidModifier ad_group_bid_modifier = 24;

  // The criterion referenced in the query.
  resources.AdGroupCriterion ad_group_criterion = 17;

  // The bidding strategy referenced in the query.
  resources.BiddingStrategy bidding_strategy = 18;

  // The campaign budget referenced in the query.
  resources.CampaignBudget campaign_budget = 19;

  // The campaign referenced in the query.
  resources.Campaign campaign = 2;

  // The campaign criterion referenced in the query.
  resources.CampaignCriterion campaign_criterion = 20;

  // The customer referenced in the query.
  resources.Customer customer = 1;

  // The geo target constant referenced in the query.
  resources.GeoTargetConstant geo_target_constant = 23;

  // The keyword view referenced in the query.
  resources.KeywordView keyword_view = 21;

  // The recommendation referenced in the query.
  resources.Recommendation recommendation = 22;

  // The metrics.
  common.Metrics metrics = 4;

  // Ad network type.
  enums.AdNetworkTypeEnum.AdNetworkType ad_network_type = 5;

  // Date to which metrics apply.
  // YYYY-MM-DD format, e.g., 2018-04-17.
  google.protobuf.StringValue date = 6;

  // Day of the week, e.g., MONDAY.
  enums.DayOfWeekEnum.DayOfWeek day_of_week = 7;

  // Platform to which metrics apply.
  enums.DeviceEnum.Device device = 8;

  // Hour of day as a number between 0 and 23, inclusive.
  google.protobuf.Int32Value hour = 9;

  // Month as represented by the date of the first day of a month.
  google.protobuf.StringValue month = 10;

  // Quarter as represented by the date of the first day of a quarter.
  // Uses the calendar year for quarters,
  // e.g., the second quarter of 2018 starts on 2018-04-01.
  google.protobuf.StringValue quarter = 12;

  // Position of the ad.
  enums.SlotEnum.Slot slot = 13;

  // Week as defined as Monday through Sunday, and represented by the date of
  // Monday.
  google.protobuf.StringValue week = 14;

  // Year, formatted as yyyy.
  google.protobuf.Int32Value year = 15;
}
