feat: add bigframes.bigquery.st_area and suggest it from GeoSeries.area (#1318)

* feat: Add GeoSeries.area

* fix formatting

* fix import error

* fix format and return type

* update test

* add type ignore flag

* add and test st_area

* update goseries notebook with area and st_area

* ignore mypy error

* update the notebook

* update the notebook

* ignore exception in notebook

* update test data and add comment

* Update tests/system/small/bigquery/test_geo.py

* Update tests/system/small/bigquery/test_geo.py

---------

Co-authored-by: Tim Sweña (Swast) <[email protected]>

Author: arwas11

bigframes/bigquery/__init__.py

@@ -27,6 +27,7 @@
     unix_millis,
     unix_seconds,
 )
+from bigframes.bigquery._operations.geo import st_area
 from bigframes.bigquery._operations.json import (
     json_extract,
     json_extract_array,
@@ -45,6 +46,8 @@
     "array_length",
     "array_agg",
     "array_to_string",
+    # geo ops
+    "st_area",
     # json ops
     "json_set",
     "json_extract",

bigframes/bigquery/_operations/geo.py

@@ -0,0 +1,93 @@
+# Copyright 2025 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.
+
+from __future__ import annotations
+
+from bigframes import operations as ops
+import bigframes.geopandas
+import bigframes.series
+
+"""
+Search functions defined from
+https://cloud.google.com/bigquery/docs/reference/standard-sql/geography_functions
+"""
+
+
+def st_area(self) -> bigframes.series.Series:
+    """
+    Returns the area in square meters covered by the polygons in the input
+    GEOGRAPHY.
+
+    If geography_expression is a point or a line, returns zero. If
+    geography_expression is a collection, returns the area of the polygons
+    in the collection; if the collection doesn't contain polygons, returns zero.
+
+
+    ..note::
+        BigQuery's Geography functions, like `st_area`, interpet the geomtry
+        data type as a point set on the Earth's surface. A point set is a set
+        of points, lines, and polygons on the WGS84 reference spheroid, with
+        geodesic edges. See: https://cloud.google.com/bigquery/docs/geospatial-data
+
+
+    **Examples:**
+
+        >>> import bigframes.geopandas
+        >>> import bigframes.pandas as bpd
+        >>> import bigframes.bigquery as bbq
+        >>> from shapely.geometry import Polygon, LineString, Point
+        >>> bpd.options.display.progress_bar = None
+
+        >>> series = bigframes.geopandas.GeoSeries(
+        ...         [
+        ...             Polygon([(0.0, 0.0), (0.1, 0.1), (0.0, 0.1)]),
+        ...             Polygon([(0.10, 0.4), (0.9, 0.5), (0.10, 0.5)]),
+        ...             Polygon([(0.1, 0.1), (0.2, 0.1), (0.2, 0.2)]),
+        ...             LineString([(0, 0), (1, 1), (0, 1)]),
+        ...             Point(0, 1),
+        ...         ]
+        ... )
+        >>> series
+        0              POLYGON ((0 0, 0.1 0.1, 0 0.1, 0 0))
+        1    POLYGON ((0.1 0.4, 0.9 0.5, 0.1 0.5, 0.1 0.4))
+        2    POLYGON ((0.1 0.1, 0.2 0.1, 0.2 0.2, 0.1 0.1))
+        3                        LINESTRING (0 0, 1 1, 0 1)
+        4                                       POINT (0 1)
+        dtype: geometry
+
+        >>> bbq.st_area(series)
+        0    61821689.855985
+        1    494563347.88721
+        2    61821689.855841
+        3                0.0
+        4                0.0
+        dtype: Float64
+
+    Use `round()` to round the outputed areas to the neares ten millions
+
+        >>> bbq.st_area(series).round(-7)
+        0     60000000.0
+        1    490000000.0
+        2     60000000.0
+        3            0.0
+        4            0.0
+        dtype: Float64
+
+    Returns:
+      bigframes.pandas.Series:
+          Series of float representing the areas.
+    """
+    series = self._apply_unary_op(ops.geo_area_op)
+    series.name = None
+    return series

bigframes/core/compile/scalar_op_compiler.py

@@ -993,6 +993,11 @@ def geo_y_op_impl(x: ibis_types.Value):
     return typing.cast(ibis_types.GeoSpatialValue, x).y()
 
 
+@scalar_op_compiler.register_unary_op(ops.geo_area_op)
+def geo_area_op_impl(x: ibis_types.Value):
+    return typing.cast(ibis_types.GeoSpatialValue, x).area()
+
+
 # Parameterized ops
 @scalar_op_compiler.register_unary_op(ops.StructFieldOp, pass_op=True)
 def struct_field_op_impl(x: ibis_types.Value, op: ops.StructFieldOp):

bigframes/geopandas/geoseries.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 from __future__ import annotations
 
+import bigframes_vendored.constants as constants
 import bigframes_vendored.geopandas.geoseries as vendored_geoseries
 import geopandas.array  # type: ignore
 
@@ -39,3 +40,29 @@ def y(self) -> bigframes.series.Series:
         series = self._apply_unary_op(ops.geo_y_op)
         series.name = None
         return series
+
+    # GeoSeries.area overrides Series.area with something totally different.
+    # Ignore this type error, as we are trying to be as close to geopandas as
+    # we can.
+    @property
+    def area(self, crs=None) -> bigframes.series.Series:  # type: ignore
+        """Returns a Series containing the area of each geometry in the GeoSeries
+        expressed in the units of the CRS.
+
+        Args:
+            crs (optional):
+                Coordinate Reference System of the geometry objects. Can be
+                anything accepted by pyproj.CRS.from_user_input(), such as an
+                authority string (eg “EPSG:4326”) or a WKT string.
+
+        Returns:
+            bigframes.pandas.Series:
+                Series of float representing the areas.
+
+        Raises:
+            NotImplementedError:
+                GeoSeries.area is not supported. Use bigframes.bigquery.st_area(series), insetead.
+        """
+        raise NotImplementedError(
+            f"GeoSeries.area is not supported. Use bigframes.bigquery.st_area(series), instead. {constants.FEEDBACK_LINK}"
+        )

bigframes/operations/__init__.py

@@ -84,7 +84,7 @@
     SqlScalarOp,
     where_op,
 )
-from bigframes.operations.geo_ops import geo_x_op, geo_y_op
+from bigframes.operations.geo_ops import geo_area_op, geo_x_op, geo_y_op
 from bigframes.operations.json_ops import (
     JSONExtract,
     JSONExtractArray,
@@ -332,6 +332,7 @@
     # Geo ops
     "geo_x_op",
     "geo_y_op",
+    "geo_area_op",
     # Numpy ops mapping
     "NUMPY_TO_BINOP",
     "NUMPY_TO_OP",

bigframes/operations/geo_ops.py

@@ -29,3 +29,10 @@
         dtypes.is_geo_like, dtypes.FLOAT_DTYPE, description="geo-like"
     ),
 )
+
+geo_area_op = base_ops.create_unary_op(
+    name="geo_area",
+    type_signature=op_typing.FixedOutputType(
+        dtypes.is_geo_like, dtypes.FLOAT_DTYPE, description="geo-like"
+    ),
+)