Module to operate with HERETile tiling scheme.

here.geotiles.heretile.ancestor(tile_id, level: int | None = None) → int | None[source]#

Return the ancestor tile at the given level for the given tile.

Parameters:

  • tile_id – the tile ID

  • level – the tiling level

Returns:

the tile ID of the ancestor or parent, when existing

here.geotiles.heretile.ancestors(tile_id, level: int | None = None) → OrderedDict[int, int][source]#

For a given tile_id return a dictionary of its ancestor levels and tile IDs.

If level is not provided the result contains tile IDs of all ancestors up to the largest “root” tile, else up to the specified level only.

Parameters:

  • tile_id – the tile ID

  • level – the tiling level

Returns:

an ordered dictionary with tile levels mapped to tile IDs

here.geotiles.heretile.between_points(south_west: Point, north_east: Point, level: int, fully_contained: bool = False) → Iterator[int][source]#

Return the tiles that are included the the bounding box identified by two points.

Parameters:

  • south_west – point at the south-western corner of the bounding box

  • north_east – point at the north-eastern corner of the bounding box

  • level – the tiling level

  • fully_contained – return only tiles wholly inside the bounding box

Returns:

the tile IDs in the order of West to East first, then South to North.

here.geotiles.heretile.contains_coordinates(tile_id, lng: float, lat: float) → bool[source]#

Return if the tile contains a point.

The check includes the tile boundary, aligned with the way shapely intersects operates. :param tile_id: the tile ID :param lng: longitude :param lat: latitude :return: if the point is inside the given tile

>>> tile = from_x_y_level(2, 1, 2)
>>> contains_coordinates(tile, 45, 45)
True
>>> contains_coordinates(tile, 0, 0)
True
here.geotiles.heretile.contains_geometry(tile_id, geometry: BaseGeometry, fully_contained=False) → bool[source]#

Return if the tile contains a geometry.

Inclusion is modeled as the shapely relation intersects (fully_contained is false) or contains (otherwise) between the tile and the geometry.

Parameters:

  • tile_id – the tile ID

  • geometry – any geometry

  • fully_contained – check if the geometry is fully contained in the tile

Returns:

if the geometry is contained in the given tile, fully or partially

here.geotiles.heretile.contains_point(tile_id, pt: Point) → bool[source]#

Return if the tile contains a point.

This method is more efficient than contains_geometry for points.

The check includes the tile boundary, aligned with the way shapely intersects operates.

Parameters:

  • tile_id – the tile ID

  • pt – a point

Returns:

if the point is inside the given tile

>>> tile = from_x_y_level(2, 1, 2)
>>> contains_point(tile, Point(90, 45))
True
>>> contains_point(tile, Point(0, 0))
True
here.geotiles.heretile.descendants(tile_id, level: int | None = None) → Iterator[int][source]#

Return the tile IDs of all descendants at some level for a given tile.

here.geotiles.heretile.from_coordinates(lng: float, lat: float, level: int) → int[source]#

Return the tile that contains a point.

Parameters:

  • lng – longitude

  • lat – latitude

  • level – the tiling level

Returns:

the tile ID

Raises:

ValueError – if no tile ID can correspond to the input parameters

>>> # Berlin main station
>>> from_coordinates(13.36937, 52.52507, 14)
377894440

Boundary conditions: at a given level, one points belongs to only one tile. For this purpose, the western and southern border of a tile is considered included in the tile, while eastern and norther borders are not. A point located on the border between two tiles belongs to only of the them.

>>> # Longitude boundary
>>> from_coordinates(90, 45, 2)
23
>>> # Latitude boundary
>>> from_coordinates(45, 0, 2)
22

If you’re interested in obtaining two or four tile IDs in case the point is on a border or corner of a tile, please use in_geometry.

here.geotiles.heretile.from_point(pt: Point, level: int) → int[source]#

Return the tile that contains a point.

Parameters:

  • pt – the point

  • level – the tile level

Returns:

