geoparse package

Submodules

geoparse.geoparse module

class geoparse.geoparse.CellUtils

Bases: object

A utility class for performing operations on spatial cells, such as compaction, uncompaction, and statistical analysis. It supports various spatial indexing systems, including Geohash, H3, and S2, and provides methods to manipulate and analyze spatial cells efficiently.

The class provides methods to: 1. Compact spatial cells by merging adjacent cells into parent cells, reducing the total number of cells. 2. Uncompact S2 cells by expanding them into their child cells at a specified resolution. 3. Compute statistics for H3 cells covering a given geometry, including the number of cells and their area.

Supported cell types: - Geohash: A hierarchical spatial indexing system using base-32 encoding. - H3: A hexagonal hierarchical spatial indexing system. - S2: A spherical geometry library for spatial indexing on a sphere.

Key Features: - Compaction of spatial cells to reduce redundancy and improve efficiency. - Uncompaction of S2 cells for detailed spatial analysis. - Statistical analysis of H3 cells, including cell count and area calculations.

Examples

>>> cellop = CellOperation()

>>> # Compact H3 cells
>>> h3_cells = ["8928308280fffff", "8928308280bffff"]
>>> compacted_cells = cellop.compact_cells(h3_cells, "h3")
>>> print(compacted_cells)

>>> # Uncompact S2 cells
>>> s2_tokens = ["89c2847c", "89c2847d"]
>>> uncompacted_cells = cellop.uncompact_s2(s2_tokens, level=10)
>>> print(uncompacted_cells)

>>> # Compute H3 cell statistics for a geometry
>>> from shapely.geometry import Polygon
>>> geom = Polygon([(-122.0, 37.0), (-122.0, 38.0), (-121.0, 38.0), (-121.0, 37.0), (-122.0, 37.0)])
>>> cell_count, cell_area = cellop.h3_stats(geom, h3_res=9, compact=True)
>>> print(f"Cell count: {cell_count}, Cell area: {cell_area} km^2")

Notes

• Compaction is useful for reducing the number of cells while maintaining spatial coverage.

• Uncompaction allows for detailed analysis by expanding cells into finer resolutions.

• H3 cell statistics are useful for understanding the spatial distribution and coverage of a geometry.

static compact_cells(cells: list, cell_type: str) → list

Compacts a list of spatial cells (e.g., Geohash, S2, or H3) by merging adjacent cells into parent cells.

The function takes a list of spatial cells and compacts them into larger cells if possible, reducing the total number of cells by merging adjacent cells into their parent cell at a coarser resolution. The compaction process differs based on the specified cell_type and its respective hierarchy.

Parameters:

• cells (list) – A list of spatial cells represented as strings. Each cell corresponds to a spatial area in a specific grid system (e.g., Geohash, H3, or S2).

• cell_type (str) – The type of spatial cell system used. Accepted values are: - “geohash” : Geohash spatial indexing system. - “h3” : H3 hexagonal spatial indexing system. - “s2” : S2 spherical spatial indexing system.

Returns:

A list of compacted spatial cells. Each cell is represented as a string and is at the coarsest resolution possible based on the input cells.

Return type:

list

Raises:

ValueError – If cell_type is not one of “geohash”, “h3”, or “s2”.

Notes

• For h3, the function uses the built-in h3.compact() method.

• For s2, the compaction merges cells up to their parent cells by considering the S2 hierarchy.

• For geohash, cells are merged based on shared prefixes.

static h3_stats(geom: BaseGeometry, h3_res: int, compact: bool = False) → Tuple[int, float]

Computes H3 cell statistics for a given geometry at a specified resolution.

This function takes a Shapely geometry object and computes the number of H3 cells covering the geometry at a specified resolution. It also calculates the area of each H3 cell at the given resolution. Optionally, the function can return the compacted set of H3 cells, reducing the number of cells required to represent the geometry.

Parameters:

• geom (shapely.geometry.base.BaseGeometry) – A Shapely geometry object (e.g., Polygon or MultiPolygon) representing the area of interest.

• h3_res (int) – The H3 resolution level for generating spatial cells. The resolution level controls the granularity of the cells.

• compact (bool, optional) – If True, the function returns a compacted set of H3 cells, reducing the number of cells needed to represent the geometry. Default is False.

Returns:

A tuple containing: - int: Number of H3 cells covering the given geometry. - float: Area of each H3 cell at the specified resolution, in square kilometers.

Return type:

tuple

Examples

>>> from shapely.geometry import Polygon
>>> geom = Polygon([(-122.0, 37.0), (-122.0, 38.0), (-121.0, 38.0), (-121.0, 37.0), (-122.0, 37.0)])
>>> h3_stats(geom, h3_res=9, compact=True)
(512, 0.001)

Notes

The function utilizes the H3 library for generating and compacting H3 cells and for calculating cell area. The area is always returned in square kilometers (“km^2”).

static uncompact_s2(compact_tokens: list, level: int) → list

Expands a list of compacted S2 cell tokens to a specified resolution level.

This function takes a list of compact S2 cell tokens and generates their child cells up to the desired resolution level. It is used to “uncompact” S2 cells that have been previously compacted, producing a more detailed representation.

Parameters:

• compact_tokens (list) – A list of S2 cell tokens represented as strings. These tokens are at a coarser resolution level and will be expanded into their child cells.

• level (int) – The target S2 cell resolution level to which the input tokens should be expanded. The resolution level determines the size of the child cells. A higher level corresponds to finer granularity (smaller cells).

Returns:

A list of S2 cell tokens represented as strings. Each token corresponds to a child cell of the input compact tokens, expanded to the specified resolution level.

Return type:

list

Raises:

ValueError – If the provided level is less than or equal to the resolution level of the input compact_tokens.

Example

>>> compact_tokens = ["89c2847c", "89c2847d"]
>>> uncompact_s2(compact_tokens, level=10)
["89c2847c1", "89c2847c2", "89c2847c3", ..., "89c2847d1", "89c2847d2", ...]

class geoparse.geoparse.GeomUtils

Bases: object

A utility class for performing various geometric operations on Shapely geometry objects.

This class provides methods for determining UTM projections, transforming geometries between coordinate reference systems (CRS), calculating geometric statistics, and computing bearings for LineString geometries.

find_proj(geom: Point | LineString | Polygon | MultiPolygon) → str

Determines the appropriate UTM zone projection for a given geometry.

trans_proj(geom: BaseGeometry, proj1: str, proj2: str) → BaseGeometry

Transforms a Shapely geometry object from one CRS to another.

geom_stats(geom: Polygon | MultiPolygon | None = None, projection=None, unit: str = 'm') → List[int | float] | None

Computes geometric statistics for a Polygon or MultiPolygon geometry.

bearing(geom: LineString) → tuple[int, int, str, str]

Calculates the bearing and cardinal directions of a LineString.

Notes

• This class relies on the shapely, pyproj, and math libraries for geometric operations.

• Ensure that input geometries are valid Shapely objects and that CRS definitions are valid and supported by pyproj.

Examples

>>> from shapely.geometry import Polygon, LineString
>>> geom_utils = GeomUtils()

>>> # Example for find_proj
>>> polygon = Polygon([(-120, 35), (-121, 35), (-121, 36), (-120, 36), (-120, 35)])
>>> utm_proj = geom_utils.find_proj(polygon)
>>> print(utm_proj)
'EPSG:32610'

