frequenz-floss / frequenz-api-weather Goto Github PK

+// Pagination parameters for list requests.
+message PaginationParams {
+ // Maximum number of results to be returned per request.
+ // If not set, the default value is 50.
+  uint32 page_size = 1;
+
+  // Identifies a specific page of the list results.
+ string page_token = 2;
+}

+// Metadata for paginated list responses.
+message PaginationInfo {
+  // Total number of orders that match the filter criteria.
+  uint32 total_items = 1;
+
+  // Token for retrieving the next set of results.
+  string next_page_token = 2;
+}

// ... (no change)

service WeatherForecastService {
 // ... (no change)
 rpc GetHistoricalWeatherForecast (GetHistoricalWeatherForecastRequest)
-   returns (ForecastResponse);
+  returns (GetHistoricalWeatherForecastResponse);

 // Streams live weather forecast features for a geo location as they become
 // available. Initially, the most recent forecast will be streamed.
 rpc ReceiveLiveWeatherForecastStream (ReceiveLiveWeatherForecastStreamRequest)
-  returns (stream ForecastResponse);
+  returns (ReceiveLiveWeatherForecastStreamResponse);

}

message GetHistoricalWeatherForecastRequest {
-  // The location for which the forecast is being requested.
+  // The locations for which the forecast is being requested.
+  // The maximum number of locations that can be requested is 50.
-  frequenz.api.common.location.Location location = 1;
+  repeated frequenz.api.common.location.Location location = 1;

  // List of required features. If none are specified, all available features
  // will be returned.
  repeated ForecastFeature features = 2;

  // The UTC timestamp indicating the start of the requested historical forecast
  // period.
  google.protobuf.Timestamp start_ts = 3;

  // The UTC timestamp indicating the end of the requested historical forecast
  // period.
  google.protobuf.Timestamp end_ts = 4;

+ // Pagination parameters.
+ //
  // Specifies the maximum number of forecasts to be returned in a single
  // response. If not provided, a default page size will be used.
-  int32 page_size = 5;
+ PaginationParams pagination_params = 4;
}

message StreamLiveWeatherForecastRequest {
-  // The location for which the forecast is being requested.
+  // The locations for which the forecast is being streamed.
+  // The maximum number of locations that can be streamed is 50.
-  frequenz.api.common.location.Location location = 1;
+  repeated frequenz.api.common.location.Location location = 1;
  
  // ... (no change)
}

- // The ForecastResponse message encapsulates the weather forecast data returned
- // by the SubscribeWeatherForecast method. It provides a structured format for
+ // The ForecastResponse message provides a structured format for
// representing forecast data for a specific location, including timestamps
// for validity and creation.
-message ForecastResponse {
+message LocationForecast {
  // ... (no change)
}

+// A list of forecasts for the requested locations.
+message GetHistoricalWeatherForecastResponse {
+  // List of forecasts per location.
+  repeated LocationForecast forecast= 1;

+  // Metadata for pagination, including token for next page to retrieve.
+  PaginationInfo pagination_info = 4;
+}

// Response to a subscription request for a stream of forecasts for a list of locations.
// Real-time information on forecasts is pushed through this response.
+message ReceiveLiveWeatherForecastStreamResponse {
+  // Forecast for a location being broadcasted in real-time.
+  LocationForecast forecast= 1;
+}
}

syntax = "proto3";

package frequenz.api.weatherforecast.v1;

import "frequenz/api/common/location.proto";
import "google/protobuf/timestamp.proto";

// Service provides operations related to retrieving weather forecasts for
// locations.
//
// The forecasts are updated regularly, and the service will stream the latest
// available data unless a specific time range is requested.
// !!! note
//     Weather forecasts are inherently uncertain and actual conditions may
//     vary. Use the data responsibly.
service WeatherForecastService {
  // Returns historical weather forecast features for a geo location for a
  // specified time range.
- rpc GetHistoricalWeatherForecast (ForecastRequest)
+ rpc GetHistoricalWeatherForecast (GetHistoricalWeatherForecastRequest)
    returns (ForecastResponse);

  // Streams live weather forecast features for a geo location as they become
  // available. Initially, the most recent forecast will be streamed.
- rpc StreamLiveWeatherForecast (ForecastRequest)
+ rpc StreamLiveWeatherForecast (StreamLiveWeatherForecastRequest)
    returns (stream ForecastResponse);
}

// Weather features (e.g. wind speeds or solar radiation) available for query
// through the API.
enum ForecastFeature {
  // ... (no change)
}

-// The ForecastRequest message is used to specify the parameters for the
-// SubscribeWeatherForecast method. It allows users to request weather forecasts
-// for a specific location and time period, with specified features. 
+// The GetHistoricalWeatherForecast message is used to specify the parameters for 
+// requesting historical weather forecasts for a specific location and time period, 
+// with specified features.
- message ForecastRequest {
+message GetHistoricalWeatherForecastRequest {
  // The location for which the forecast is being requested.
  frequenz.api.common.location.Location location = 1;

  // List of required features. If none are specified, all available features
-  // will be streamed.
+  // will be returned.
  repeated ForecastFeature features = 2;

-// Optional for StreamLiveWeatherForecast, ignored if provided.
-// The start of the period for which the forecast is being requested.
+// The start of the period for which the historical forecast is being requested.
  google.protobuf.Timestamp start_ts = 3;

-// Optional for StreamLiveWeatherForecast, ignored if provided.
-// The end of the period for which the forecast is being requested.
+// The end of the period for which the historical forecast is being requested.
  google.protobuf.Timestamp end_ts = 4;

-// Optional for StreamLiveWeatherForecast, ignored if provided.
-// Specifies the maximum number of forecasts to be returned in a single
-// response.
+// Specifies the maximum number of forecasts to be returned in a single
+// response. If not provided, a default page size will be used.  
  int32 page_size = 5;
}

+// The LiveForecastRequest message is for requesting live weather forecasts.
+message StreamLiveWeatherForecastRequest {
+  // The location for which the forecast is being requested.
+  frequenz.api.common.location.Location location = 1;
+
+  // List of required features. If none are specified, all available features
+  // will be streamed.
+  repeated ForecastFeature features = 2;
+}