Skip to content

Map Tile API

Module for the HERE Map Tile API.

MapTileApi

Bases: HEREApi

A python interface into the HERE Map Tile API.

Source code in src/herepy/map_tile_api.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
class MapTileApi(HEREApi):
    """A python interface into the HERE Map Tile API."""

    def __init__(self, api_key: str = None, timeout: int = None):
        """
        Initialize a MapTileApi instance.

        Args:
          api_key (str):
            API key taken from HERE Developer Portal.
          timeout (int):
            Timeout limit for requests.

        """
        super().__init__(api_key, timeout)
        self._base_url = None

    def __get_error_from_response(self, json_data):
        if "error" in json_data:
            if json_data["error"] == "Unauthorized":
                return UnauthorizedError(json_data["error_description"])
        error_type = json_data.get("Type")
        error_message = json_data.get("Message", "Error occurred on " + sys._getframe(1).f_code.co_name)
        if error_type == "Invalid Request":
            return InvalidRequestError(error_message)
        else:
            return HEREError(error_message)

    def get_maptile(
        self,
        latitude: float,
        longitude: float,
        zoom: int,
        api_type: MapTileApiType = MapTileApiType.base,
        resource_type: MapTileResourceType = BaseMapTileResourceType.alabeltile,
        map_id: str = "newest",
        scheme: str = "normal.day",
        size: int = 256,
        tile_format: str = "png8",
        query_parameters: dict | None = None,
    ) -> bytes | None:
        """
        Return the map tile bytes for the given parameters.

        Args:
          latitude (float):
            Latitude value to be used to fetch map tile.
          longitude (float):
            Longitude value to be used to fetch map tile.
          zoom (int):
            Zoom level of the map image.
          api_type (MapTileApiType):
            MapTileApiType used to generate url.
          resource_type (MapTileResourceType):
            Resource type to download map tile.
          map_id (str):
            Specifies the map version, either newest or with a hash value.
            https://developer.here.com/documentation/map-tile/dev_guide/topics/map-versions.html
          scheme (str):
            Specifies the view scheme. A complete list of the supported schemes may be obtained
            by using the https://developer.here.com/documentation/map-tile/dev_guide/topics/resource-info.html
            resource.
          size (int):
            Returned image size. The following sizes ([width, height]) are supported:
            256 = [256, 256]
            512 = [512, 512]
            The following sizes ([width, height]) are deprecated, although usage is still accepted:
            128 = [128, 128]
          tile_format (str):
            Returned image format. The following image formats are supported:
            png – PNG format, 24 bit, RGB
            png8 – PNG format, 8 bit, indexed color
            jpg – JPG format at 90% quality
            Please note that JPG is recommended for satellite and hybrid schemes only.
          query_parameters (Optional[Dict]):
            Optional Query Parameters. Refer to the API definition for values.

        Returns:
          Map tile as bytes.

        Raises:
          HEREError

        """
        server = randrange(1, 4)
        column, row = MercatorProjection.get_column_row(latitude=latitude, longitude=longitude, zoom=zoom)
        url = str.format(
            "https://{}.{}.maps.ls.hereapi.com/maptile/2.1/{}/{}/{}/{}/{}/{}/{}",
            server,
            api_type.__str__(),
            resource_type.__str__(),
            map_id,
            scheme,
            zoom,
            column,
            row,
            size,
            tile_format,
        )
        if query_parameters:
            query_parameters.update({"apiKey": self._api_key})
        else:
            query_parameters = {"apiKey": self._api_key}
        url = Utils.build_url(url, extra_params=query_parameters)
        response = requests.get(url, timeout=self._timeout, stream=True)
        if isinstance(response.content, bytes):
            try:
                json_data = json.loads(response.content.decode("utf8"))
                if "error" in json_data:
                    error = self.__get_error_from_response(json_data)
                    raise error
            except UnicodeDecodeError:
                print("Map tile downloaded")
        return response.content

__init__(api_key=None, timeout=None)

Initialize a MapTileApi instance.

Parameters:

Name Type Description Default
api_key str

API key taken from HERE Developer Portal.

 None
timeout int

Timeout limit for requests.

 None
Source code in src/herepy/map_tile_api.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(self, api_key: str = None, timeout: int = None):
    """
    Initialize a MapTileApi instance.

    Args:
      api_key (str):
        API key taken from HERE Developer Portal.
      timeout (int):
        Timeout limit for requests.

    """
    super().__init__(api_key, timeout)
    self._base_url = None