>>> # Example for trans_proj
>>> point = Point(10, 50)
>>> transformed_point = geom_utils.trans_proj(point, "EPSG:4326", "EPSG:32632")
>>> print(transformed_point)
<Point object at 0x...>

>>> # Example for geom_stats
>>> stats = geom_utils.geom_stats(polygon, unit="km")
>>> print(stats)
[1, 0, 4, 12322.539175581376, 444.0301771896464, 'EPSG:32631']

>>> # Example for bearing
>>> line = LineString([(0, 0), (1, 1)])
>>> bearing_info = geom_utils.bearing(line)
>>> print(bearing_info)
(45, 45, 'NE', 'NE-SW')

static bearing(geom: LineString) → tuple[int, int, str, str]

Calculate the bearing and cardinal directions of a LineString.

Parameters:

geom (shapely.geometry.LineString) – The input geometry for which the bearing is calculated.

Returns:

A tuple containing: - bearing (int): The bearing angle in degrees (0 to 359). - axis_bearing (int): The axis bearing in degrees (0 to 179). - cardinal_direction (str): The cardinal direction (e.g., “N”, “NE”). - axis_direction (str): The cardinal axis direction (e.g., “N-S”, “E-W”). Returns (-1, -1, “LOOP”, “LOOP”) if the LineString forms a loop.

Return type:

tuple[int, int, str, str]

Notes

The bearing is calculated based on the angle between the starting and ending points of the LineString, relative to North.

Examples

>>> from shapely.geometry import LineString
>>> geom = LineString([(0, 0), (1, 1)])
>>> bearing(geom)
(45, 45, 'NE', 'NE-SW')

>>> loop_geom = LineString([(0, 0), (1, 1), (0, 0)])
>>> bearing(loop_geom)
(-1, -1, 'LOOP', 'LOOP')

static find_proj(geom: Point | LineString | Polygon | MultiPolygon) → str

Determines the appropriate UTM zone projection for a given geometry.

Calculates the Universal Transverse Mercator (UTM) zone projection based on the centroid coordinates of the input geometry. The function returns the corresponding EPSG code for the UTM zone in which the geometry is located.

Parameters:

geom (Point, LineString, Polygon, or MultiPolygon) – A Shapely geometry object, which can be a Point, Polygon, or MultiPolygon.

Returns:

The EPSG code representing the UTM projection for the geometry’s location. For the northern hemisphere, the function returns codes in the format ‘EPSG:326XX’. For the southern hemisphere, it returns ‘EPSG:327XX’, where ‘XX’ is the UTM zone number.

Return type:

str

Notes

The UTM (Universal Transverse Mercator) system divides the Earth into 60 longitudinal zones, each 6 degrees wide. This function uses the centroid of the input geometry to determine the appropriate zone and EPSG code.

Examples

>>> from shapely.geometry import Polygon
>>> geom = Polygon([(-120, 35), (-121, 35), (-121, 36), (-120, 36), (-120, 35)])
>>> find_proj(geom)
'EPSG:32610'

static flatten_3d(geom: GeoSeries) → List[Polygon | MultiPolygon]

Flattens a GeoSeries of 3D Polygons or MultiPolygons into 2D geometries.

This function removes the z-coordinate from each 3D geometry in the input GeoSeries, converting it into a 2D Polygon or MultiPolygon. The result is a list of 2D geometries.

Parameters:

geom (gpd.GeoSeries) – A GeoSeries containing 3D Polygons or MultiPolygons (geometries with z-coordinates).

Returns:

A list of 2D Polygons or MultiPolygons with the z-coordinates removed.

Return type:

List[Union[Polygon, MultiPolygon]]

Examples

>>> gdf.geometry = flatten_3d(gdf.geometry)
    Converts all 3D geometries in the GeoSeries `gdf.geometry` to 2D geometries.

Notes

The function is useful when working with datasets that contain 3D geometries but only 2D geometries are needed for further spatial analysis or visualization.

static geom_stats(geom: Polygon | MultiPolygon | None = None, projection=None, unit: str = 'm') → List[int | float] | None

Computes geometric statistics for a Polygon or MultiPolygon geometry.

Calculates various statistics for a given Shapely geometry, such as the number of shells (outer boundaries), number of holes, number of shell points, total area, and total perimeter length. If no geometry is provided, the function will print a usage example.

Parameters:

• geom (Polygon or MultiPolygon, optional) – A Shapely geometry object (Polygon or MultiPolygon) for which to compute the statistics. If not provided, the function will print a usage example and not perform any computations. Default is None.

• projection (str, optional) – The EPSG code used for calculating perimeter and area of the geom in meters or kilometers, and square meters or square kilometers. If None, the UTM zone will be calculated.

• unit (str, optional) – The unit for area and length calculations. Accepts “m” for meters and “km” for kilometers. Default is “m”.

Returns:

• list of int or float, optional –

  A list containing the following statistics in order:

  • Number of shells (int)

  • Number of holes (int)

  • Number of shell points (int)

  • Total area (float)

  • Total perimeter length (float)

  • The projection used for calculating the area and perimeter

• If no geometry is provided, the function returns None.

Examples

>>> from shapely.geometry import Polygon
>>> geom = Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)])
>>> geom_stats(geom, unit="km")
[1, 0, 4, 12322.539175581376, 444.0301771896464, 'EPSG:32631']

static line_to_points(row: GeoSeries) → GeoDataFrame

Splits a LineString geometry into individual Point geometries while preserving original attributes.

This function takes a GeoSeries representing a single row of a GeoDataFrame, extracts the coordinates from a LineString geometry, and creates a new GeoDataFrame with each Point as a separate row. All original attributes from the input row are preserved in the new GeoDataFrame.

Parameters:

row (gpd.GeoSeries) – A GeoSeries representing a single row of a GeoDataFrame. It must include a ‘geometry’ column containing a LineString geometry.

Returns:

A new GeoDataFrame where each row corresponds to a Point geometry derived from the coordinates of the LineString. All other columns from the original row are preserved.

Return type:

gpd.GeoDataFrame

Examples

>>> line_gdf = gpd.GeoDataFrame({"geometry": [LineString([(0, 0), (1, 1), (2, 2)])]})
>>> point_gdf = line_to_points(line_gdf.iloc[0])
>>> print(point_gdf)
   geometry
0  POINT (0 0)
1  POINT (1 1)
2  POINT (2 2)

static trans_proj(geom: BaseGeometry, proj1: str, proj2: str) → BaseGeometry

Transforms a Shapely geometry object from one CRS to another.

Uses pyproj to create a transformation pipeline that converts the input geometry from the source CRS (proj1) to the target CRS (proj2). The resulting geometry is returned in the new coordinate reference system.

Parameters:

• geom (BaseGeometry) – A Shapely geometry object to be transformed. This can include Point, Polygon, MultiPolygon, LineString, or any other Shapely geometry type.

• proj1 (str) – The EPSG code or PROJ string representing the source CRS of the input geometry.

• proj2 (str) – The EPSG code or PROJ string representing the target CRS for the transformed geometry.

Returns:

The transformed Shapely geometry object in the target projection.

Return type:

BaseGeometry

