Skip to content

Map Image API

MapImageApi (HEREApi)

A python interface into the HERE Map Image API

__init__(self, api_key=None, timeout=None) special

Returns a MapImageApi 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 herepy/map_image_api.py 
def __init__(self, api_key: str = None, timeout: int = None):
    """Returns a MapImageApi instance.
    Args:
      api_key (str):
        API key taken from HERE Developer Portal.
      timeout (int):
        Timeout limit for requests.
    """

    super(MapImageApi, self).__init__(api_key, timeout)
    self._base_url = "https://image.maps.ls.hereapi.com/mia/1.6/mapview"

get_mapimage(self, top_left=None, bottom_right=None, coordinates=None, city_name=None, country_name=None, center=None, encoded_geo_coordinate=None, encoded_geo_center_coordinate=None, image_format=<MapImageFormatType.png: 0>, image_height=None, show_position=False, maxhits=1, label_language='eng', second_label_language=None, house_number=None, zoom=8, map_scheme=None, uncertainty=None, nodot=None)

Retrieves the map image with given parameters.

Parameters:

Name Type Description Default
top_left List[float]

List contains latitude and longitude in order for the bounding box parameter. Note: If poi or poix are given, then this parameter is ignored. Note: If this parameter is provided, it ignores tx, tx.xy, ctr, ectr. Note: If this parameter is provided then the geo search parameters are ignored, such as co.

 None
bottom_right List[float]

List contains latitude and longitude in order for the bounding box parameter. Note: If poi or poix are given, then this parameter is ignored. Note: If this parameter is provided, it ignores tx, tx.xy, ctr, ectr. Note: If this parameter is provided then the geo search parameters are ignored, such as co.

 None
coordinates List[float]

List contains latitude and longitude in order.

 None
city_name Optional[str]

City name for address based search. UTF-8 encoded and URL-encoded.

 None
country_name Optional[str]

Country name for address based search. UTF-8 encoded and URL-encoded.

 None
center List[float]

Map center point geo coordinate. If the position is on the border of the map, the dot might be cropped.

 None
encoded_geo_coordinate str

Encoded equivalent of position geo coordinate parameter c. Parameter c is ignored if this parameter is specified.

 None
encoded_geo_center_coordinate str

Encoded equivalent of map center point geo coordinate parameter ctr. Parameter ctr is ignored if this parameter is present.

 None
image_format MapImageFormatType

Image format. It is possible to request the map image.

 <MapImageFormatType.png: 0>
image_height Optional[int]

Result image height in pixels, maximum 2048. Height and width parameter can be provided independently, i.e. there is no need to enter both to resize the image.

 None
show_position bool

Flag for showing address or position information box inside the map image (if address is available or position is allowed to be shown). Note: If geo search parameters such as co are provided, then the information shown is related to those parameter's values, if valid.

 False
maxhits int

Maximum number of search results to return. Applies only when some kind of search is performed which can return multiple results. Set to 1 to show directly the first matching result without any results listing.

 1
label_language str

Map label language. Specifies the language to be used to display descriptions of details inside the map image. If the parameter is not provided, the default language depends on the highest prioritized locale of the client's Accept-Language HTTP header which is currently supported. If no map language based on HTTP header can be determined, the server configured default is used. Note: Some MARC three-letter language codes are supported, please check https://developer.here.com/documentation/map-image/dev_guide/topics/resource-map.html for more details.

 'eng'
second_label_language Optional[str]

Second language to be used, only for dual labelling, therefore a ml language must also be present Map label language. Note: Some MARC three-letter language codes are supported, please check https://developer.here.com/documentation/map-image/dev_guide/topics/resource-map.html for more details.

 None
house_number Optional[str]

House number on the street for address based search.

 None
zoom int

Zoom level for the map image.

 8
map_scheme Optional[int]

Determines the map scheme to use for the map image.

 None
uncertainty Optional[str]

The parameter u specifies position uncertainty, which is shown as a filled circle around a location defined in terms of its latitude and longitude. The value of the parameter u indicates the radius of the circle representing uncertainty. In this case, the radius is set to 5 myriameters, which is 50000 meters.

 None
nodot Optional[bool]

If provided map image will be without dots.

 None

Returns:

Type Description