the tile ID

>>> # Berlin main station
>>> p = Point(13.36937, 52.52507)
>>> from_point(p, 14)
377894440

Boundary conditions: at a given level, one points belongs to only one tile. For this purpose, the western and southern border of a tile is considered included in the tile, while eastern and norther borders are not. A point located on the border between two tiles belongs to only of the them.

>>> # Longitude boundary
>>> p = Point(90, 45)
>>> from_point(p, 2)
23
>>> # Latitude boundary
>>> p = Point(45, 0)
>>> from_point(p, 2)
22

If you’re interested in obtaining two or four tile IDs in case the point is on a border or corner of a tile, please use in_geometry.

here.geotiles.heretile.from_x_y_level(x: int, y: int, level: int) → int[source]#

Return the tile given X and Y components and level.

Parameters:

  • x – the tile X component

  • y – the tile Y component

  • level – the tiling level

Returns:

the tile ID

here.geotiles.heretile.get_boundary_ring(tile_id) → LinearRing[source]#

Return the boundary of given tile as linear ring. The ring describes the boundary counter-clockwise. It contains 5 points, since a linear ring is always closed by repeating its first point. :param tile_id: the tile ID :return: the tile boundary as linear ring

>>> lr = get_boundary_ring(23618402)
>>> lr.equals(LinearRing([(13.447265625, 52.470703125),
...     (13.447265625, 52.55859375),
...     (13.359375, 52.55859375),
...     (13.359375, 52.470703125),
...     (13.447265625, 52.470703125)
... ]))
True
here.geotiles.heretile.get_bounds(tile_id) → Tuple[float, float, float, float][source]#

Return the bounds of given tile.

This function returns bounds following the same convention of the bounds function of shapely.

Parameters:

tile_id – the tile ID

Returns:

the bounds, a tuple of 4 coordinates: (west, south, east, north)

>>> get_bounds(23618402)
(13.359375, 52.470703125, 13.447265625, 52.55859375)
here.geotiles.heretile.get_center_coordinates(tile_id) → Tuple[float, float][source]#

Return the center point of given tile.

Parameters:

tile_id – the tile ID

Returns:

the center point, a tuple of 2 coordinates: (longitude, latitude)

here.geotiles.heretile.get_center_point(tile_id) → Point[source]#

Return the center point of given tile.

Parameters:

tile_id – the tile ID

Returns:

the center point

here.geotiles.heretile.get_corners(tile_id) → Tuple[Point, Point][source]#

Return the southwestern and northeastern corners of given tile.

Parameters:

tile_id – the tile ID

Returns:

the corner points, a tuple of 2 points: (sw, ne)

here.geotiles.heretile.get_level(tile_id) → int[source]#

Return the level of a given tile.

Parameters:

tile_id – the tile ID

Returns:

the level of the tile ID

here.geotiles.heretile.get_polygon(tile_id) → Polygon[source]#

Return the given tile as polygon. :param tile_id: the tile ID :return: the tile as polygon

>>> p = get_polygon(23618402)
>>> p.equals(Polygon([(13.447265625, 52.470703125),
...     (13.447265625, 52.55859375),
...     (13.359375, 52.55859375),
...     (13.359375, 52.470703125),
...     (13.447265625, 52.470703125)
... ]))
True
here.geotiles.heretile.get_x(tile_id) → int[source]#

Return the X component of a given tile.

Parameters:

tile_id – the tile ID

Returns:

the X component of the tile ID

here.geotiles.heretile.get_x_y_level(tile_id) → Tuple[int, int, int][source]#

Return the X and Y components and level of a given tile.

Parameters:

tile_id – the tile ID

Returns:

the components and level, a tuple of 3 elements: (x, y, level)

here.geotiles.heretile.get_y(tile_id) → int[source]#

Return the Y component of a given tile.

Parameters:

tile_id – the tile ID

Returns:

the Y component of the tile ID