Notes

• The function requires pyproj and shapely libraries.

• Ensure that the input and output CRS definitions are valid and supported by pyproj.

Examples

>>> from shapely.geometry import Point
>>> geom = Point(10, 50)
>>> trans_proj(geom, "EPSG:4326", "EPSG:32632")
<Point object at 0x...>

class geoparse.geoparse.Karta

Bases: object

static choropleth(gdf: GeoDataFrame, columns: list, bins: list, legend: str, palette: str = 'YlOrRd', highlight: bool = True) → Map

Creates a choropleth map using the given GeoDataFrame and specified parameters.

This function generates a Folium choropleth map layer by visualizing the data from a GeoDataFrame using color gradients to represent different data values across geographic areas.

Parameters:

• gdf (geopandas.GeoDataFrame) – The GeoDataFrame containing multipolygon geometries and data attributes to be visualized.

• columns (list) –

  A list of two elements:

  • columns[0]str

    The column name in gdf that contains unique identifiers for each region.

  • columns[1]str

    The column name in gdf containing the data values to be visualized.

• bins (list) – A list of numerical values defining the value intervals for the choropleth color categories.

• legend (str) – The title for the legend, which describes what is represented on the map.

• palette (str, optional) – The color palette to be used for the choropleth (default is “YlOrRd”).

• highlight (bool, optional) – A flag indicating whether regions should be highlighted when hovered over (default is True).

Returns:

The Folium map object containing the choropleth layer.

Return type:

folium.Map

Examples

>>> choropleth(
        gdf,
        ['region_id', 'population'],
        bins=[0, 100, 500, 1000, 5000],
        legend="Population by Region",
        palette="YlOrRd",
        highlight=True
    )

static plp(gdf_list: DataFrame | GeoDataFrame | List[DataFrame | GeoDataFrame] = None, cluster: bool = False, heatmap: bool = False, line: bool = False, antpath: bool = False, point_color: str = 'blue', color_head: str | None = None, color_tail: str | None = None, point_opacity: float = 0.5, point_radius: int = 3, point_weight: int = 6, point_popup: dict | None = None, buffer_radius: int = 0, ring_inner_radius: int = 0, ring_outer_radius: int = 0, x: str | None = None, y: str | None = None, line_color: str = 'blue', line_opacity: float = 0.5, line_weight: int = 6, line_popup: dict | None = None, centroid: bool = False, fill_color: str = 'red', highlight_color: str = 'green', fill_opacity: float = 0.25, highlight_opacity: float = 0.5, line_width: float = 0.3, poly_popup: dict | None = None, geohash_res: int = 0, s2_res: int = -1, h3_res: int = -1, geohash_inner: bool = False, compact: bool = False, cells: List[str] | None = None, cell_type: str | None = None, osm_ways: List[int] | None = None, url: str | None = 'https://overpass-api.de/api/interpreter') → Map

plp (points, lines, polygons) creates a Folium map with points, lines, or polygons based on the input geospatial data. The function plp allows users to add different geometrical elements (points, lines, polygons) to a Folium map. It supports various visual styles and configurations, such as clustering, heatmaps, and geohash or cell-based layers.

Parameters:

• gdf_list (list of gpd.GeoDataFrame or pd.DataFrame, optional) – List of GeoDataFrames or DataFrames containing geometrical data to be plotted. If a single DataFrame is provided, it will be wrapped in a list internally.

• cluster (bool, default False) – If True, clusters points together based on their proximity using Folium’s MarkerCluster.

• heatmap (bool, default False) – If True, creates a heatmap layer using Folium’s HeatMap for points.

• line (bool, default False) – If True, connects points using Folium’s PolyLine to form lines.

• antpath (bool, default False) – If True, creates animated ant paths for the line geometries using Folium’s AntPath.

• point_color (str, default "blue") – Color of the points when displayed on the map.

• color_head (str, optional) – Substring index for the head to extract color.

• color_tail (str, optional) – Substring index for the tail to extract color.

• point_opacity (float, default 0.5) – Opacity of the points. Value should be between 0 and 1.

• point_radius (int, default 3) – Radius of the points in pixels.

• point_weight (int, default 6) – Weight (thickness) of the point outline. Typically set to twice the point_radius.

• point_popup (dict, optional) – Dictionary where keys are labels and values are column names in the DataFrame. Used to create HTML popups with attributes of each point.

• buffer_radius (float, default 0) – Buffer radius (in meters) to create a buffer around each point. Set to 0 to disable buffering.

• ring_inner_radius (float, default 0) – Inner radius of ring buffers around points. Only used if ring_outer_radius is set.

• ring_outer_radius (float, default 0) – Outer radius of ring buffers around points. If set, creates a ring around each point.

• x (str, optional) – Column name for the x-coordinate (longitude). Specify it to use the column other than that containing ‘lon’.

• y (str, optional) – Column name for the y-coordinate (latitude). Specify it to use the column other than that containing ‘lat’.

• line_color (str, default "blue") – Color of the lines connecting points or LineString geometries.

• line_opacity (float, default 0.5) – Opacity of the lines. Value should be between 0 and 1.

• line_weight (int, default 6) – Thickness of the lines.

• line_popup (dict, optional) – Dictionary where keys are labels and values are column names in the DataFrame. Used to create HTML popups with attributes of each line.

• centroid (bool, default False) – If True, displays the centroids of polygon geometries on the map.

• fill_color (str, default "red") – Fill color for polygon geometries.

• highlight_color (str, default "green") – Color used to highlight polygons when hovered.

• line_width (float, default 0.3) – Thickness of polygon outlines.

• poly_popup (dict, optional) – Dictionary where keys are labels and values are column names in the DataFrame. Used to create HTML popups with attributes of each polygon.

• geohash_res (int, default 0) – Resolution for creating geohash-based polygonal layers. Set to 0 to disable.

• s2_res (int, default -1) – Resolution for creating S2-based polygonal layers. Set to -1 to disable.

• h3_res (int, default -1) – Resolution for creating H3-based polygonal layers. Set to -1 to disable.

• geohash_inner (bool, default False) – If True, shows only inner geohash cells. Does not work if compact is set to True.

• compact (bool, default False) – If True, creates compact representation of geohash, S2, or H3 cells.

• cells (list, optional) – List of geohash, S2, or H3 cell IDs to visualize.

• cell_type (str, optional) – Type of cells used in cells parameter. Can be ‘geohash’, ‘s2’, or ‘h3’.

• osm_ways (list of int, optional) – List of OSM way IDs to visualize as lines or polygons.

• url (str, optional) – Overpass API URL to query OSM geometries by osm_ways parameter.

Returns:

A Folium map object with the added geometrical features based on input parameters.

Return type:

folium.Map

Examples

>>> # Example usage
>>> gdf = gpd.read_file("path/to/shapefile.shp")
>>> plp(gdf)

class geoparse.geoparse.OSMUtils

Bases: object

A utility class for converting OpenStreetMap (OSM) way IDs into Shapely geometries.

This class provides methods to retrieve and convert OSM way IDs into Shapely Polygon or LineString objects using the Overpass API. It supports both single and multiple way ID conversions.

way_to_geom(way_id: int) → Optional[LineString or Polygon]

Converts a single OSM way ID into a Shapely Polygon or LineString object.

