Registry / data / geoarrow-pandas

geoarrow-pandas

library0.1.1pypypi✓ verified 87d ago

GeoArrow Pandas provides GeoArrow extension types for pandas DataFrames, enabling efficient storage and manipulation of geospatial data using the Apache Arrow memory format. It integrates with pandas by implementing the ExtensionArray and ExtensionDtype protocols. The current version is 0.1.1, and it is considered an experimental library with a relatively slow release cadence, indicating ongoing development.

data serialization

pip install geoarrow-pandas

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GEOARROW-PANDAS

geoarrow-pandas

datapythonv0.1.1

Install

9.9s avg

Import

1249ms

Disk

333MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 1.271s · 348.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 9.9s · import 1.226s · 315MB

333MB installed

● package 333MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

geoarrow.pandas

✓ import geoarrow.pandas as ga

GeoArrowExtensionDtype

✓ from geoarrow.pandas import GeoArrowExtensionDtype

✗ from geoarrow.pandas.types import GeoArrowExtensionDtype

The primary types are exposed directly under `geoarrow.pandas` for convenience.

This quickstart demonstrates how to create a pandas Series using GeoArrow extension types, specifically the Well-Known Binary (WKB) format. It uses `shapely` to construct geometries and `ga.wkb_type()` to specify the GeoArrow dtype. The series will behave like a regular pandas Series but with GeoArrow's efficient backing.

import pandas as pd import geoarrow.pandas as ga import shapely # Create a pandas Series with GeoArrow-backed WKB geometries s = pd.Series([shapely.Point(1, 2), shapely.Point(3, 4)], dtype=ga.wkb_type()) print("GeoArrow-backed Series:") print(s) print(f"Series dtype: {s.dtype}") # Example conversion to GeoPandas # geopandas dependency would be needed for actual usage: # try: # import geopandas # gdf = ga.to_geopandas(s.to_frame(name='geometry')) # print('\nConverted to GeoPandas GeoDataFrame:') # print(gdf) # except ImportError: # print('\nSkipping GeoPandas conversion (geopandas not installed).')

Debug

Known issues

breakingAs a '0.x' experimental library, the API of geoarrow-pandas is subject to change without strict backward compatibility guarantees. Expect potential modifications to class names, function signatures, and overall structure in future releases.

fix

Always review release notes for new versions. Pin specific minor versions in your dependencies to mitigate unexpected changes for a period.

affects: All 0.x versions

gotchaDirect conversion of large GeoArrow-backed DataFrames or Series to GeoPandas (e.g., via `ga.to_geopandas`) can be computationally intensive and memory-hungry, as it often involves copying data and converting it to shapely objects.

fix

For operations primarily within the GeoArrow ecosystem, try to avoid frequent conversions to GeoPandas. Convert only when specific GeoPandas functionality is required. Consider processing data in chunks or streaming if memory becomes an issue.

affects: All 0.x versions

gotchaGeoArrow-backed Series (GeoArrowExtensionDtype) do not expose the same comprehensive set of geometry-specific methods (e.g., `.area`, `.centroid`, `.crs`) directly on the Series accessor as a `geopandas.GeoSeries` does.

fix

To access these methods, you may need to explicitly convert the GeoArrow Series to a `geopandas.GeoSeries` using `ga.to_geopandas()` (if the input is a DataFrame/Series) or access the underlying GeoArrowArray for lower-level operations. Many spatial operations can also be performed via the `geoarrow` library itself.

affects: All 0.x versions

gotchaAttempting to create a GeoArrowExtensionDtype Series with incompatible Python objects or incorrect `pyarrow` types can lead to `TypeError` or `ValueError`.

fix

Ensure that the input data (e.g., list of shapely objects) is compatible with the chosen GeoArrow type (e.g., `ga.wkb_type()`). If working with PyArrow arrays directly, ensure they conform to the GeoArrow specifications.

affects: All 0.x versions

Errors

Common errors & fixes

TypeError: cannot convert '...' to GeoArrowExtensionDtype

The data being passed to `pd.Series` (or similar constructor) is not in a format that `geoarrow-pandas` can directly convert into a GeoArrow extension type.

fix

Ensure your input data is a list of `shapely` geometries, WKB/WKT strings, or a compatible PyArrow array. Explicitly specify the GeoArrow dtype, e.g., `pd.Series([...], dtype=ga.wkb_type())` or `pd.Series([...], dtype=ga.point_type(pyarrow.float64()))`.

AttributeError: 'GeoArrowExtensionArray' object has no attribute 'area'

You are attempting to call a geometry-specific method (like `.area`, `.centroid`, etc.) directly on the `GeoArrowExtensionArray` or its accessor, expecting GeoPandas-like behavior.

fix

GeoArrow Pandas provides a memory-efficient backbone, but does not replicate all GeoPandas geometry methods directly. Convert your data to a `geopandas.GeoDataFrame` or `GeoSeries` first using `ga.to_geopandas()` if you need these methods, or use lower-level functions from the `geoarrow` library itself for spatial operations.

ModuleNotFoundError: No module named 'geoarrow.pandas'

The `geoarrow-pandas` library has not been installed in your current Python environment.

fix

Install the library using pip: `pip install geoarrow-pandas`.

Upgrade

Version history

0.1.1latest on PyPI · released Oct 5, 2023

Audit

Dependencies

pandasrequiredCore dataframe library

pyarrowrequiredUnderlying Arrow memory format

geoarrowrequiredCore GeoArrow definitions and types

shapelyrequiredUsed for geometry construction and conversions

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/geoarrow/geoarrow-python ↗

packagehttps://pypi.org/project/geoarrow-pandas/ ↗

homepagehttps://arrow.apache.org ↗