here.geotiles.heretile.in_bounding_box(west: float, south: float, east: float, north: float, level: int, fully_contained: bool = False) → Iterator[int][source]#

Return the tiles that are included the given bounding box.

If fully_contained is false, some of the returned tiles may be partially outside the bounding box. Otherwise, return only the tiles wholly inside the bounding box.

Parameters:

  • west – western border of the bounding box

  • south – southern border of the bounding box

  • east – eastern border of the bounding box

  • north – northern border of the bounding box

  • level – the tiling level

  • fully_contained – return only tiles wholly inside the bounding box

Yield:

the tile IDs in the order of West to East first, then South to North.

>>> next(in_bounding_box(
...     west=13.36937,
...     south=52.52507,
...     east=13.36938,
...     north=52.52508,
...     level=12
... ))
23618402
>>> list(in_bounding_box(
...     west=-115.81741,
...     south=46.16326,
...     east=-115.51230,
...     north=46.39060,
...     level=12,
...     fully_contained=True
... ))
[19681773, 19681784]
here.geotiles.heretile.in_geometry(geometry: BaseGeometry, level: int, fully_contained: bool = False) → Iterator[int][source]#

Return the tiles that are included in the given geometry.

Parameters:

  • geometry – an arbitrary geometry

  • level – the tiling level

  • fully_contained – return only tiles wholly inside the geometry

Returns:

iterator of tile IDs, in no particular order

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) or contains (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 geometry

Examples (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 geometry

here.geotiles.heretile.in_geometry_bounds(geometry: BaseGeometry, level: int, fully_contained: bool = False) → Iterator[int][source]#

Return the tiles that are included in the bounds of a geometry.

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.

Parameters:

  • geometry – an arbitrary geometry

  • level – the tiling level

  • fully_contained – return only tiles wholly inside the bounding box

Returns:

iterator of tile IDs in the order of West to East first, then South to North.

here.geotiles.heretile.is_contained_in_geometry(tile_id, geometry: BaseGeometry, fully_contained=False) → bool[source]#

Return if the tile is contained in a geometry.

Inclusion is modeled as the shapely relation intersects (fully_contained is false) or contains (otherwise) between the geometry and the tile.

Parameters:

  • tile_id – the tile ID

  • geometry – any geometry

  • fully_contained – check if the tile is fully contained in the geometry

Returns:

if the tile is contained in the given geometry, fully or partially

here.geotiles.heretile.is_descendant(tile_id, of_tile_id) → bool[source]#

Check if a tile is a direct descendant of another tile.

Parameters:

  • tile_id – the subject tile ID

  • of_tile_id – check the relationship of the subject with this tile ID

Returns:

if tile_id is a descendant of of_tile_id

here.geotiles.heretile.is_parent(tile_id, of_tile_id) → bool[source]#

Check if a tile is the direct parent of another tile.

Parameters:

  • tile_id – the subject tile ID

  • of_tile_id – check the relationship of the subject with this tile ID

Returns:

if tile_id is the parent of of_tile_id

here.geotiles.heretile.is_valid(tile_id) → bool[source]#

Check if an integer is a valid tile ID.

Parameters:

tile_id – an integer

Returns:

if the passed integer is a valid tile identifier

>>> # Valid tile IDs
>>> is_valid(1)
True
>>> is_valid(5)
True
>>> is_valid("5")
True
>>> is_valid(from_coordinates(13.3, 52.5, 7))
True
>>> # Invalid tile IDs
>>> is_valid(0)
False
>>> is_valid(7)
False
>>> is_valid("7")
False
>>> is_valid(from_coordinates(13.3, 52.5, 7) << 1)
False
here.geotiles.heretile.neighbors(tile_id, level: int | None = None) → Iterator[int][source]#

Return tile IDs of all neighbors on given level for the given tile.

Parameters:

  • tile_id – the subject tile ID

  • level – the tiling level

Yield:

neighboring tile IDs, in no particular order

here.geotiles.heretile.root() → int[source]#

Return the ID of the root tile.