ways_to_geom(ids: List[int]) → List[LineString or Polygon]

Converts a list of OSM way IDs into a list of Shapely Polygon or LineString objects.

Notes

• The class uses the Overpass API to fetch geometry data for OSM ways.

• Ensure that the provided way IDs are valid and that the Overpass API is accessible.

• The returned geometries are in WGS84 (latitude/longitude) coordinates.

Examples

>>> converter = WayConverter()
>>> # Convert a single way ID
>>> geometry = converter.way_to_geom(123456)
>>> print(geometry)
POLYGON ((13.3888 52.5170, 13.3976 52.5291, 13.4286 52.5232, 13.3888 52.5170))

>>> # Convert multiple way IDs
>>> geometries = converter.ways_to_geom([123456, 234567])
>>> print(geometries)
[<shapely.geometry.polygon.Polygon object at 0x...>,
 <shapely.geometry.linestring.LineString object at 0x...>]

static decode(encoded: str) → list

Decodes an encoded polyline string from Valhalla into a list of coordinates.

Valhalla routing, map-matching, and elevation services use an encoded polyline format to store a series of latitude and longitude coordinates as a single string. This function decodes the polyline into a list of coordinates with six decimal precision.

Parameters:

encoded (str) – An encoded polyline string as per the Valhalla encoding format.

Returns:

A list of [longitude, latitude] pairs decoded from the input polyline string.

Return type:

list of list of float

Notes

• The function uses six decimal degrees of precision for decoding Valhalla’s encoded polylines.

• The decoded coordinates are returned in [longitude, latitude] format.

References

• https://github.com/valhalla/valhalla-docs/blob/master/decoding.md#decode-a-route-shape

Examples

>>> encoded_polyline = "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
>>> decoded_coords = decode(encoded_polyline)
>>> print(decoded_coords)
[[-120.2, 38.5], [-120.95, 40.7], [-126.453, 43.252]]

static map_matching(df: DataFrame, cost: str, url: str, format: str = 'osrm') → dict | None

Performs map matching using Valhalla’s Meili service.

Map matching aligns a series of GPS points onto a road network. This function takes a DataFrame of coordinates, sends a request to the Meili map-matching service, and returns the matched coordinates along with other route information.

Parameters:

• df (pd.DataFrame) – A pandas DataFrame containing the GPS coordinates to be map-matched. It should be in the format of [{“lon”: float, “lat”: float}, …].

• cost (str) – The routing profile to use for map matching. Common values include “auto”, “bicycle”, or “pedestrian”.

• url (str) – The URL endpoint for the Meili map-matching service.

• format (str, optional) – The response format for the request, either “osrm” or “geojson”. Defaults to “osrm”.

Returns:

A dictionary representing the JSON response from the map-matching service if the request is successful, otherwise None.

Return type:

Optional[dict]

Examples

>>> coordinates = [{"lon": -73.9857, "lat": 40.7484}, {"lon": -73.9851, "lat": 40.7478}]
>>> df = pd.DataFrame(coordinates)
>>> url = "https://valhalla.mapzen.com/trace_attributes"
>>> matched_route = map_matching(df, "auto", url)
>>> print(matched_route)
{'shape': '_p~iF~ps|U_ulLnnqC_mqNvxq`@', 'confidence_score': 1.0}

static way_to_geom(way_id: int, url: str = 'https://overpass-api.de/api/interpreter') → LineString | None

Converts an OSM way ID into a Shapely Polygon or LineString object.

This function retrieves the geometry corresponding to the given OSM way ID and returns it as a Shapely Polygon or LineString object based on whether the way forms a closed loop or not.

Parameters:

• way_id (int) – The OpenStreetMap (OSM) way ID to be retrieved.

• url (str, optional) – The URL endpoint for the Overpass API. Defaults to “https://overpass-api.de/api/interpreter”.

Returns:

A Shapely Polygon object if the way forms a closed loop, or a LineString object otherwise.

Return type:

shapely.geometry.Polygon or shapely.geometry.LineString

Notes

• The function constructs an Overpass API query using the given way ID, requests the geometry, and then converts it into a Shapely geometry.

• Assumes that the Overpass API returns data in JSON format with a “geometry” attribute.

Examples

>>> way_id = 123456
>>> url = "https://overpass-api.de/api/interpreter"
>>> geometry = way_to_geom(way_id, url)
>>> print(geometry)
POLYGON ((13.3888 52.5170, 13.3976 52.5291, 13.4286 52.5232, 13.3888 52.5170))

static ways_to_geom(ids: List[int], url: str = 'https://overpass-api.de/api/interpreter') → List[LineString]

Converts an array of OpenStreetMap (OSM) way IDs into Shapely geometries.

This function retrieves the geometries corresponding to the given OSM way IDs and returns a list of Shapely LineString or Polygon objects based on the geometries fetched from the OSM API.

Parameters:

• ids (list of int) – A list of OSM way IDs to be retrieved.

• url (str, optional) – The URL endpoint for the Overpass API. Defaults to “https://overpass-api.de/api/interpreter”.

Returns:

A list of Shapely LineString or Polygon objects representing the geometries of the OSM ways. If the way forms a closed loop, it is returned as a Polygon; otherwise, it is returned as a LineString.

Return type:

list of shapely.geometry.LineString or shapely.geometry.Polygon

Notes

• The function constructs an Overpass API query using the given IDs, requests the geometries, and then converts them into Shapely geometries.

• The function assumes that the Overpass API returns data in JSON format and expects the “geometry” attribute to contain the coordinates.

Examples

>>> way_ids = [123456, 234567, 345678]
>>> url = "https://overpass-api.de/api/interpreter"
>>> geometries = ways_to_geom(way_ids, url)
>>> print(geometries)
[<shapely.geometry.polygon.Polygon object at 0x...>,
 <shapely.geometry.linestring.LineString object at 0x...>]

class geoparse.geoparse.SpatialIndex

Bases: object

A class for performing spatial indexing operations on geographic data.

This class provides methods to convert geographic coordinates (latitude, longitude) and geometries (Polygon, MultiPolygon) into spatial cell representations using various encoding systems such as Geohash, S2, and H3. It also supports parallel processing for efficient handling of large datasets.

Methods:

point_cell(lats, lons, cell_type, res):

Converts latitude and longitude coordinates into spatial index representations.

poly_cell(geoms, cell_type, res, dump):

Converts a list of geometries into a set of unique spatial cells.

ppoint_cell(lats, lons, cell_type, res):

Converts latitude and longitude coordinates into spatial index representations in parallel.

ppoly_cell(mdf, cell_type, res, compact, dump, verbose):

Performs parallelized conversion of geometries in a GeoDataFrame to cell identifiers.

cell_point(cells, cell_type):

Converts a list of cell IDs into their corresponding centroids.

cell_poly(cells, cell_type):

Converts a list of spatial cells to their corresponding geometries and resolution levels.

pcell_point(cells, cell_type):

Converts a list of cell IDs into their corresponding latitude and longitude points in parallel.

pcell_poly(cells, cell_type):

Parallelized version of cell_poly, converting a list of spatial cells to geometries and resolution levels.

static cell_point(cells: List[str | int], cell_type: str) → List[Tuple[float, float]]

Converts a list of cell IDs into their corresponding centroids.

