docs: clarify behavior of primary types and weekday text

Google APIs · copybara-github · commit f37bfb8159ea · 2025-06-30T15:55:14.000-07:00
PiperOrigin-RevId: 777751281
diff --git a/google/maps/places/v1/place.proto b/google/maps/places/v1/place.proto
@@ -177,14 +177,31 @@ message Place {
     optional bool open_now = 1;
 
     // The periods that this place is open during the week. The periods are in
-    // chronological order, starting with Sunday in the place-local timezone. An
-    // empty (but not absent) value indicates a place that is never open, e.g.
+    // chronological order, in the place-local timezone. An empty (but not
+    // absent) value indicates a place that is never open, e.g.
     // because it is closed temporarily for renovations.
+    //
+    // The starting day of `periods` is NOT fixed and should not be assumed to
+    // be Sunday. The API determines the start day based on a variety of
+    // factors. For example, for a 24/7 business, the first period may begin on
+    // the day of the request. For other businesses, it might be the first day
+    // of the week that they are open.
+    //
+    // NOTE: The ordering of the `periods` array is independent of the ordering
+    // of the `weekday_descriptions` array. Do not assume they will begin on the
+    // same day.
     repeated Period periods = 2;
 
     // Localized strings describing the opening hours of this place, one string
-    // for each day of the week.  Will be empty if the hours are unknown or
-    // could not be converted to localized text. Example: "Sun: 18:00–06:00"
+    // for each day of the week.
+    //
+    // NOTE: The order of the days and the start of the week is determined by
+    // the locale (language and region). The ordering of the `periods` array is
+    // independent of the ordering of the `weekday_descriptions` array. Do not
+    // assume they will begin on the same day.
+    //
+    // Will be empty if the hours are unknown or could not be converted to
+    // localized text. Example: "Sun: 18:00–06:00"
     repeated string weekday_descriptions = 3;
 
     // A type string used to identify the type of secondary hours.
@@ -405,17 +422,22 @@ message Place {
   // https://developers.google.com/maps/documentation/places/web-service/place-types
   repeated string types = 5;
 
-  // The primary type of the given result. This type must one of the Places API
-  // supported types. For example, "restaurant", "cafe", "airport", etc.  A
+  // The primary type of the given result. This type must be one of the Places
+  // API supported types. For example, "restaurant", "cafe", "airport", etc.  A
   // place can only have a single primary type.  For the complete list of
   // possible values, see Table A and Table B at
-  // https://developers.google.com/maps/documentation/places/web-service/place-types
+  // https://developers.google.com/maps/documentation/places/web-service/place-types.
+  // The primary type may be missing if the place's primary type is not a
+  // supported type. When a primary type is present, it is always one of the
+  // types in the `types` field.
   string primary_type = 50;
 
   // The display name of the primary type, localized to the request language if
   // applicable. For the complete list of possible values, see Table A and Table
   // B at
-  // https://developers.google.com/maps/documentation/places/web-service/place-types
+  // https://developers.google.com/maps/documentation/places/web-service/place-types.
+  // The primary type may be missing if the place's primary type is not a
+  // supported type.
   google.type.LocalizedText primary_type_display_name = 32;
 
   // A human-readable phone number for the place, in national format.
diff --git a/google/maps/places/v1/places_service.proto b/google/maps/places/v1/places_service.proto
@@ -41,9 +41,10 @@ option objc_class_prefix = "GMPSV1";
 option php_namespace = "Google\\Maps\\Places\\V1";
 
 // Service definition for the Places API.
-// Note: every request (except for Autocomplete requests) requires a field mask
-// set outside of the request proto (`all/*`, is not assumed). The field mask
-// can be set via the HTTP header `X-Goog-FieldMask`. See:
+// Note: every request (except for Autocomplete and GetPhotoMedia requests)
+// requires a field mask set outside of the request proto (`all/*`, is not
+// assumed). The field mask can be set via the HTTP header `X-Goog-FieldMask`.
+// See:
 // https://developers.google.com/maps/documentation/places/web-service/choose-fields
 service Places {
   option (google.api.default_host) = "places.googleapis.com";