Map image as bytes.
Source code in herepy/map_image_api.py 
def get_mapimage(
    self,
    top_left: List[float] = None,
    bottom_right: List[float] = None,
    coordinates: List[float] = None,
    city_name: Optional[str] = None,
    country_name: Optional[str] = None,
    center: List[float] = None,
    encoded_geo_coordinate: str = None,
    encoded_geo_center_coordinate: str = None,
    image_format: MapImageFormatType = MapImageFormatType.png,
    image_height: Optional[int] = None,
    show_position: bool = False,
    maxhits: int = 1,
    label_language: str = "eng",
    second_label_language: Optional[str] = None,
    house_number: Optional[str] = None,
    zoom: int = 8,
    map_scheme: Optional[int] = None,
    uncertainty: Optional[str] = None,
    nodot: Optional[bool] = None,
):
    """Retrieves the map image with given parameters.
    Args:
      top_left (List[float]):
        List contains latitude and longitude in order for the bounding box parameter.
        Note: If poi or poix are given, then this parameter is ignored.
        Note: If this parameter is provided, it ignores tx, tx.xy, ctr, ectr.
        Note: If this parameter is provided then the geo search parameters are ignored, such as co.
      bottom_right (List[float]):
        List contains latitude and longitude in order for the bounding box parameter.
        Note: If poi or poix are given, then this parameter is ignored.
        Note: If this parameter is provided, it ignores tx, tx.xy, ctr, ectr.
        Note: If this parameter is provided then the geo search parameters are ignored, such as co.
      coordinates (List[float]):
        List contains latitude and longitude in order.
      city_name (Optional[str]):
        City name for address based search. UTF-8 encoded and URL-encoded.
      country_name (Optional[str]):
        Country name for address based search. UTF-8 encoded and URL-encoded.
      center (List[float]):
        Map center point geo coordinate. If the position is on the border of the map, the dot might be cropped.
      encoded_geo_coordinate (str):
        Encoded equivalent of position geo coordinate parameter c. Parameter c is ignored if this parameter is specified.
      encoded_geo_center_coordinate (str):
        Encoded equivalent of map center point geo coordinate parameter ctr. Parameter ctr is ignored if this parameter is present.
      image_format (MapImageFormatType):
        Image format. It is possible to request the map image.
      image_height (Optional[int]):
        Result image height in pixels, maximum 2048. Height and width parameter can be provided independently,
        i.e. there is no need to enter both to resize the image.
      show_position (bool):
        Flag for showing address or position information box inside the map image
        (if address is available or position is allowed to be shown).
        Note: If geo search parameters such as co are provided, then the information shown
        is related to those parameter's values, if valid.
      maxhits (int):
        Maximum number of search results to return. Applies only when some kind of search
        is performed which can return multiple results. Set to 1 to show directly the first
        matching result without any results listing.
      label_language (str):
        Map label language. Specifies the language to be used to display descriptions of details inside the map image.
        If the parameter is not provided, the default language depends on the highest prioritized locale of the
        client's Accept-Language HTTP header which is currently supported.
        If no map language based on HTTP header can be determined, the server configured default is used.
        Note: Some MARC three-letter language codes are supported, please check https://developer.here.com/documentation/map-image/dev_guide/topics/resource-map.html
        for more details.
      second_label_language (Optional[str]):
        Second language to be used, only for dual labelling, therefore a ml language must also be present Map label language.
        Note: Some MARC three-letter language codes are supported, please check https://developer.here.com/documentation/map-image/dev_guide/topics/resource-map.html
        for more details.
      house_number (Optional[str]):
        House number on the street for address based search.
      zoom (int):
        Zoom level for the map image.
      map_scheme (Optional[int]):
        Determines the map scheme to use for the map image.
      uncertainty (Optional[str]):
        The parameter u specifies position uncertainty, which is shown as a filled circle around a
        location defined in terms of its latitude and longitude. The value of the parameter u indicates
        the radius of the circle representing uncertainty. In this case, the radius is set to 5 myriameters,
        which is 50000 meters.
      nodot (Optional[bool]):
        If provided map image will be without dots.
    Returns:
      Map image as bytes.
    Raises:
      HEREError
    """

    data = {
        "z": zoom,
        "apiKey": self._api_key,
    }
    if top_left and bottom_right:
        data["bbox"] = str.format(
            "{0},{1};{2},{3}",
            top_left[0],
            top_left[1],
            bottom_right[0],
            bottom_right[1],
        )
    if coordinates:
        data["c"] = str.format("{0},{1}", coordinates[0], coordinates[1])
    if city_name:
        data["ci"] = city_name
    if country_name:
        data["co"] = country_name
    if center:
        data["ctr"] = str.format("{0},{1}", center[0], center[1])
    if encoded_geo_coordinate:
        data["e"] = encoded_geo_coordinate
    if encoded_geo_center_coordinate:
        data["ectr"] = encoded_geo_center_coordinate
    if map_scheme:
        data["t"] = map_scheme
    if uncertainty:
        data["u"] = uncertainty
    if nodot:
        data["nodot"] = None
    if image_height:
        data["h"] = image_height
    if house_number:
        data["n"] = house_number
    data["f"] = image_format._value_
    data["i"] = show_position
    data["maxhits"] = maxhits
    data["ml"] = label_language
    if second_label_language:
        data["ml2"] = second_label_language
    url = Utils.build_url(self._base_url, extra_params=data)
    response = requests.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 as err:
            print("Map image downloaded")
    return response.content