{"id":8197,"library":"geoarrow-c","title":"geoarrow-c","description":"geoarrow-c provides Python bindings to the GeoArrow C and C++ implementation, enabling a geospatial type system and generic coordinate-shuffling. It supports Well-Known Binary (WKB), Well-Known Text (ISO), and GeoArrow encodings as Arrow extension types. The library is currently at version 0.3.1 and primarily serves as a low-level dependency for higher-level Python libraries like `geoarrow-python`. Its release cadence follows updates to the GeoArrow specification and its underlying C/C++ implementation.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/geoarrow/geoarrow-c","tags":["geospatial","arrow","apache-arrow","bindings","c","c++","performance","wkb","wkt"],"install":[{"cmd":"pip install geoarrow-c","lang":"bash","label":"Stable release"},{"cmd":"python -m pip install \"git+https://github.com/geoarrow/geoarrow-c.git#egg=geoarrow-c&subdirectory=python/geoarrow-c\"","lang":"bash","label":"Development version"}],"dependencies":[{"reason":"geoarrow-c is primarily intended as a dependency for higher-level GeoArrow Python bindings like `geoarrow-pyarrow` which offer a more user-friendly interface for common geospatial operations.","package":"geoarrow-python"},{"reason":"Direct usage of geoarrow-c often involves interacting with the Arrow C Data interface, making `pyarrow` a practical dependency for creating and consuming Arrow arrays in Python.","package":"pyarrow"}],"imports":[{"note":"The core C functions are exposed under the 'lib' submodule within 'geoarrow.c'.","wrong":"import geoarrow.c as gc","symbol":"lib","correct":"from geoarrow.c import lib"},{"note":"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`.","symbol":"geoarrow.c","correct":"import geoarrow.c"}],"quickstart":{"code":"import geoarrow.pyarrow as ga\nimport pyarrow as pa\nimport urllib.request\nimport os\n\n# Most users should interact with GeoArrow via geoarrow-pyarrow for higher-level operations.\n# geoarrow-c works under the hood of geoarrow-pyarrow.\n\n# Example: Reading a GeoArrow-enabled IPC file using geoarrow.pyarrow\n# This requires geoarrow-pyarrow and pyarrow, which internally use geoarrow-c.\n# Replace with a real URL or local path if needed.\nurl = 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')\n\ntry:\n    with urllib.request.urlopen(url) as f, pa.ipc.open_stream(f) as reader:\n        table = reader.read_all()\n        print(\"Successfully read GeoArrow data via geoarrow.pyarrow.\")\n        print(table.schema.field(\"geometry\").type)\nexcept Exception as e:\n    print(f\"Could not fetch or read sample data: {e}\")\n    print(\"Ensure geoarrow-pyarrow and pyarrow are installed and the URL is accessible.\")\n\n# For direct, low-level interaction with geoarrow.c (less common for end-users):\nfrom geoarrow.c import lib\nprint(f\"geoarrow.c library loaded: {lib.__name__}\")\n# Further usage of `lib` involves Arrow C Data interface specifics, often via ctypes.","lang":"python","description":"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."},"warnings":[{"fix":"Prefer `pip install geoarrow-pyarrow` and `import geoarrow.pyarrow as ga` for most use cases.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.3.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install geoarrow-c`.","cause":"The `geoarrow-c` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'geoarrow.c'"},{"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.","cause":"Attempting to use `geoarrow.c` for high-level geospatial operations, which are typically found in `geoarrow-pyarrow`.","error":"AttributeError: module 'geoarrow.c' has no attribute 'some_high_level_function'"},{"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.","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.","error":"Segmentation fault (core dumped) or other memory errors when manipulating ArrowArrays directly with `geoarrow.c.lib`."}]}