This function supports various cell ID types: ‘geohash’, ‘h3’, ‘s2_int’ (integer-based S2 cells), and ‘s2’ (token-based S2 cells). For each cell in the list, it returns the latitude and longitude of the cell’s center.

Parameters:

• cells (list of str or int) – List of cell identifiers. The format of each cell ID depends on the specified cell_type: - For ‘geohash’: cells should be a list of geohash strings. - For ‘h3’: cells should be a list of H3 cell ID strings. - For ‘s2_int’: cells should be a list of integer-based S2 cell IDs. - For ‘s2’: cells should be a list of S2 token strings.

• cell_type (str) – Type of the cell ID format. Should be one of the following: - ‘geohash’: Geohash encoding. - ‘h3’: H3 hexagonal grid encoding. - ‘s2_int’: Integer-based S2 cell ID. - ‘s2’: S2 token (string-based cell ID).

Returns:

A list of tuples where each tuple contains the latitude and longitude (in degrees) of the center point for each cell ID.

Return type:

list of tuple of float

Raises:

ValueError – If the cell_type is not one of ‘geohash’, ‘h3’, ‘s2’, or ‘s2_int’.

Examples

>>> cell_point(["ezs42", "u4pruydqqvj"], cell_type="geohash")
[(42.6, -5.6), (57.64911, 10.40744)]

>>> cell_point(["8928308280fffff"], cell_type="h3")
[(37.775938728915946, -122.41795063018799)]

>>> cell_point([9744573459660040192], cell_type="s2_int")
[(37.7749, -122.4194)]

>>> cell_point(["89c25c"], cell_type="s2")
[(37.7749, -122.4194)]

static cell_poly(cells: list, cell_type: str) → tuple

Converts a list of spatial cells to their corresponding geometries and resolution levels.

The function takes a list of spatial cells (e.g., Geohash, H3, or S2) and converts each cell into a geometry object (Polygon) based on the specified cell type. It also calculates the resolution level for each cell.

Parameters:

• cells (list) – A list of spatial cells represented as strings. Each cell corresponds to a spatial area in a specific grid system (e.g., Geohash, H3, or S2).

• cell_type (str) – The type of spatial cell system used. Accepted values are: - “geohash” : Geohash spatial indexing system. - “h3” : H3 hexagonal spatial indexing system. - “s2” : S2 spherical spatial indexing system.

Returns:

A tuple containing: - res : list of int

A list of resolution levels corresponding to each cell in the input.

• geomslist of shapely.geometry.Polygon

  A list of Polygon geometries representing the spatial boundaries of the input cells.

Return type:

tuple

Raises:

ValueError – If cell_type is not one of “geohash”, “h3”, or “s2”.

Example

>>> from shapely.geometry import Polygon
>>> cells = ["ezs42", "ezs43"]  # Geohash cells
>>> cell_type = "geohash"
>>> res, geoms = cell_poly(cells, cell_type)
>>> print(res)
[5, 5]  # Resolution levels of the input cells
>>> print(geoms)
[<shapely.geometry.polygon.Polygon object at 0x...>, <shapely.geometry.polygon.Polygon object at 0x...>]
# Polygon geometries representing the spatial boundaries of the cells

Notes

The function supports three spatial indexing systems: - Geohash: Uses rectangular bounding boxes to represent cells. - H3: Uses hexagonal grid cells. - S2: Uses spherical grid cells.

static pcell_point(cells: List[str | int], cell_type: str) → List[Tuple[float, float]]

Converts a list of cell IDs into their corresponding latitude and longitude points in parallel.

Parameters:

• cells (list of str or int) – List of cell identifiers.

• cell_type (str) – Type of the cell ID format.

Returns:

List of tuples containing the latitude and longitude (in degrees) of each cell ID.

Return type:

list of tuple of float

static pcell_poly(cells: List[str | int], cell_type: str) → tuple

Parallelized version of cell_poly, converting a list of spatial cells to geometries and resolution levels.

Parameters:

• cells (list of str or int) – List of spatial cells in a specific grid system.

• cell_type (str) – Type of spatial cell system (“geohash”, “h3”, or “s2”).

Returns:

A tuple containing: - res : list of int

Resolution levels for each cell in the input.

• geomslist of shapely.geometry.Polygon

  Polygon geometries representing the boundaries of input cells.

Return type:

tuple

static point_cell(lats: list[float], lons: list[float], cell_type: str, res: int) → list

Convert latitude and longitude coordinates into spatial index representations using various cell encoding types.

Parameters:

latslist[float]

A list of latitude values (in decimal degrees) for each point to encode.

lonslist[float]

A list of longitude values (in decimal degrees) for each point to encode.

cell_typestr

The type of spatial encoding to use. Options are:

• ‘geohash’: Encodes the coordinates using the geohash format.

• ‘s2’: Encodes the coordinates using the S2 library, outputting a string representation.

• ‘s2_int’: Encodes the coordinates using the S2 library, outputting an integer representation.

• ‘h3’: Encodes the coordinates using the H3 library, outputting a hex string.

resint

The resolution or precision level for the encoding, specific to each encoding type.

Returns:

list

A list of encoded cell identifiers. The data type of each identifier depends on cell_type:

• ‘geohash’ and ‘s2’: list of str

• ‘s2_int’: list of int

• ‘h3’: list of str

Raises:

ValueError

If cell_type is not one of ‘geohash’, ‘s2’, ‘s2_int’, or ‘h3’.

Example:

>>> lats = [37.7749, 34.0522]
>>> lons = [-122.4194, -118.2437]
>>> point_cell(lats, lons, "geohash", 6)
['9q8yy', '9qh0b']

static poly_cell(geoms: List[Polygon | MultiPolygon], cell_type: str, res: int, dump: str = None) → List[str] | None

Converts a list of geometries into a set of unique spatial cells based on the specified cell type and resolution.

This function takes a list of Shapely geometries (e.g., Polygon, MultiPolygon) and converts them into spatial cells using one of the supported cell systems: Geohash, S2, or H3. The resulting cells are returned as a list of unique cell IDs. If dump is set to a valid directory path, the cells are saved to a file in that directory, instead of being returned.

Parameters:

• geoms (list of shapely.geometry.Polygon or shapely.geometry.MultiPolygon) – A list of Shapely geometry objects (Polygon or MultiPolygon).

• cell_type (str) – The type of spatial cell system to use. Supported values are “geohash”, “s2”, or “h3”.

• res (int) – The resolution level for the spatial cells. The resolution parameter determines the granularity of the cells.

• dump (str, optional) – If set to a valid directory path (string), the cells are saved to a file in the specified folder. The file will be saved in a subdirectory structure following the pattern: /path/to/dir/cell_type/res/. If dump is None, the function returns the list of cell IDs. Default is None.

Returns:

If dump is None, a list of unique cell IDs is returned. If dump is provided, None is returned after saving the cells to a file.

Return type:

list of str or None

Raises:

ValueError – If cell_type is not one of the supported values (“geohash”, “s2”, “h3”).

Examples

>>> from shapely.geometry import Polygon, MultiPolygon
>>> geometries = [Polygon([(0, 0), (1, 0), (1, 1), (0, 1)]), MultiPolygon([...])]
>>> # Convert geometries to H3 cells at resolution 9
>>> h3_cells = poly_cell(geometries, cell_type="h3", res=9)

