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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
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

    async def async_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 = await self._get_async_client().get(url, timeout=self._timeout)
        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

async_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) async

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 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
async def async_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 = await self._get_async_client().get(url, timeout=self._timeout)
    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

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