here.geopandas_adapter.geotiles.heretile module — HERE Data SDK for Python documentation
- Last UpdatedMar 27, 2025
- 10 minute read
Module to operate with HERETile tiling scheme using (Geo)DataFrames.
- here.geopandas_adapter.geotiles.heretile.ancestor(tile_ids: Series, level: int | None = None) Series [source]#
Return the ancestor tiles at the given level for the tiles.
Index and
NaN
values are retained.NaN
is also returned in case of invalid tile IDs or tiling level, or when the ancestor doesn’t exist.- Parameters:
tile_ids – the tile IDs
level – the tiling level
- Returns:
a
pd.Series
with the tile IDs of the ancestors or parents, when existing- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.contains_coordinates(tile_ids: Series, lngs: Series, lats: Series) Series [source]#
Return if the tiles contains the points.
The check includes the tile boundary, aligned with the way shapely
intersects
operates.NaN
values or not all the series containing a value for a given index determine the resulting tile ID to beNaN
.- Parameters:
tile_ids – the tile IDs
lngs – the Series with longitudes
lats – the Series with latitudes
- Returns:
a
pd.Series
containing if the points are inside the tiles- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.contains_geometry(tile_ids: Series, geometries: GeoSeries, fully_contained=False) Series [source]#
Return if the tiles contain the geometries.
Inclusion is modeled as the shapely relation
intersects
(fully_contained
is false) orcontains
(otherwise) between the tile and the geometry.NaN
values or not all the series containing a value for a given index determine the resulting tile ID to beNaN
.- Parameters:
tile_ids – the tile IDs
geometries – a ``gpd.GeoSeries` with any geometric type
fully_contained – check if each geometry is fully contained in each tile
- Returns:
a
pd.Series
of booleans, if the geometries are inside the tiles- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.contains_point(tile_ids: Series, pts: GeoSeries) Series [source]#
Return if the tiles contains the points.
This method is more efficient than
contains_geometry
for points.The check includes the tile boundary, aligned with the way shapely
intersects
operates.NaN
values or not all the series containing a value for a given index determine the resulting tile ID to beNaN
.- Parameters:
tile_ids – the tile IDs
pts – the ``gpd.GeoSeries` with points
- Returns:
a
pd.Series
of booleans, if the points are inside the tiles- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.descendants(tile_ids: Series, level: int | None = None) Series [source]#
Return the tile IDs of all descendants at some level for each tile.
Index and
NaN
values are retained.NaN
is also returned in place of empty lists or in case of invalid tile IDs or tiling level.Use
pd.Series.explode
method to turn the lists into multiple rows.- Parameters:
tile_ids – the tile IDs
level – the tiling level
- Returns:
a
pd.Series
with the list of descendants tile IDs for each tile- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.from_coordinates(lngs: Series, lats: Series, level: int) Series [source]#
Return the tiles that contain points.
Series must be indexed the same.
NaN
values or series missing a row for some index value determine the resulting tile ID to beNaN
. This is also the case if a point can’t be mapped to a tile ID.Index is retained.
- Parameters:
lngs – the Series with longitudes
lats – the Series with latitudes
level – the tiling level
- Returns:
a
Series
tile IDs,NaN
when no tile ID can be calculated
- here.geopandas_adapter.geotiles.heretile.from_point(pts: GeoSeries, level: int) Series [source]#
Return the tiles that contain points.
NaN
values or rows not containing a Point determine the resulting tile ID to beNaN
. This is also the case if a point can’t be mapped to a tile ID.Index is retained.
- Parameters:
pts – the GeoSeries with the points
level – the tiling level
- Returns:
a
Series
tile IDs,NaN
when no tile ID can be calculated
- here.geopandas_adapter.geotiles.heretile.from_x_y_level(xs: Series, ys: Series, levels: Series) Series [source]#
Return the tiles given X and Y components and levels.
Series must be indexed the same.
NaN
values or series missing a row for some index value determine the resulting tile ID to beNaN
. This is also the case if not tile ID corresponds to a (x, y, level) tuple.Index is retained.
- Parameters:
xs – the Series with the tile X component
ys – the Series with the tile Y component
levels – the Series with tile levels
- Returns:
a
Series
tile IDs,NaN
when no tile ID can be calculated- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_boundary_ring(tile_ids: Series) GeoSeries [source]#
Return the boundary of the tiles as linear rings.
Each ring describes the boundary counter-clockwise. It contains 5 points, since a linear ring is always closed by repeating its first point.
Index and
NaN
values are retained by returningNone
.None
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
gpd.GeoSeries
of linear rings- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_bounds(tile_ids: Series) DataFrame [source]#
Return the bounds of the tiles.
This function returns bounds following the same convention of the
bounds
function of shapely.Index and
NaN
values are retained.NaN
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
DataFrame
with columnswest
,south
,east
,north
.NaN
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_center_coordinates(tile_ids: Series) DataFrame [source]#
Return the center points of the tiles.
Index and
NaN
values are retained.NaN
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a tuple of 2
Series
containing longitude and latitude,NaN
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_center_point(tile_ids: Series) GeoSeries [source]#
Return the center points of the tiles.
Index and
NaN
values are retained by returningNone
.None
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
GeoSeries
of points,None
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_corners(tile_ids: Series) GeoDataFrame [source]#
Return the southwestern and northeastern corners of the tiles.
Index and
NaN
values are retained by returningNone
.None
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
GeoDataFrame
with columnssouthwest
,northeast
.None
when not applicable # noqa- Raises:
ValueError – in case the series doesn’t contain integers or strings # noqa
- here.geopandas_adapter.geotiles.heretile.get_level(tile_ids: Series) Series [source]#
Return the levels of the tiles.
Index and
NaN
values are retained.NaN
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
Series
tiling levels,NaN
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_polygon(tile_ids: Series) GeoSeries [source]#
Return the tiles as polygons.
Index and
NaN
values are retained by returningNone
.None
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
gpd.GeoSeries
of polygons- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_x(tile_ids: Series) Series [source]#
Return the X components of the tiles.
Index and
NaN
values are retained.NaN
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
Series
of X components,NaN
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_x_y_level(tile_ids: Series) DataFrame [source]#
Return the X and Y components and the levels of the tiles.
Index and
NaN
values are retained.NaN
are also returned in case of invalid tile IDs.Resulting
NaN
values are removed, unlessdrop_na
is set to false.- Parameters:
tile_ids – the tile IDs
- Returns:
a
DataFrame
with columnsx
,y
,level
,NaN
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.get_y(tile_ids: Series) Series [source]#
Return the Y components of the tiles.
Index and
NaN
values are retained.NaN
are also returned in case of invalid tile IDs.- Parameters:
tile_ids – the tile IDs
- Returns:
a
Series
of Y components,NaN
when not applicable- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.in_geometry(geometries: GeoSeries, level: int, fully_contained: bool = False) Series [source]#
Return the tiles that are included in the geometries.
If
fully_contained
is false, some of the returned tiles may be partially outside the geometry. Otherwise, return only the tiles wholly inside the geometry.Inclusion is modeled as the shapely relation
intersects
(fully_contained
is false) orcontains
(otherwise) between the geometry and the tiles.Examples (
fully_contained
is false): - if the geometry is a point, return one, two or four tiles - if the geometry is a line string, it return all the tiles along the line - if the geometry is a polygon, it returns all the tiles intersecting with the polygon - for multi-geometries, return the union of the tiles in each geometryExamples (
fully_contained
is true): - if the geometry is a point, nothing is returned - if the geometry is a line string, nothing is returned - if the geometry is a polygon, it returns all the tiles contained in the polygon - for multi-geometries, return the union of the tiles in each geometryIndex and
NaN
values are retained.NaN
is also returned in place of empty lists.Use
pd.Series.explode
method to turn the lists into multiple rows.- Parameters:
geometries – the GeoSeries with arbitrary geometries
level – the tiling level
fully_contained – return only tiles wholly inside the bounding box
- Returns:
a
Series
with the list of tile IDs corresponding to each geometry, in the order of West to East first, then South to North
- here.geopandas_adapter.geotiles.heretile.in_geometry_bounds(geometries: GeoSeries, level: int, fully_contained: bool = False) Series [source]#
Return the tiles that are included in the bounds of geometries.
If
fully_contained
is false, some of the returned tiles may be partially outside the bounds. Otherwise, return only the tiles wholly inside the bounds.Index and
NaN
values are retained.NaN
is also returned in place of empty lists.Use
pd.Series.explode
method to turn the lists into multiple rows.- Parameters:
geometries – the GeoSeries with arbitrary geometries
level – the tiling level
fully_contained – return only tiles wholly inside the bounding box
- Returns:
a
Series
with the list of tile IDs corresponding to each geometry, in the order of West to East first, then South to North
- here.geopandas_adapter.geotiles.heretile.is_contained_in_geometry(tile_ids: Series, geometries: GeoSeries, fully_contained=False) Series [source]#
Return if the tiles are contained in the geometries.
Inclusion is modeled as the shapely relation
intersects
(fully_contained
is false) orcontains
(otherwise) between the geometry and the tile.- Parameters:
tile_ids – the tile IDs
geometries – a ``gpd.GeoSeries` with any geometric type
fully_contained – check if the tile is fully contained in the geometry
- Returns:
a
pd.Series
of booleans, if the tiles are contained in the geometries, fully or partially- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.is_descendant(tile_ids: Series, of_tile_ids: Series) Series [source]#
Check if tiles are the direct descendant of other tiles.
Index and
NaN
values are retained. Series should be indexed the same.- Parameters:
tile_ids – the subject tile IDs
of_tile_ids – check the relationship of the subjects with these tiles
- Returns:
a
pd.Series
containing if each tile is the descendant of the other tile- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.is_parent(tile_ids: Series, of_tile_ids: Series) Series [source]#
Check if tiles are the direct parents of other tiles.
Index and
NaN
values are retained. Series should be indexed the same.- Parameters:
tile_ids – the subject tile IDs
of_tile_ids – check the relationship of the subjects with these tiles
- Returns:
a
pd.Series
containing if each tile is the parent of the other tile- Raises:
ValueError – in case the series doesn’t contain integers # noqa
- here.geopandas_adapter.geotiles.heretile.is_valid(tile_ids: Series) Series [source]#
Check if integers are a valid tile IDs.
Index and
NaN
values are retained.- Parameters:
tile_ids – a Series of integers
- Returns:
a
Series
of booleans with the result of the test- Raises:
ValueError – in case the series doesn’t contain integers # noqa
Example: >>> is_valid(pd.Series([0, 1, 2, 3, 4])) 0 False 1 True 2 False 3 False 4 True dtype: bool
- here.geopandas_adapter.geotiles.heretile.neighbors(tile_ids: Series, level: int | None = None) Series [source]#
Return tile IDs of all neighbors on given level for tiles.
Index and
NaN
values are retained.NaN
is also returned in place of empty lists or in case of invalid tile IDs or tiling level.Use
pd.Series.explode
method to turn the lists into multiple rows.- Parameters:
tile_ids – the subject tile IDs
level – the tiling level
- Returns:
a
pd.Series
with the list of neighboring tile IDs- Raises:
ValueError – in case the series doesn’t contain integers # noqa