geoarrow-c

Common errors

• ModuleNotFoundError: No module named 'geoarrow.c'

  cause The `geoarrow-c` package is not installed in the current Python environment.
  fix Run `pip install geoarrow-c`.

• AttributeError: module 'geoarrow.c' has no attribute 'some_high_level_function'

  cause Attempting to use `geoarrow.c` for high-level geospatial operations, which are typically found in `geoarrow-pyarrow`.
  fix Install `geoarrow-pyarrow` (`pip install geoarrow-pyarrow`) and use `import geoarrow.pyarrow as ga` for operations like reading GeoParquet, converting to GeoPandas, or performing computations.

• Segmentation fault (core dumped) or other memory errors when manipulating ArrowArrays directly with `geoarrow.c.lib`.

  cause Incorrect handling of Arrow C Data interface structures (e.g., `ArrowArray`, `ArrowSchema`) when interacting with `geoarrow.c.lib`, often due to misuse of pointers, incorrect buffer sizes, or memory lifetimes.
  fix Direct interaction with `geoarrow.c.lib` requires a deep understanding of the Arrow C Data interface. It is highly recommended to use higher-level Python libraries like `pyarrow` and `geoarrow-pyarrow` that safely manage these low-level details. If direct interaction is unavoidable, meticulously follow the Arrow C Data interface specification and `geoarrow-c`'s C/C++ examples for correct memory management.

Warnings

• gotcha Direct usage of `geoarrow-c` for high-level geospatial operations is generally discouraged. Its primary role is as a low-level binding for the C/C++ GeoArrow implementation. For most Python users, `geoarrow-pyarrow` (from the `geoarrow-python` package) offers a much more ergonomic and feature-rich interface for working with GeoArrow data, including integrations with `pyarrow`, `pandas`, and `geopandas`.
  Fix: Prefer `pip install geoarrow-pyarrow` and `import geoarrow.pyarrow as ga` for most use cases.
• breaking The GeoArrow specification itself has undergone revisions (e.g., from v0.1 to v0.2). These updates introduced new array types (Box, Geometry, Geometry Collection), updated Coordinate Reference System (CRS) definitions, and support for binary view/string view storage types for WKT/WKB. While `geoarrow-c` aims to support these, changes in the specification might implicitly affect how data is interpreted or structured across different versions, especially when exchanging data with tools built on older spec versions.
  Fix: Ensure all GeoArrow-related libraries in your ecosystem (e.g., `geoarrow-python`, `geoarrow-c`) are updated to versions that support the same GeoArrow specification (preferably 0.2 or newer) to ensure compatibility and correct interpretation of data structures and metadata. Refer to the GeoArrow specification changelog.
• gotcha When building `geoarrow-c` from source, particularly in development environments, ensure that `nanoarrow` and other C dependencies are correctly handled. The library utilizes amalgamated C/C++ files for distribution, but direct compilation might require specific CMake configurations.
  Fix: For standard installation, use `pip install geoarrow-c` to leverage pre-built wheels. For development builds, consult the `geoarrow-c` GitHub repository's build instructions and ensure all submodules and dependencies are correctly fetched and configured with CMake. The internal vendored copies of geoarrow-c and nanoarrow are updated in `geoarrow 0.4.0`.

Install

• pip install geoarrow-c Stable release
• python -m pip install "git+https://github.com/geoarrow/geoarrow-c.git#egg=geoarrow-c&subdirectory=python/geoarrow-c" Development version

Imports

• lib
  wrong:

  import geoarrow.c as gc

  correct:

  from geoarrow.c import lib

  The core C functions are exposed under the 'lib' submodule within 'geoarrow.c'.
• geoarrow.c

  import geoarrow.c

  While `import geoarrow.c` is correct, direct usage of its low-level interface is generally not recommended for most high-level geospatial tasks. Users should typically prefer `geoarrow.pyarrow`.

Quickstart

This quickstart demonstrates the recommended way to interact with GeoArrow data in Python using `geoarrow-pyarrow`, which leverages `geoarrow-c` internally. It includes a basic example of reading GeoArrow-encoded data. It also shows a minimal direct import of `geoarrow.c.lib` for low-level access, which is generally not needed by most users.

import geoarrow.pyarrow as ga
import pyarrow as pa
import urllib.request
import os

# Most users should interact with GeoArrow via geoarrow-pyarrow for higher-level operations.
# geoarrow-c works under the hood of geoarrow-pyarrow.

# Example: Reading a GeoArrow-enabled IPC file using geoarrow.pyarrow
# This requires geoarrow-pyarrow and pyarrow, which internally use geoarrow-c.
# Replace with a real URL or local path if needed.
url = os.environ.get('GEOARROW_SAMPLE_DATA_URL', 'https://raw.githubusercontent.com/geoarrow/geoarrow-data/v0.2.0/natural-earth/files/natural-earth_cities_wkb.arrows')

try:
    with urllib.request.urlopen(url) as f, pa.ipc.open_stream(f) as reader:
        table = reader.read_all()
        print("Successfully read GeoArrow data via geoarrow.pyarrow.")
        print(table.schema.field("geometry").type)
except Exception as e:
    print(f"Could not fetch or read sample data: {e}")
    print("Ensure geoarrow-pyarrow and pyarrow are installed and the URL is accessible.")

# For direct, low-level interaction with geoarrow.c (less common for end-users):
from geoarrow.c import lib
print(f"geoarrow.c library loaded: {lib.__name__}")
# Further usage of `lib` involves Arrow C Data interface specifics, often via ctypes.