{"id":7256,"library":"geoarrow-types","title":"GeoArrow Types","description":"The `geoarrow-types` package defines Python types for the GeoArrow specification, primarily as PyArrow extension types. It provides a foundational layer for representing geospatial data in Apache Arrow columnar format, enabling interoperability and high-performance geospatial data processing. The current version is 0.3.0, and it follows a minor release cadence aligned with the broader GeoArrow Python ecosystem.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/geoarrow/geoarrow-python","tags":["geospatial","apache-arrow","arrow","pyarrow","data-types","gis"],"install":[{"cmd":"pip install geoarrow-types","lang":"bash","label":"Install geoarrow-types"}],"dependencies":[{"reason":"Core dependency for defining and using Apache Arrow extension types.","package":"pyarrow","optional":false}],"imports":[{"symbol":"PointExtensionType","correct":"from geoarrow_types import PointExtensionType"},{"symbol":"LineStringExtensionType","correct":"from geoarrow_types import LineStringExtensionType"},{"symbol":"PolygonExtensionType","correct":"from geoarrow_types import PolygonExtensionType"},{"symbol":"WkbExtensionType","correct":"from geoarrow_types import WkbExtensionType"},{"symbol":"WktExtensionType","correct":"from geoarrow_types import WktExtensionType"}],"quickstart":{"code":"import pyarrow as pa\nfrom geoarrow_types import PointExtensionType, WkbExtensionType\n\n# 1. Register GeoArrow Point Type\n# This step is crucial for PyArrow to recognize 'geoarrow.point' by name\nPointExtensionType.register_extension_type()\n\n# Create a PyArrow array using the registered GeoArrow point type\npoint_data = pa.array(\n    [\n        {'x': 1.0, 'y': 2.0},\n        {'x': 3.0, 'y': 4.0},\n        None # GeoArrow types support null values\n    ],\n    type=\"geoarrow.point\" # Use the registered string name\n)\nprint(\"\\nGeoArrow Point Array:\")\nprint(point_data)\nprint(\"Is GeoArrow Point Type recognized:\", isinstance(point_data.type, PointExtensionType))\n\n# 2. Register GeoArrow WKB Type\nWkbExtensionType.register_extension_type()\n\n# Example WKB bytes (usually generated by libraries like shapely)\nwkb_point_bytes = b'\\x01\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\xf0?\\x00\\x00\\x00\\x00\\x00\\x00\\x00@'\nwkb_linestring_bytes = b'\\x01\\x02\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x08@\\x00\\x00\\x00\\x00\\x00\\x00\\x10@\\x00\\x00\\x00\\x00\\x00\\x00\\x14@\\x00\\x00\\x00\\x00\\x00\\x00\\x18@'\n\nwkb_data = pa.array([wkb_point_bytes, wkb_linestring_bytes, None], type=\"geoarrow.wkb\")\nprint(\"\\nGeoArrow WKB Array:\")\nprint(wkb_data)\nprint(\"Is GeoArrow WKB Type recognized:\", isinstance(wkb_data.type, WkbExtensionType))\n","lang":"python","description":"This quickstart demonstrates how to register GeoArrow extension types and create PyArrow arrays using these types. It covers both a structured geometry type (Point) and a binary representation type (WKB). The `register_extension_type()` call is essential for PyArrow to map the string identifier (e.g., 'geoarrow.point') to the custom Python class."},"warnings":[{"fix":"Always call `YourExtensionType.register_extension_type()` before creating an array with `pa.array(..., type='geoarrow.yourtype')`.","message":"GeoArrow extension types must be explicitly registered with PyArrow before they can be used by their string identifier (e.g., 'geoarrow.point') when creating arrays. Forgetting this will lead to errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your environment has `pyarrow` installed at version 10.0.0 or higher. Upgrade with `pip install --upgrade pyarrow`.","message":"Version 0.3.0 explicitly requires `pyarrow>=10.0.0`. Older versions of PyArrow (e.g., 9.x or earlier) are not compatible and will likely cause installation or runtime issues.","severity":"breaking","affected_versions":"0.3.0+"},{"fix":"Consult the `_storage_type` property or documentation for the specific `GeoArrowExtensionType` to determine the expected underlying PyArrow data type (e.g., `pa.struct` for Point types, `pa.binary` for WKB).","message":"When manually constructing `pyarrow.ExtensionArray` from a storage array, the storage array's PyArrow data type must precisely match the `_storage_type` defined by the GeoArrow Extension Type. Mismatches will raise `pyarrow.lib.ArrowInvalid`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Call `PointExtensionType.register_extension_type()` before using the string type name. For example: `from geoarrow_types import PointExtensionType; PointExtensionType.register_extension_type(); pa.array([...], type='geoarrow.point')`.","cause":"The GeoArrow extension type 'geoarrow.point' was not registered with PyArrow before being used to create an array.","error":"pyarrow.lib.ArrowKeyError: 'geoarrow.point' not found in type factory"},{"fix":"Ensure the storage array's PyArrow type matches the `_storage_type` of the GeoArrow extension. For `PointExtensionType`, this is typically `pa.struct([pa.field('x', pa.float64()), pa.field('y', pa.float64())])`.","cause":"The PyArrow array provided as storage for an `ExtensionArray` does not match the expected underlying data type for the specific GeoArrow extension type.","error":"pyarrow.lib.ArrowInvalid: Expected a storage array of type Struct<x: double, y: double> but got List<item: string>"}]}