s2sphere

Common errors

• AttributeError: 'str' object has no attribute 'get_center'

  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]
  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')`.

• TypeError: argument of type 'int' is not iterable

  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.
  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.

Warnings

• breaking 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]
  Fix: Monitor official `s2sphere` and `google/s2geometry` repositories for announcements regarding API changes. Pin library versions in `requirements.txt` to mitigate unexpected updates.
• gotcha 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]
  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`
• gotcha 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]
  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.

Install

• pip install s2sphere Install stable release

Imports

• s2sphere

  import s2sphere

  All core classes and functions are typically accessed via the top-level s2sphere module.
• LatLon
  wrong:

  from s2sphere.sphere import LatLon

  correct:

  s2sphere.LatLon.from_degrees(latitude, longitude)

  Direct imports from submodules like `s2sphere.sphere` are generally discouraged and may change between versions; prefer accessing through the main `s2sphere` module.

Quickstart

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]

import s2sphere

# Define two points using latitude and longitude
p1 = s2sphere.LatLon.from_degrees(33, -122)
p2 = s2sphere.LatLon.from_degrees(33.1, -122.1)

# Create a region coverer
r = s2sphere.RegionCoverer()

# Get the S2 cells covering a LatLon rectangle defined by the two points
cell_ids = r.get_covering(s2sphere.LatLonRect.from_point_pair(p1, p2))

# Print the resulting cell IDs
print(f"S2 Cell IDs covering the region: {cell_ids}")

# Example: Convert a CellId to LatLon
if cell_ids:
    first_cell_id = cell_ids[0]
    center_latlon = s2sphere.LatLng.from_point(s2sphere.Cell(first_cell_id).get_center())
    print(f"Center of the first cell ({first_cell_id.to_token()}): {center_latlon.degrees()}, {center_latlon.lngdegrees()}")