>>> # Convert geometries to S2 cells and save to a directory
>>> poly_cell(geometries, cell_type="s2", res=10, dump="~/Desktop/spatial_cells")

static ppoint_cell(lats: list[float], lons: list[float], cell_type: str, res: int) → list

Converts lists of latitude and longitude points to cell identifiers in parallel.

This function takes lists of latitude and longitude points and converts each pair into a cell identifier based on the specified cell_type and resolution res. It leverages parallel processing to speed up the conversion, dividing the data into chunks and using Pool.starmap for concurrent execution.

Parameters:

• lats (list of float) – List of latitude values.

• lons (list of float) – List of longitude values, corresponding element-wise to the latitude list.

• cell_type (str) –

  The type of spatial encoding to use. Options are:

  • ’geohash’: Encodes the coordinates using the geohash format.

  • ’s2’: Encodes the coordinates using the S2 library, outputting a string representation.

  • ’s2_int’: Encodes the coordinates using the S2 library, outputting an integer representation.

  • ’h3’: Encodes the coordinates using the H3 library, outputting a hex string.

• res (int) – Resolution or precision level for the cell identifiers. Higher values indicate finer precision.

Returns:

A list of cell identifiers corresponding to the input latitude and longitude points.

Return type:

list

Raises:

ValueError – If cell_type is not one of ‘geohash’, ‘s2’, ‘s2_int’, or ‘h3’.

Notes

This function splits the input latitude and longitude lists into chunks and performs the cell conversion in parallel, with each chunk processed by a separate CPU core. This can significantly reduce processing time for large datasets.

Examples

>>> lats = [37.7749, 40.7128]
>>> lons = [-122.4194, -74.0060]
>>> cell_type = "h3"
>>> res = 9
>>> ppoint_cell(lats, lons, cell_type, res)
['8928308280fffff', '8a28308280fffff']

static ppoly_cell(mdf: GeoDataFrame, cell_type: str, res: int, compact: bool = False, dump: str = None, verbose: bool = False) → Tuple[List[str], int]

Performs a parallelised conversion of geometries in a GeoDataFrame to cell identifiers of a specified type (e.g., Geohash, S2, or H3), optionally compacting the result to reduce the number of cells.

This function first divides the bounding box of the input GeoDataFrame into smaller grid cells, then calculates the intersection between these grid cells and the input geometries. The resulting geometries are processed in parallel to generate cell identifiers according to the specified cell_type and res (resolution). The result can be compacted to reduce the number of cells. Optionally, if dump is provided, the results are saved in multiple files, where the number of files is 4 times the number of CPU cores available in the system.

Parameters:

• mdf (gpd.GeoDataFrame) – A GeoDataFrame containing geometries that need to be converted to cell identifiers.

• cell_type (str) – The type of cell identifier to use. Options are: - “geohash”: Converts geometries to Geohash identifiers. - “s2”: Converts geometries to S2 cell tokens. - “h3”: Converts geometries to H3 cell tokens.

• res (int) – The resolution or precision level of the cell identifiers. Higher values indicate finer precision.

• compact (bool, optional, default=False) – If True, compact the resulting cells to reduce their number. This is typically applicable for S2 and H3 cells.

• dump (str, optional) – A string representing a valid directory path. If provided, the cells are saved in multiple files within the directory /path/to/dir/cell_type/res/. The number of output files will be 4 times the number of CPU cores available in the system. If not provided, the function returns the list of cell identifiers instead of saving them to files. Default is None.

• verbose (bool, optional, default=False) – If True, print timing and progress information to the console.

Returns:

• A list of cell identifiers as strings, corresponding to the geometries in the input GeoDataFrame.

• The total number of unique cell identifiers.

Return type:

Tuple[List[str], int]

Raises:

ValueError – If an invalid cell_type is provided. Supported types are “geohash”, “s2”, and “h3”.

Example

>>> # Assuming `mdf` is a GeoDataFrame with geometries:
>>> cells, count = ppoly_cell(mdf, cell_type="s2", res=10, compact=True, dump="~/Desktop/cells", verbose=True)
>>> print(f"Generated {count} cells: {cells}")

class geoparse.geoparse.SpatialOps

Bases: object

A utility class for performing advanced spatial operations on GeoDataFrames and geometries.

This class provides methods for handling 3D geometries, converting LineStrings to Points, performing spatial intersections, and executing parallelized spatial overlay operations. It is designed to work with GeoPandas GeoDataFrames and Shapely geometries.

flatten_3d(geom: gpd.GeoSeries) → List[Polygon | MultiPolygon]

Converts 3D geometries in a GeoSeries to 2D geometries by removing the z-coordinate.

line_to_points(row: gpd.GeoSeries) → gpd.GeoDataFrame

Splits a LineString geometry into individual Point geometries while preserving attributes.

intersection(gdf1: gpd.GeoDataFrame, gdf2: gpd.GeoDataFrame, poly_id: str | None = None) → gpd.GeoDataFrame

Performs a spatial intersection between two GeoDataFrames and returns the intersecting subset.

quick_intersection(gdf1: gpd.GeoDataFrame, gdf2: gpd.GeoDataFrame, poly_id: str | None = None) → gpd.GeoDataFrame

Performs an optimized spatial intersection using bounding box filtering and spatial indexing.

poverlay(gdf1: gpd.GeoDataFrame, gdf2: gpd.GeoDataFrame, how: str = 'intersection', keep_geom_type: bool = False) → gpd.GeoDataFrame

Executes a parallelized spatial overlay operation between two GeoDataFrames.

Notes

• The class relies on GeoPandas and Shapely for spatial operations and multiprocessing for parallelization.

• Ensure that input GeoDataFrames have the same coordinate reference system (CRS) for accurate results.

Examples

>>> spatial_ops = SpatialOps()

>>> # Example for flatten_3d
>>> gdf_2d = spatial_ops.flatten_3d(gdf.geometry)
>>> print(gdf_2d)

>>> # Example for line_to_points
>>> point_gdf = spatial_ops.line_to_points(line_gdf.iloc[0])
>>> print(point_gdf)

>>> # Example for intersection
>>> result_gdf = spatial_ops.intersection(gdf1, gdf2, poly_id="region_id")
>>> print(result_gdf)

>>> # Example for quick_intersection
>>> result_gdf = spatial_ops.quick_intersection(gdf1, gdf2, poly_id="region_id")
>>> print(result_gdf)

>>> # Example for poverlay
>>> result_gdf = spatial_ops.poverlay(gdf1, gdf2, how="intersection")
>>> print(result_gdf)

static geocoding_google(address_or_zipcode: str, api_key: str) → Series

Returns geographic coordinates (latitude and longitude) for a given address or zip code using the Google Geocoding API.

This function utilizes the Google Geocoding API to convert a given address or zip code into geographic coordinates. The function returns the latitude and longitude as a pandas Series. If the request is unsuccessful or the address is not found, the function returns a Series with (None, None).

Parameters:

• address_or_zipcode (str) – A text-based address or zip code that needs to be geocoded.

• api_key (str) – A valid Google Maps API key required to access the Google Geocoding service.

Returns:

A pandas Series containing the latitude and longitude as floats. If the request fails or the address is not found, returns a Series with (None, None).

