{"id":7696,"library":"s2sphere","title":"s2sphere","description":"s2sphere is a Python implementation of a part of Google's C++ S2 Geometry Library. It provides tools for working with spherical geometry, such as mapping points and regions on a sphere to a 1D index, enabling scalable proximity searches on distributed indexes. The current version is 0.2.5, and it maintains an active release cadence, primarily via updates to its GitHub repository and PyPI package. [1, 2, 3]","status":"active","version":"0.2.5","language":"en","source_language":"en","source_url":"https://github.com/sidewalklabs/s2sphere","tags":["geometry","geospatial","s2-geometry","mapping","spatial-indexing","sphere"],"install":[{"cmd":"pip install s2sphere","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"All core classes and functions are typically accessed via the top-level s2sphere module.","symbol":"s2sphere","correct":"import s2sphere"},{"note":"Direct imports from submodules like `s2sphere.sphere` are generally discouraged and may change between versions; prefer accessing through the main `s2sphere` module.","wrong":"from s2sphere.sphere import LatLon","symbol":"LatLon","correct":"s2sphere.LatLon.from_degrees(latitude, longitude)"}],"quickstart":{"code":"import s2sphere\n\n# Define two points using latitude and longitude\np1 = s2sphere.LatLon.from_degrees(33, -122)\np2 = s2sphere.LatLon.from_degrees(33.1, -122.1)\n\n# Create a region coverer\nr = s2sphere.RegionCoverer()\n\n# Get the S2 cells covering a LatLon rectangle defined by the two points\ncell_ids = r.get_covering(s2sphere.LatLonRect.from_point_pair(p1, p2))\n\n# Print the resulting cell IDs\nprint(f\"S2 Cell IDs covering the region: {cell_ids}\")\n\n# Example: Convert a CellId to LatLon\nif cell_ids:\n    first_cell_id = cell_ids[0]\n    center_latlon = s2sphere.LatLng.from_point(s2sphere.Cell(first_cell_id).get_center())\n    print(f\"Center of the first cell ({first_cell_id.to_token()}): {center_latlon.degrees()}, {center_latlon.lngdegrees()}\")","lang":"python","description":"This quickstart demonstrates how to use `s2sphere` to find S2 cells covering a geographical region defined by two latitude-longitude points. It then shows how to convert one of these cell IDs back to its center latitude and longitude. [1, 3]"},"warnings":[{"fix":"Monitor official `s2sphere` and `google/s2geometry` repositories for announcements regarding API changes. Pin library versions in `requirements.txt` to mitigate unexpected updates.","message":"The underlying C++ S2 Geometry Library, which `s2sphere` partially implements or binds to, explicitly states that its Python API is unstable and may be replaced. Future versions could introduce breaking changes due to a planned migration from SWIG to pybind11 for more Pythonic names and complete functionality. [5]","severity":"breaking","affected_versions":"All 0.x versions and potentially future major versions."},{"fix":"When iterating with `walk_hilbert_curve`, ensure you explicitly create a *copy* of the `CellId` instance if you need to retain its value outside the current iteration. E.g., `for cell_id_obj in cell.walk_hilbert_curve(level): current_id = s2sphere.CellId(cell_id_obj.id) # Create a new instance`","message":"The `s2sphere.CellId.walk_hilbert_curve` method internally mutates a single `CellId` instance to yield subsequent IDs. If you store or save the `CellId` object returned by the iterator directly, its value will change out from underneath you in subsequent iterations. [12]","severity":"gotcha","affected_versions":"0.2.5"},{"fix":"Always remember the spherical nature of S2 geometry. Utilize `s2sphere`'s dedicated methods for distance calculations, region coverings, and geometric operations that correctly account for Earth's curvature. Convert latitude/longitude pairs to `s2sphere.LatLng` and `s2sphere.Point` for accurate operations.","message":"The `s2sphere` library is designed for spherical geometry. Applying assumptions from planar Euclidean geometry (e.g., straight-line distance, simple bounding boxes) can lead to incorrect results, especially over large distances or near poles. [3, 5, 9, 10]","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":"Before using `CellId` or `Cell` methods, convert the hex-encoded string token into an `s2sphere.CellId` object using `s2sphere.CellId.from_token('your_hex_token_string')`.","cause":"Users often obtain S2 Cell IDs as hex-encoded string 'tokens' (e.g., from databases or APIs). Attempting to directly use `Cell` or `CellId` object methods like `get_center()` or `get_vertex()` on such a string will result in an `AttributeError` because these methods belong to `s2sphere.CellId` or `s2sphere.Cell` objects, not strings. [17]","error":"AttributeError: 'str' object has no attribute 'get_center'"},{"fix":"Ensure that inputs to `s2sphere` functions match the expected type (e.g., lists of `CellId` objects, `LatLonRect` objects). If you have a single `CellId` and a function expects an iterable, wrap it in a list `[my_cell_id]`. Remember that `CellId` objects have an `id` attribute which is an integer, and the `CellId` object itself is what is typically passed around.","cause":"Some S2 sphere functions, particularly those dealing with collections of CellIds (like a RegionCoverer's output), expect iterable inputs or return lists of `CellId` objects. Trying to pass a single integer or non-iterable where a collection is expected, or conversely, attempting to iterate over a single `CellId`'s internal 'id' attribute (which is an integer) will raise this error.","error":"TypeError: argument of type 'int' is not iterable"}]}