get_maptile(latitude, longitude, zoom, api_type=MapTileApiType.base, resource_type=BaseMapTileResourceType.alabeltile, map_id='newest', scheme='normal.day', size=256, tile_format='png8', query_parameters=None)

Return the map tile bytes for the given parameters.

Parameters:

Name Type Description Default
latitude float

Latitude value to be used to fetch map tile.

 required
longitude float

Longitude value to be used to fetch map tile.

 required
zoom int

Zoom level of the map image.

 required
api_type MapTileApiType

MapTileApiType used to generate url.

 base
resource_type MapTileResourceType

Resource type to download map tile.

 alabeltile
map_id str

Specifies the map version, either newest or with a hash value. https://developer.here.com/documentation/map-tile/dev_guide/topics/map-versions.html

 'newest'
scheme str

Specifies the view scheme. A complete list of the supported schemes may be obtained by using the https://developer.here.com/documentation/map-tile/dev_guide/topics/resource-info.html resource.

 'normal.day'
size int

Returned image size. The following sizes ([width, height]) are supported: 256 = [256, 256] 512 = [512, 512] The following sizes ([width, height]) are deprecated, although usage is still accepted: 128 = [128, 128]

 256
tile_format str

Returned image format. The following image formats are supported: png – PNG format, 24 bit, RGB png8 – PNG format, 8 bit, indexed color jpg – JPG format at 90% quality Please note that JPG is recommended for satellite and hybrid schemes only.

 'png8'
query_parameters Optional[Dict]

Optional Query Parameters. Refer to the API definition for values.

 None

Returns:

Type Description
bytes | None

Map tile as bytes.
Source code in src/herepy/map_tile_api.py 
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def get_maptile(
    self,
    latitude: float,
    longitude: float,
    zoom: int,
    api_type: MapTileApiType = MapTileApiType.base,
    resource_type: MapTileResourceType = BaseMapTileResourceType.alabeltile,
    map_id: str = "newest",
    scheme: str = "normal.day",
    size: int = 256,
    tile_format: str = "png8",
    query_parameters: dict | None = None,
) -> bytes | None:
    """
    Return the map tile bytes for the given parameters.

    Args:
      latitude (float):
        Latitude value to be used to fetch map tile.
      longitude (float):
        Longitude value to be used to fetch map tile.
      zoom (int):
        Zoom level of the map image.
      api_type (MapTileApiType):
        MapTileApiType used to generate url.
      resource_type (MapTileResourceType):
        Resource type to download map tile.
      map_id (str):
        Specifies the map version, either newest or with a hash value.
        https://developer.here.com/documentation/map-tile/dev_guide/topics/map-versions.html
      scheme (str):
        Specifies the view scheme. A complete list of the supported schemes may be obtained
        by using the https://developer.here.com/documentation/map-tile/dev_guide/topics/resource-info.html
        resource.
      size (int):
        Returned image size. The following sizes ([width, height]) are supported:
        256 = [256, 256]
        512 = [512, 512]
        The following sizes ([width, height]) are deprecated, although usage is still accepted:
        128 = [128, 128]
      tile_format (str):
        Returned image format. The following image formats are supported:
        png – PNG format, 24 bit, RGB
        png8 – PNG format, 8 bit, indexed color
        jpg – JPG format at 90% quality
        Please note that JPG is recommended for satellite and hybrid schemes only.
      query_parameters (Optional[Dict]):
        Optional Query Parameters. Refer to the API definition for values.

    Returns:
      Map tile as bytes.

    Raises:
      HEREError

    """
    server = randrange(1, 4)
    column, row = MercatorProjection.get_column_row(latitude=latitude, longitude=longitude, zoom=zoom)
    url = str.format(
        "https://{}.{}.maps.ls.hereapi.com/maptile/2.1/{}/{}/{}/{}/{}/{}/{}",
        server,
        api_type.__str__(),
        resource_type.__str__(),
        map_id,
        scheme,
        zoom,
        column,
        row,
        size,
        tile_format,
    )
    if query_parameters:
        query_parameters.update({"apiKey": self._api_key})
    else:
        query_parameters = {"apiKey": self._api_key}
    url = Utils.build_url(url, extra_params=query_parameters)
    response = requests.get(url, timeout=self._timeout, stream=True)
    if isinstance(response.content, bytes):
        try:
            json_data = json.loads(response.content.decode("utf8"))
            if "error" in json_data:
                error = self.__get_error_from_response(json_data)
                raise error
        except UnicodeDecodeError:
            print("Map tile downloaded")
    return response.content