Return type:

pd.Series

Examples

>>> df[["lat", "lon"]] = df.apply(lambda row: geocoding_google(row.address, "your_api_key"), axis=1)
>>> result = geocoding_google("1600 Amphitheatre Parkway, Mountain View, CA", "your_api_key")
>>> print(result)
lat    37.4224764
lon   -122.0842499
dtype: float64

Notes

• Make sure to enable the Google Geocoding API in your Google Cloud Console and provide a valid API key.

• The API might return ambiguous results if the input address is incomplete or vague.

• Consider handling None values in the returned Series if the API fails to find the address or the request limit is exceeded.

Raises:

Exception – If there is an error in the API request or response parsing, an exception is raised with an error message.

static haversine(lat1: float, lon1: float, lat2: float, lon2: float) → float

Calculates the great-circle distance between two points on the Earth’s surface.

The haversine formula determines the shortest distance over the Earth’s surface between two points given their latitudes and longitudes. The result is the distance in meters, based on a mean Earth radius.

Parameters:

• lat1 (float) – Latitude of the first point in decimal degrees.

• lon1 (float) – Longitude of the first point in decimal degrees.

• lat2 (float) – Latitude of the second point in decimal degrees.

• lon2 (float) – Longitude of the second point in decimal degrees.

Returns:

The great-circle distance between the two points in meters.

Return type:

float

References

[1]

https://en.wikipedia.org/wiki/Haversine_formula

[2]

https://en.wikipedia.org/wiki/Longitude

Examples

>>> haversine(52.2296756, 21.0122287, 41.8919300, 12.5113300)
1319743.483

Notes

The mean Earth radius is taken as 6,371,008.8 meters. a = 6378137.0 # Equatorial radius b = 6356752.3142 # Polar radius R = (2*a + b)/3 # Mean radius = 6371008.7714

static intersection(gdf1: GeoDataFrame, gdf2: GeoDataFrame, poly_id: str | None = None) → GeoDataFrame

Performs a spatial intersection between two GeoDataFrames and return the intersecting subset of the first GeoDataFrame.

This function identifies geometries in gdf1 that intersect with any geometries in gdf2. It adds a new column, counts, to gdf2 representing the number of intersecting geometries for each feature in gdf2. If a poly_id column is specified, it also adds the geometry ID from gdf2 to the intersected subset of gdf1.

Parameters:

• gdf1 (geopandas.GeoDataFrame) – The first GeoDataFrame whose geometries are tested for intersection with gdf2.

• gdf2 (geopandas.GeoDataFrame) – The second GeoDataFrame containing geometries to intersect with gdf1.

• poly_id (str, optional) – The column name in gdf2 containing unique geometry identifiers. If provided, the intersected subset of gdf1 will include a new column geom_id indicating the geometry ID from gdf2 that each feature intersects with.

Returns:

A new GeoDataFrame containing only the intersecting geometries from gdf1 with respect to gdf2. If poly_id is provided, the intersected GeoDataFrame will also include a geom_id column.

Return type:

geopandas.GeoDataFrame

Examples

>>> gdf1 = geopandas.read_file("data1.shp")
>>> gdf2 = geopandas.read_file("data2.shp")
>>> result_gdf = intersection(gdf1, gdf2, poly_id="region_id")

Notes

The function modifies gdf2 in place by adding a counts column, which reflects the number of geometries in gdf1 that intersect with each geometry in gdf2.

static poverlay(gdf1: GeoDataFrame, gdf2: GeoDataFrame, how: str = 'intersection', keep_geom_type: bool = False) → GeoDataFrame

Performs a spatial overlay operation between two GeoDataFrames in parallel using multiple CPU cores.

This function divides the first GeoDataFrame into chunks according to the number of available CPU cores and applies the specified overlay operation (e.g., intersection, union, difference) in parallel on each chunk with respect to the second GeoDataFrame. The results are then concatenated and returned as a single GeoDataFrame.

Parameters:

• gdf1 (gpd.GeoDataFrame) – The first GeoDataFrame to be used in the spatial overlay operation.

• gdf2 (gpd.GeoDataFrame) – The second GeoDataFrame to be used in the spatial overlay operation.

• how (str, optional) – The type of overlay operation to perform. Options include “intersection”, “union”, “difference”, “symmetric_difference”, and “identity”. Defaults to “intersection”.

• keep_geom_type (bool, optional) – Whether to retain the original geometry type (e.g., Polygon, LineString) in the resulting overlay. If set to True, only features of the same geometry type are retained. Defaults to False.

Returns:

A new GeoDataFrame resulting from the spatial overlay operation, with the same coordinate reference system (CRS) as the first input GeoDataFrame (gdf1).

Return type:

gpd.GeoDataFrame

Examples

>>> gdf1 = gpd.GeoDataFrame({"geometry": [Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])]})
>>> gdf2 = gpd.GeoDataFrame({"geometry": [Polygon([(1, 1), (3, 1), (3, 3), (1, 3)])]})
>>> result_gdf = poverlay(gdf1, gdf2, how="intersection")
>>> print(result_gdf)
                                             geometry
0  POLYGON ((2.00000 1.00000, 2.00000 2.00000, 1....

Notes

• The spatial overlay operation is performed using the geopandas.overlay function. The parallelization is achieved using the multiprocessing library to divide and distribute the overlay operations across multiple CPU cores.

• Ensure that both GeoDataFrames (gdf1 and gdf2) have the same coordinate reference system (CRS) before applying the overlay operation to avoid unexpected results.

Raises:

ValueError – If the how parameter is not one of the supported overlay operation types: “intersection”, “union”, “difference”, “symmetric_difference”, or “identity”.

static quick_intersection(gdf1: GeoDataFrame, gdf2: GeoDataFrame, poly_id: str | None = None) → GeoDataFrame

Performs a quick spatial intersection between two GeoDataFrames using bounding box optimization.

This function identifies geometries in gdf1 that intersect with any geometries in gdf2. It uses a spatial index to quickly filter gdf1 geometries that are likely to intersect with the bounding box of each geometry in gdf2. It then performs a precise intersection check on this subset, improving the performance of the intersection operation.

If a poly_id column is provided, the function adds a new geom_id column to the resulting intersected GeoDataFrame, storing the geometry ID from gdf2 that each feature in gdf1 intersects with. It also modifies gdf2 by adding a counts column to indicate the number of intersecting geometries.

Parameters:

• gdf1 (geopandas.GeoDataFrame) – The first GeoDataFrame whose geometries are tested for intersection with gdf2.

• gdf2 (geopandas.GeoDataFrame) – The second GeoDataFrame containing geometries to intersect with gdf1.

• poly_id (str, optional) – The column name in gdf2 containing unique geometry identifiers. If provided, the intersected subset of gdf1 will include a new column geom_id indicating the geometry ID from gdf2 that each feature intersects with.

Returns:

A new GeoDataFrame containing only the intersecting geometries from gdf1 with respect to gdf2. If poly_id is provided, the intersected GeoDataFrame will also include a geom_id column.

Return type:

geopandas.GeoDataFrame

Examples

>>> gdf1 = geopandas.read_file("data1.shp")
>>> gdf2 = geopandas.read_file("data2.shp")
>>> result_gdf = quick_intersection(gdf1, gdf2, poly_id="region_id")

Notes

• This function modifies gdf2 in place by adding a counts column, which reflects the number of geometries in gdf1 that intersect with each geometry in gdf2.

• It leverages spatial indexing using the sindex attribute of gdf1 to quickly identify candidates for intersection, which significantly improves performance for large datasets.

static reverse_geocoding_google(lat: float, lon: float, api_key: str) → str

Returns the postal code for a given geographic coordinate (latitude, longitude) using the Google Geocoding API.

This function makes a reverse geocoding request to the Google Geocoding API to obtain the postal code associated with the provided latitude and longitude. If the postal code is found, it is returned as a string. If not, None is returned.

Parameters:

• lat (float) – The latitude of the location to reverse geocode.

• lon (float) – The longitude of the location to reverse geocode.

• api_key (str) – A valid Google Maps API key for accessing the geocoding service.

Returns:

The postal code corresponding to the input geographic coordinates, if found. Returns None if no postal code is found or if the request fails.

Return type:

str

Examples

>>> reverse_geocoding_google(37.4224764, -122.0842499, "your_api_key")
'94043'

>>> df["postcode"] = df.apply(lambda row: reverse_geocoding_google(row.lat, row.lon, "your_api_key"), axis=1)

static vincenty(lat1: float, lon1: float, lat2: float, lon2: float) → float

Calculates the geodesic distance between two points on the Earth’s surface using the Vincenty formula, which accounts for the Earth’s ellipsoidal shape.

Parameters: - lat1, lon1: Latitude and longitude of the first point (in degrees). - lat2, lon2: Latitude and longitude of the second point (in degrees).

Returns: - Distance between the two points in meters.

Notes: - This implementation may encounter numerical issues, such as divide-by-zero errors,

in edge cases where the points are on opposite sides of the Earth or on the same meridian e.g., from (0,0) to (0,90).However, for points (0,0) to (0.001,90), the distance calculation is accurate within a small error margin (about 9.3e-06 meters).

• The error in the above approach can be significant for very small distances, such as between (0,0) and (0,0.001).

geoparse.geoparse.plp(gdf_list: DataFrame | GeoDataFrame | List[DataFrame | GeoDataFrame] = None, cluster: bool = False, heatmap: bool = False, line: bool = False, antpath: bool = False, point_color: str = 'blue', color_head: str | None = None, color_tail: str | None = None, point_opacity: float = 0.5, point_radius: int = 3, point_weight: int = 6, point_popup: dict | None = None, buffer_radius: int = 0, ring_inner_radius: int = 0, ring_outer_radius: int = 0, x: str | None = None, y: str | None = None, line_color: str = 'blue', line_opacity: float = 0.5, line_weight: int = 6, line_popup: dict | None = None, centroid: bool = False, fill_color: str = 'red', highlight_color: str = 'green', fill_opacity: float = 0.25, highlight_opacity: float = 0.5, line_width: float = 0.3, poly_popup: dict | None = None, geohash_res: int = 0, s2_res: int = -1, h3_res: int = -1, geohash_inner: bool = False, compact: bool = False, cells: List[str] | None = None, cell_type: str | None = None, osm_ways: List[int] | None = None, url: str | None = 'https://overpass-api.de/api/interpreter') → Map

plp (points, lines, polygons) creates a Folium map with points, lines, or polygons based on the input geospatial data. The function plp allows users to add different geometrical elements (points, lines, polygons) to a Folium map. It supports various visual styles and configurations, such as clustering, heatmaps, and geohash or cell-based layers.

Parameters:

• gdf_list (list of gpd.GeoDataFrame or pd.DataFrame, optional) – List of GeoDataFrames or DataFrames containing geometrical data to be plotted. If a single DataFrame is provided, it will be wrapped in a list internally.

• cluster (bool, default False) – If True, clusters points together based on their proximity using Folium’s MarkerCluster.

• heatmap (bool, default False) – If True, creates a heatmap layer using Folium’s HeatMap for points.

• line (bool, default False) – If True, connects points using Folium’s PolyLine to form lines.

• antpath (bool, default False) – If True, creates animated ant paths for the line geometries using Folium’s AntPath.

• point_color (str, default "blue") – Color of the points when displayed on the map.

• color_head (str, optional) – Substring index for the head to extract color.

• color_tail (str, optional) – Substring index for the tail to extract color.

• point_opacity (float, default 0.5) – Opacity of the points. Value should be between 0 and 1.

• point_radius (int, default 3) – Radius of the points in pixels.

• point_weight (int, default 6) – Weight (thickness) of the point outline. Typically set to twice the point_radius.

• point_popup (dict, optional) – Dictionary where keys are labels and values are column names in the DataFrame. Used to create HTML popups with attributes of each point.

• buffer_radius (float, default 0) – Buffer radius (in meters) to create a buffer around each point. Set to 0 to disable buffering.

• ring_inner_radius (float, default 0) – Inner radius of ring buffers around points. Only used if ring_outer_radius is set.

• ring_outer_radius (float, default 0) – Outer radius of ring buffers around points. If set, creates a ring around each point.

• x (str, optional) – Column name for the x-coordinate (longitude). Specify it to use the column other than that containing ‘lon’.

• y (str, optional) – Column name for the y-coordinate (latitude). Specify it to use the column other than that containing ‘lat’.

• line_color (str, default "blue") – Color of the lines connecting points or LineString geometries.

• line_opacity (float, default 0.5) – Opacity of the lines. Value should be between 0 and 1.

• line_weight (int, default 6) – Thickness of the lines.

• line_popup (dict, optional) – Dictionary where keys are labels and values are column names in the DataFrame. Used to create HTML popups with attributes of each line.

• centroid (bool, default False) – If True, displays the centroids of polygon geometries on the map.

• fill_color (str, default "red") – Fill color for polygon geometries.

• highlight_color (str, default "green") – Color used to highlight polygons when hovered.

• line_width (float, default 0.3) – Thickness of polygon outlines.

• poly_popup (dict, optional) – Dictionary where keys are labels and values are column names in the DataFrame. Used to create HTML popups with attributes of each polygon.

• geohash_res (int, default 0) – Resolution for creating geohash-based polygonal layers. Set to 0 to disable.

• s2_res (int, default -1) – Resolution for creating S2-based polygonal layers. Set to -1 to disable.

• h3_res (int, default -1) – Resolution for creating H3-based polygonal layers. Set to -1 to disable.

• geohash_inner (bool, default False) – If True, shows only inner geohash cells. Does not work if compact is set to True.

• compact (bool, default False) – If True, creates compact representation of geohash, S2, or H3 cells.

• cells (list, optional) – List of geohash, S2, or H3 cell IDs to visualize.

• cell_type (str, optional) – Type of cells used in cells parameter. Can be ‘geohash’, ‘s2’, or ‘h3’.

• osm_ways (list of int, optional) – List of OSM way IDs to visualize as lines or polygons.

• url (str, optional) – Overpass API URL to query OSM geometries by osm_ways parameter.

Returns:

A Folium map object with the added geometrical features based on input parameters.

Return type:

folium.Map

Examples

>>> # Example usage
>>> gdf = gpd.read_file("path/to/shapefile.shp")
>>> plp(gdf)

Module contents